# Zamanlanmış Görevler

https://dev.wisecp.com/tr/zamanlanmis-gorevler

Zamanlanmış görevleri listeleyen, açıp kapatan ve elle çalıştıran dört uç.

## Genel Bakış

Zamanlanmış görev, kurulumun kendiliğinden yaptığı işlerin **tanımıdır**: fatura kesmek, hizmet askıya almak, bildirim göndermek. Bu dört uç görevleri listeler, işlerini gösterir, açıp kapatır ve elle çalıştırır.

Görev ile iş **aynı şey değildir**. Görev bir kuraldır; her koşusunda kuyruğa bir ya da daha çok iş bırakır. Görev listesindeki sayılar da o kuralın kuyruktaki işlerini anlatır.

Bazı görevler **iki aşamalı** çalışır: önce ne yapılacağını bulan bir aşama, sonra bulunanları yürüten bir aşama. Sayımlar ve süzgeçler bu ayrımı gözetir.

## Referans

### Görevleri Listeleme

get/api/v1/admin/automation/tasks

`Automation/GetAutomationTasks` admin

Kurulumdaki bütün zamanlanmış görevleri durumlarıyla döndürür.

Dönen alanlar data[] — 14

taskstringGörevin anahtarı. Diğer uçlarda bu değer kullanılır.

display_namestringGörevin görünen adı.

descriptionstringGörevin ne yaptığı.

frequencystringNe sıklıkta çalıştığı: `minute`, `hour`, `day`, `month`, `unknown`.

disabledboolGörevin kapatılmış olup olmadığı.

registeredboolGörevi yürütecek bir işleyicinin bulunup bulunmadığı. Yanlışsa görev listede durur ama çalışamaz.

last_run_atstring | nullSon çalıştığı an.

next_run_atstring | nullSonraki çalışma anı.

pendingintBekleyen iş sayısı.

processingintİşlenmekte olan iş sayısı.

today_completedintBugün tamamlanan iş sayısı. İki aşamalı görevde yalnız yürütme aşaması sayılır.

today_failedintDüşen iş sayısı. Kayıtların saklandığı süre boyunca sayılır.

last_errorstring | nullSon hata mesajı.

last_error_atstring | nullSon hatanın anı.

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/automation/tasks' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/automation/tasks', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();

const broken = data.filter((t) => ! t.registered);
```

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

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

```php
// KAPALI ile ISLEYICISI YOK ayri seylerdir: ikincisi bir kurulum eksigidir.
$tasks  = Api::Automation()->GetAutomationTasks()['data'];
$broken = array_filter($tasks, fn ($t) => ! $t['registered']);
```

### Görevin İşlerini Listeleme

get/api/v1/admin/automation/tasks/{task}/jobs

`Automation/GetAutomationTaskJobs` admin imleçli sayfalama

Tek bir göreve ait kuyruk işlerini döndürür.

Sorgu 5

status_filterstringDuruma göre süzer.

stage_filterstringAşamaya göre süzer. İki aşamalı görevlerde keşif ve yürütme ayrılır.

qstringSatırlarda serbest metin arar.

after_idintBu numaradan sonraki satırları getirir.

limitintKaç satır gelsin. Bir ile yüz arasına çekilir.

Dönen alanlar data — 3

rowsarrayİş satırları.

has_moreboolDaha fazla satır var mı.

next_afterintBir sonraki sayfa için verilecek numara.

Hatalar 2

task_required422Görev anahtarı verilmedi.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl 'https://panel.ornek.com/api/v1/admin/automation/tasks/invoice-create/jobs?limit=50' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const url = new URL(`https://panel.ornek.com/api/v1/admin/automation/tasks/${task}/jobs`);
url.searchParams.set('limit', '50');

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

// Sonraki sayfa: url.searchParams.set('after_id', data.next_after)
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/automation/tasks/' . $task . '/jobs?' . http_build_query(['limit' => 50]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Bu uc ILERI dogru gezer; genel besleme ise geriye. Ikisini karistirmayin.
$page = Api::Automation()->GetAutomationTaskJobs(['task' => $task], ['limit' => 50])['data'];
$next = Api::Automation()->GetAutomationTaskJobs(['task' => $task], [
    'after_id' => $page['next_after'],
]);
```

### Görevi Açma ve Kapatma

put/api/v1/admin/automation/tasks/{task}/status

`Automation/UpdateAutomationTaskStatus` admin

Bir görevin çalışıp çalışmayacağını belirler.

Gövde 1

enabledintreqGörevi açar ya da kapatır.

Dönen alanlar data — 2

taskstringGörevin anahtarı.

enabledboolGörevin yeni durumu.

Hatalar 4

enabled_required422Açık ya da kapalı bilgisi verilmedi.

task_required422Görev anahtarı verilmedi.

not_found404Görev bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl -X PUT 'https://panel.ornek.com/api/v1/admin/automation/tasks/invoice-create/status' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":0}'
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/automation/tasks/${task}/status`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ enabled: 0 }),
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/automation/tasks/' . $task . '/status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['enabled' => 0]),
]);

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

```php
// Kapatmak KUYRUKTAKI isleri silmez: bekleyenler gorev acilinca yeniden alinir.
Api::Automation()->UpdateAutomationTaskStatus(['task' => $task, 'enabled' => 0]);
```

### Görevi Hemen Çalıştırma

post/api/v1/admin/automation/tasks/{task}/run

`Automation/RunAutomationTask` admin sıraya alınır

Görevi zamanını beklemeden kuyruğa alır.

Gövde —

——Gövde gerekmez, boş gönderin. Hangi görevin çalışacağını adresteki görev anahtarı belirler.

Dönen alanlar data — 3

taskstringGörevin anahtarı.

dispatchedboolKuyruğa alındı mı. Görevin bittiği anlamına gelmez.

job_idintAçılan iş kaydının numarası.

Hatalar 4

task_required422Görev anahtarı verilmedi.

no_handler422Görev için işleyici yok.

blocked_by_gate422Bir kanca çalıştırmayı reddetti.

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/automation/tasks/invoice-create/run' \
  -H "Authorization: Bearer $API_KEY"
```

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

const { data } = await res.json();
console.log(data.job_id);
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/automation/tasks/' . $task . '/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
// Cagri KUYRUGA ATAR, calistirmaz; sonucu is numarasindan takip edin.
$jobId = Api::Automation()->RunAutomationTask(['task' => $task])['data']['job_id'];
$job   = Api::Automation()->GetAutomationJob(['queue' => 'cron', 'id' => $jobId])['data'];
```

## Tuzaklar

> **Kapalı olmakla işleyicisi olmamak ayrı şeylerdir**
> 
> Bir görev **kapatılmış** olabilir ya da onu yürütecek bir **işleyicisi hiç olmayabilir**. İkincisi bir tercih değil, kurulumdaki bir eksiktir: görev listede durur, hiç çalışmaz ve elle çalıştırma çağrısı da hata verir. İzleme yazarken iki alanı ayrı okuyun.

> **Hemen çalıştırmak hemen çalıştırmaz**
> 
> Çalıştırma ucu görevi **kuyruğa atar**; işi yapan zamanlanmış işçidir. Yanıt geri geldiğinde iş henüz başlamamış olabilir, dolayısıyla sonucu ölçmek için dönen iş numarasını takip etmeniz gerekir. İşçi ölmüşse iş hiç alınmaz ve sessizce bekler.

> **İki liste ters yönde gezer**
> 
> Görevin işleri ucu **ileriye** doğru sayfalar: verdiğiniz numaradan sonrakileri getirir. Genel iş beslemesi ise **geriye** doğru gider. İki ucu aynı döngüde kullanan bir kod, imleç alanlarını karıştırırsa ya hiç ilerlemez ya da aynı sayfayı döndürür.

> **Kapatmak kuyruğu boşaltmaz**
> 
> Görevi kapatmak **yeni iş bırakmasını** durdurur; kuyrukta bekleyen işleri silmez. Görevi yeniden açtığınızda o eski işler de alınır ve beklenmedik bir anda çalışır. Uzun süre kapalı kalacak bir görevde bekleyenleri ayrıca iptal etmeyi düşünün.

> **Bugünün sayıları farklı pencerelere bakar**
> 
> Görev listesindeki tamamlanan sayısı **bugünü**, düşen sayısı ise kayıtların saklandığı **tüm süreyi** kapsar. İkisini yan yana koyup bir başarı oranı hesaplamak yanlış çıkar. Aynı pencereye ait sayılar istiyorsanız görevin işlerini durum süzgeciyle kendiniz sayın.

## İlgili Makaleler

- [Otomasyon İşleri](https://dev.wisecp.com/tr/otomasyon-isleri)
- [Cron Ayarları](https://dev.wisecp.com/tr/cron-ayarlari)
- [Zamanlanmış Görev Ekleme](https://dev.wisecp.com/tr/zamanlanmis-gorev-ekleme)