# Modül Kuyruğu

https://dev.wisecp.com/tr/modul-kuyrugu

Modüllerin arka planda yaptığı işleri izleyen, yeniden deneyen ve temizleyen dokuz uç.

## Genel Bakış

Bir hizmet kurulurken, askıya alınırken ya da iptal edilirken modülün sağlayıcıyla konuşması gerekir. Bu konuşma isteği bekletmemek için **kuyruğa** alınır ve arka planda çalışır. Bu dokuz uç o kuyruğu izler ve müdahale eder.

Bir iş belirli sayıda denenir; o sayıya ulaşınca **düşer** ve kendiliğinden bir daha denenmez. Düşmüş bir işi tekrar sıraya almak ya da beklemeden çalıştırmak buradaki uçların işidir.

## Referans

### Kuyruğu Listeleme

get/api/v1/admin/tools/module-queue

`Tools/GetModuleQueue` admin sayfalı

Modüllere verilmiş ve arka planda çalışacak işleri döndürür.

Sorgu parametreleri 6

statusstringDuruma göre süzer.

module_namestringModül adına göre süzer.

actionstringİşleme göre süzer.

pageintVarsayılan 1.

limitintVarsayılan 25, en çok 100.

searchstringKayıtlarda arar.

Dönen alanlar data[] — 17

idintKuyruk öğesinin kimliği.

module_typestringModülün tipi.

module_namestringModülün adı.

actionstringYapılacak işlem.

statusstring`pending` sırada, `processing` çalışıyor, `completed` bitti, `failed` düştü.

service_idintİşlemin ilgili olduğu hizmet.

service_namestring | nullHizmetin adı.

user_idintMüşterinin kimliği.

user_full_namestring | nullMüşterinin adı.

addon_idint | nullEk hizmetin kimliği.

addon_namestring | nullEk hizmetin adı.

server_idint | nullSunucunun kimliği.

attemptsintKaç kez denendiği.

max_attemptsintEn çok kaç kez deneneceği. Bu sayıya ulaşınca öğe düşer ve kendiliğinden yeniden denenmez.

created_atstring | nullKuyruğa girdiği zaman.

updated_atstring | nullSon değişiklik zamanı.

next_retrystring | nullBir sonraki denemenin zamanı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -G 'https://panel.ornek.com/api/v1/admin/tools/module-queue' \
  -H "Authorization: Bearer $API_KEY" \
  -d status=failed
```

```javascript
const url = new URL('https://panel.ornek.com/api/v1/admin/tools/module-queue');
url.searchParams.set('status', 'failed');

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```

```php
$url = 'https://panel.ornek.com/api/v1/admin/tools/module-queue?' . http_build_query(['status' => 'failed']);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Liste kayitlari TASIMAZ: bir isin neden dustugunu gormek icin detayini okuyun.
$failed = Api::Tools()->GetModuleQueue([], ['status' => 'failed'])['data'];
```

### Kuyruk Sayaçları

get/api/v1/admin/tools/module-queue/stats

`Tools/GetModuleQueueStats` admin

Kuyruktaki işlerin durum bazında sayısını döndürür.

Dönen alanlar data — 5

totalintKuyruktaki toplam iş.

pendingintSırada bekleyen iş sayısı.

processingintŞu an çalışan iş sayısı.

completedintTamamlanmış iş sayısı.

failedintDüşmüş iş sayısı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/tools/module-queue/stats' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/stats', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/stats');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Izleme icin en ucuz uc budur: tum listeyi cekmeden kuyrugun saglıgini verir.
$stats = Api::Tools()->GetModuleQueueStats()['data'];

$stuck = $stats['failed'] > 0 || $stats['pending'] > 100;
```

### Öğe Detayı

get/api/v1/admin/tools/module-queue/{id}

`Tools/GetModuleQueueItem` admin kayıtlar burada

Tek bir işi, sağlayıcıyla yapılan görüşmelerin kaydıyla birlikte döndürür.

Dönen alanlar data — 19

idintKuyruk öğesinin kimliği.

module_typestringModülün tipi.

module_namestringModülün adı.

actionstringYapılacak işlem.

statusstring`pending` sırada, `processing` çalışıyor, `completed` bitti, `failed` düştü.

service_idintİşlemin ilgili olduğu hizmet.

service_namestring | nullHizmetin adı.

user_idintMüşterinin kimliği.

user_full_namestring | nullMüşterinin adı.

addon_idint | nullEk hizmetin kimliği.

addon_namestring | nullEk hizmetin adı.

server_idint | nullSunucunun kimliği.

attemptsintKaç kez denendiği.

max_attemptsintEn çok kaç kez deneneceği. Bu sayıya ulaşınca öğe düşer ve kendiliğinden yeniden denenmez.

created_atstring | nullKuyruğa girdiği zaman.

updated_atstring | nullSon değişiklik zamanı.

next_retrystring | nullBir sonraki denemenin zamanı.

api_logsarraySağlayıcıyla yapılan istek ve yanıtlar. Listede yer almaz, ağır olduğu için yalnız burada.

process_logsarrayİşin kendi adım kayıtları.

Hatalar 3

invalid_id422Kimlik geçerli değil.

not_found404Kuyruk öğesi bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/tools/module-queue/101' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/101', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/101');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Yeniden denemeden ONCE kayitlari okuyun: ayni kosul surerse is ayni yerde duser.
$item = Api::Tools()->GetModuleQueueItem(['id' => 101])['data'];
$last = end($item['api_logs']);
```

### Öğeyi Yeniden Deneme

post/api/v1/admin/tools/module-queue/{id}/retry

`Tools/RetryModuleQueueItem` admin sıraya alır

Düşmüş bir işi tekrar sıraya alır ve deneme sayacını sıfırlar.

Gövde —

——Gövde gerekmez. İş, path parametresiyle belirlenir; boş gövde gönderin.

Dönen alanlar data

dataobjectİşin sıfırlama sonrası hâli. Öğe detayı ucuyla aynı şekildedir.

Hatalar 3

not_found404Kuyruk öğesi bulunamadı.

not_failed422Yalnız düşmüş işler yeniden denenebilir.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/module-queue/101/retry' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/101/retry', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/101/retry');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Yeniden deneme isi HEMEN calistirmaz: siraya alir, arka plan gorevi devrali r.
// Beklemeden gormek istiyorsaniz calistirma ucunu kullanin.
Api::Tools()->RetryModuleQueueItem(['id' => 101]);
```

### Öğeyi Hemen Çalıştırma

post/api/v1/admin/tools/module-queue/{id}/run

`Tools/RunModuleQueueItem` admin anında çalışır

İşi arka planı beklemeden o anda çalıştırır ve sonucunu döndürür.

Gövde —

——Gövde gerekmez. İş, path parametresiyle belirlenir; boş gövde gönderin.

Dönen alanlar data — 3

task_successboolİş başarılı oldu mu.

task_messagestringDüştüyse hata mesajı.

itemobjectİşin çalıştırma sonrası hâli.

Hatalar 3

not_found404Kuyruk öğesi bulunamadı.

not_runnable422Yalnız sırada bekleyen ya da düşmüş işler çalıştırılabilir.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/module-queue/101/run' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/101/run', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/101/run');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Is DUSSE bile istek 200 doner: basari 'task_success' alanindadir.
$result = Api::Tools()->RunModuleQueueItem(['id' => 101])['data'];

if (!$result['task_success']) {
    $why = $result['task_message'];
}
```

Yanıt 200

```json
{
  "data": {
    "task_success": false,
    "task_message": "Provider refused: quota exceeded.",
    "item": {
      "id": 101,
      "status": "failed",
      "attempts": 3,
      "max_attempts": 3
    }
  }
}
```

### Öğeyi Silme

delete/api/v1/admin/tools/module-queue/{id}

`Tools/DeleteModuleQueueItem` admin kanca korumalı

Bir işi kuyruktan çıkarır. İş yapılmamış olarak kalır.

Dönen alanlar data — 2

deletedboolSilme başarılı mı.

idintSilinen öğenin kimliği.

Hatalar 3

not_found404Kuyruk öğesi bulunamadı.

blocked_by_gate422`gate:module.queue_intervene` kancası işlemi veto etti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/tools/module-queue/101' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/101', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/101');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Silmek isi IPTAL eder: hizmet kurulmayi bekliyorsa beklemeye devam eder.
Api::Tools()->DeleteModuleQueueItem(['id' => 101]);
```

### Toplu Silme

post/api/v1/admin/tools/module-queue/bulk-delete

`Tools/BulkDeleteModuleQueue` admin kanca korumalı

Birden çok işi kuyruktan çıkarır.

Gövde 1

idsint[]zorunluSilinecek öğelerin kimlikleri.

Dönen alanlar data — 3

deletedboolSilme çalıştı mı.

countintKabul edilen kimlik sayısı. Aşağıdaki listenin uzunluğudur, veritabanından yeniden sayılmaz.

idsint[]Silinmek üzere kabul edilen kimlikler. Artık var olmayan kimlikler de geri döner, yani bu liste neyin silindiğinin teyidi değildir.

Hatalar 3

ids_required422Hiç kimlik verilmedi.

blocked_by_gate422`gate:module.queue_intervene` kancası işlemi veto etti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/module-queue/bulk-delete' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"ids":[101,102,103]}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/bulk-delete', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ids: [101, 102, 103] }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/bulk-delete');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['ids' => [101, 102, 103]]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kimlik listesi gonderdiginiz gibi doner: artik var olmayanlar da elenmez, geri gelir.
$response = Api::Tools()->BulkDeleteModuleQueue(['ids' => [101, 102, 103]]);

$echoed = $response['data']['ids'];
```

### Tüm Düşenleri Yeniden Deneme

post/api/v1/admin/tools/module-queue/retry-all-failed

`Tools/RetryAllFailedModuleQueue` admin kuyruğun tamamı

Kuyruktaki bütün düşmüş işleri tekrar sıraya alır.

Gövde —

——Gövde gerekmez. İşlem kuyruğun tamamını kapsar ve daraltılamaz; boş gövde gönderin.

Dönen alanlar data — 1

retriedboolİşlem çalıştı mı. Kaç işin sıraya alındığını söylemez.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/module-queue/retry-all-failed' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/retry-all-failed', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/retry-all-failed');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kac isin siraya alindigini bu uc soylemez; oncesi ve sonrasi sayaclarla olculur.
$before = Api::Tools()->GetModuleQueueStats()['data']['failed'];
Api::Tools()->RetryAllFailedModuleQueue();
$after  = Api::Tools()->GetModuleQueueStats()['data']['failed'];
```

### Tamamlananları Temizleme

post/api/v1/admin/tools/module-queue/clear-completed

`Tools/ClearCompletedModuleQueue` admin

Tamamlanmış işleri kuyruktan siler.

Gövde —

——Gövde gerekmez. İşlem kuyruğun tamamını kapsar ve daraltılamaz; boş gövde gönderin.

Dönen alanlar data — 1

clearedboolTemizlik çalıştı mı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/module-queue/clear-completed' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/module-queue/clear-completed', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/module-queue/clear-completed');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Temizlik TAMAMLANANLARI alir; dusmus isler yerinde kalir ve incelenmeyi bekler.
Api::Tools()->ClearCompletedModuleQueue();
```

## Tuzaklar

> **Çalıştırma başarısızlığı 200 içinde döner**
> 
> Hemen çalıştırma ucu, iş düşse bile `200` döndürür; başarı bilgisi yanıttaki alandadır. Yalnız durum koduna bakan bir istemci başarısız bir kurulumu başarılı sayar. Hata mesajı da aynı yanıtta gelir.

> **Yeniden deneme ile çalıştırma aynı şey değildir**
> 
> Yeniden deneme işi **sıraya alır**: deneme sayacı sıfırlanır ve arka plan görevi sırası geldiğinde çalıştırır. Çalıştırma ucu ise işi **o anda** yapar ve sonucu döndürür. Sonucu görmek istiyorsanız ikincisini kullanın.

> **Silmek işi iptal eder**
> 
> Bir kuyruk öğesini silmek yalnız kaydı temizlemez: o iş **hiç yapılmaz**. Kurulmayı bekleyen bir hizmet beklemeye devam eder ve bunu size kimse hatırlatmaz. Bu yüzden silme bir kancayla korunur; kurulumunuz o kancayı kullanıyorsa istek reddedilebilir.

> **Neden düştüğü listede değildir**
> 
> Sağlayıcıyla yapılan görüşmelerin kaydı ağır olduğu için listeden çıkarılır; yalnız tek öğe detayında gelir. Bir işi yeniden denemeden önce o kaydı okuyun, çünkü aynı koşul sürüyorsa iş aynı yerde yine düşer.

> **Toplu uçlar sayı vermez**
> 
> Tüm düşenleri yeniden deneme ve tamamlananları temizleme uçları yalnız çalıştıklarını söyler; kaç işe dokunduklarını **bildirmez**. Etkiyi ölçmek istiyorsanız öncesinde ve sonrasında sayaçları okuyun.

## İlgili Makaleler

- [Bildirim Kuyruğu](https://dev.wisecp.com/tr/bildirim-kuyrugu)
- [Kayıt Defterleri](https://dev.wisecp.com/tr/kayit-defterleri)
- [Hizmet Yaşam Döngüsü](https://dev.wisecp.com/tr/hizmet-yasam-dongusu)