Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Akışlar API’si

Akışları REST üzerinden oluşturun, kaydedin, yayınlayın, test edin, geri alın, geri yükleyin ve dışa aktarın; çalışmalarını ve webhook'larını okuyun ve başarısız iletileri yeniden oynatın.

Bu yollar bir programın otomasyon motorunun akışlarıyla çalışmasını sağlar: akışları sürüm kontrolünde tutmak ve dağıtmak, geri almak, çalışmaları izlemek ve başarısız mesajları yönetmek. Akışların uygulamada nasıl çalıştığı Flows ve Versions, testing and rollback sayfalarında anlatılır.

Yollar https://<your host>/tenant/<tenantId> altındadır. Her çağrıda Authorization: Bearer <API key> gönderin; bkz. Authentication. Bu API’deki zamanlar, epoch’tan itibaren milisaniye cinsindendir.

İzinler ve API anahtarları

İzinVarsayılan rolİzin verir
automation.readAdminAkışları, sürümleri, mesaj içerikleri olmadan çalışmaları, girdisiz başarısız mesajları, webhook’ları ve kullanımı okuma
automation.manageAdminAkışları oluşturma, kaydetme, dağıtma, silme, geri yükleme, test etme, içe ve dışa aktarma; başarısız mesajları yeniden oynatma ve atma
automation.manage_privilegedAdminKontrol düzeyindeki bloklarla akışları dağıtma
automation.debugAdminÇalışmalardaki ve başarısız mesajlardaki mesaj içeriklerini görme; kaydedilmiş mesajlar ve canlı durum üzerinden test etme

Bir API anahtarı dördünü birden tutabilir. Bir dağıtım, akışın bloklarının ihtiyaç duyduğu izinleri de ister: Send command bloğu, komutun düzeyinin gönderme iznini gerektirir (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical); komut yüksek etkili olduğunda ayrıca automation.manage_privileged gerekir. Ham bir komut metodu iot_rpc.send.raw iznini gerektirir; bu izne yalnızca bir Owner sahiptir ve hiçbir anahtar sahip olamaz, dolayısıyla bir anahtar ham metod gönderen bir akışı dağıtamaz.

Bir akış bir host‘a aittir: generic (General host) ya da iot (IoT host). Bkz. Hosts, the root flow and profile root flows.

Yollar

MetotYolİzinİşlevi
GET/api/automation/flowsautomation.readAkışları listeler
POST/api/automation/flowsautomation.manageİlk taslak olarak bir akış oluşturur (hiçbir zaman dağıtılmaz, kapalı)
GET/api/automation/flows/{flowId}automation.readAkışı, dağıtılmış içeriğini ve paylaşılan taslağını getirir
PUT/api/automation/flows/{flowId}automation.managePaylaşılan taslağı kaydeder
PATCH/api/automation/flows/{flowId}automation.manageAçıklamayı değiştirir
DELETE/api/automation/flows/{flowId}automation.manageSiler (7 gün boyunca geri yüklenebilir)
DELETE/api/automation/flows/{flowId}/draftautomation.manageTaslağı atar
POST/api/automation/flows/{flowId}/restoreautomation.manageSilinmiş bir akışı geri yükler; kapalı olarak geri döner
POST/api/automation/flows/{flowId}/resumeautomation.manageDuraklatılmış bir akışı sürdürür
POST/api/automation/flows/{flowId}/detachautomation.manageBir kuralın akışını kalıcı olarak sıradan bir akışa dönüştürür
GET/api/automation/flows/{flowId}/versionsautomation.readİçeriksiz, en yeniden eskiye dağıtılmış sürümler
GET/api/automation/flows/{flowId}/versions/{version}automation.readİçeriğiyle birlikte tek bir sürüm
GET/api/automation/flows/{flowId}/statusautomation.readÇalışan akışın canlı durumu
POST/api/automation/deployautomation.manageAkışları ve işlemleri ya hep ya hiç dağıtır
POST/api/automation/deploy/preflightautomation.manageAynı dağıtımın ne yapacağını, yapmadan gösterir
POST/api/automation/testautomation.manageKaydedilmiş taslağı bir kez deneme çalıştırması olarak çalıştırır
GET/api/automation/debug/runs?flowId=automation.readBir akışın kayıtlı çalışmaları
GET/api/automation/debug/runs/{runId}automation.readAdımlarıyla birlikte tek bir çalışma
GET/api/automation/flows/{flowId}/hooksautomation.readAkışın webhook’ları
POST/api/automation/flows/{flowId}/hooks/{nodeId}/rotateautomation.manageTek bir webhook için yeni bir gizli anahtar
GET/api/automation/dlqautomation.readBaşarısız mesajlar
POST/api/automation/dlq/{entryId}/replayautomation.manageTek bir başarısız mesajı yeniden oynatır
DELETE/api/automation/dlq/{entryId}automation.manageTek bir başarısız mesajı atar
GET/api/automation/export?ids=automation.manageDağıtılmış akışları bir dosya olarak dışa aktarır
POST/api/automation/importautomation.manageBir içe aktarmayı önizler, ardından onaylar
DELETE/api/automation/import/{batchId}automation.manageBir içe aktarmayı geri alır
GET, POST/api/automation/emergency-stopokuma: automation.read; değişiklik: automation.manageAcil durdurma
GET/api/automation/hostsautomation.readHost’lar ve kuruluşunuzun bunları kullanıp kullanamayacağı
GET/api/automation/blocks?host=automation.readBir host üzerinde kullanılabilir bloklar
GET/api/automation/usageautomation.readBu ayın çalışmaları, adımları ve betik süresi ile planınıza göre akışlar

Akışları listeleme ve okuma

GET /api/automation/flows sayfalamayı 1’den başlatır; varsayılan 50 satır, en fazla 100. Filtreler: host, kind, state (virgülle ayrılmış listeler; durumlar running, disabled, invalid, not_approved, paused), enabled, owned (kural akışları için true, sıradan olanlar için false), updatedFrom / updatedTo (gün), search, deleted=true (son 7 günün silinmiş akışları), ids. Sıralama alanları: name, slug, host, kind, state, enabled, version, updatedAt, createdAt, deletedAt, sortOrder. Yanıt { "flows": [...], "data": [...], "total": n, "page": 1, "pageSize": 50 } biçimindedir; data aynı satırları içerir.

Bir akış satırında flowId, host, slug (akışın sabit kimliği, ^[a-z0-9_-]{1,32}$), name, description, enabled, state, stateReason, version (dağıtılmış sürüm; ilk dağıtımdan önce 0), draftRev, deletedAt, createdAt, updatedAt bulunur ve Rules kartının sahip olduğu bir akış için ownerModule de bulunur.

GET /api/automation/flows/{flowId} şu yapıyla yanıt verir: { "flow", "current", "draft", "permissions" }; current content alanıyla birlikte dağıtılmış sürümdür, draft paylaşılan taslaktır, permissions ise çağıranın sahip olduğu automation.manage, automation.manage_privileged ve automation.debug izinlerini gösterir.

İçerik, taslaklar ve akış oluşturma

Akış içeriği { "id": "<slug>", "name": "…", "nodes": [...], "edges": [...] } biçimindedir. Bir düğüm { "id", "type", "params", "name"?, "disabled"? }, bir kenar ise { "from", "from_port", "to" } biçimindedir. Blok türleri ve parametreleri GET /api/automation/blocks?host=generic ile listelenir ve Trigger blocks bölümünden itibaren açıklanır. Geçerli içerik elde etmenin en kolay yolu, düzenleyicide bir akış oluşturup GET /api/automation/flows/{flowId} ile okumaktır.

  • Oluştur: POST /api/automation/flows ile host, kind (flow), slug, name (en fazla 100 karakter), isteğe bağlı description ve template gönderin. Yanıt 201 { "flow" } olarak döner. Kullanımda olan bir slug 409 slug_taken döner.
  • Taslağı kaydedin: PUT /api/automation/flows/{flowId} ile { "draftRev": n, "draft": <content> } gönderin; burada draftRev, okuduğunuz revizyondur. Yanıt yeni revizyonla { "draftRev" } döner; bir sonraki kaydetmede bunu gönderin. Arada başka biri kaydettiyse: 409 { "error": "conflict", "draftRev", "by", "at", "theirs" }. Taslak asla çalışmaz.

Yayınla

POST /api/automation/deploy, istediğiniz sayıda akışı ve işlemi tek seferde yayınlar; ya hepsi ya hiçbiri uygulanır.

AlanAnlamı
itemsYayınlanacak akışlar: host, kind, content, enabled, isteğe bağlı note (en fazla 500 karakter). Mevcut bir akış için flowId ve baseVersion (okuduğunuz sürüm; hiç yayınlanmadıysa 0). flowId yoksa yeni bir akış oluşturulur.
opsİşlemler: { "op": "enable", "flowId" }, disable, delete, { "op": "rollback", "flowId", "version" }, resume, set_root, unset_root
confirmAkış slug’ına göre onaylarınız: { "<slug>": { "check": true } } veya { "<slug>": { "typed": "<flow name>" } }

En fazla 100 öğe ve 100 işlem; her akışın içeriği en fazla 1 MiB. Her öğede enabled alanını açıkça gönderin.

curl -X POST "https://<your host>/tenant/<tenantId>/api/automation/deploy" \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"flowId":"9e8f…","baseVersion":4,"host":"generic","kind":"flow","enabled":true,"note":"Raise the threshold","content":{"id":"tank-alert","name":"Tank alert","nodes":[],"edges":[]}}]}'

Yanıt { "deployRev", "versions": [ { "flowId", "slug", "kind", "version", "approved" } ], "plan", "dropped", "warnings"?, "notified" } biçimindedir. notified: false, değişikliğin kaydedildiği ve iş süreçlerinin bunu bir dakika içinde alacağı anlamına gelir.

Onaylar

Riskli bloklar içeren bir akışın onaylanması gerekir; tıpkı editörün yayınlama penceresinde olduğu gibi. Onay olmadan yayınlama 428 yanıtı verir:

{ "error": "confirm", "need": [ { "flow": "tank-alert", "name": "Tank alert", "level": "typed", "kinds": ["external"], "reasons": [ { "node": "n4", "type": "action.rpc", "risk": "external", "text": "…" } ], "permission": "automation.manage" } ] }

Aynı gövdeyi confirm ile tekrar gönderin: check düzeyi için { "check": true }, typed düzeyi için ise { "typed": "Tank alert" } (akışın adı, birebir). Bir onay, aynı üyenin aynı içeriğini bir sonraki yayınlamasına geçerlidir; dolayısıyla değişmemiş içeriği yeniden yayınlamak onay istemez.

Yayınlamadan yanıtı görmek için aynı gövdeyle POST /api/automation/deploy/preflight kullanın: hiçbir şey yazılmaz, kilitlenmez ve denetim kaydı tutulmaz.

Sürümler ve geri alma

GET .../versions yanıtı { "versions": [ { "version", "at", "by", "note", "mode", "hashShort", "approvedBy" } ] } biçimindedir. Geri almak için { "ops": [ { "op": "rollback", "flowId": "9e8f…", "version": 3 } ] } yayınlayın. Geri alma, eski içeriğe sahip yeni bir sürümdür ve aynı yetkileri ve onayları gerektirir. Sürümlerin ne kadar süre saklandığı için bkz. Sürümler, test ve geri alma.

Taslağı test edin

POST /api/automation/test, kayıtlı taslağı bir kez kuru çalıştırma olarak çalıştırır: dış dünyada işlem yapan bloklar ne yapacaklarını belirtir; hiçbir şey yazılmaz veya gönderilmez.

{ "flowId": "9e8f…", "mode": "flow", "nodeId": "trigger-1", "input": { "msgType": "inject", "payload": { "level": 92 }, "originator": { "type": "tenant", "id": "<tenantId>" } } }

mode, flow (tetikleyici nodeId üzerinden girer) ya da node (yalnızca nodeId çalışır) olabilir. Bir mesaj yerine input, { "sample": "declaration" } (bloğun örneği) olabilir veya automation.debug ile { "sample": "last_run" } ya da { "fromRun": { "runId", "step" } } olabilir. Yanıt steps, outputs, would, errors, ms, truncated ve state alanlarını içerir. Bir test 2 saniye veya 200 adımda durur. Her üye dakikada 10 test çalıştırabilir; aksi halde Retry-After ile birlikte 429 rate_limited döner.

Çalıştırmalar ve durum

GET /api/automation/debug/runs?flowId=<flowId or slug>, kayıtlı çalıştırmaları en yeniden eskiye doğru listeler. Filtreler: nodeId, status (ok, error, left_open, dropped), msgType, originatorType, originatorId, port, from ve to (milisaniye), limit (en fazla 100) ve cursor (önceki sayfanın next değeri). automation.debug olmadan satırlar mesaj içerikleri olmadan gelir. Yalnızca akışın kayıt düzeyinin tuttukları listelenir; bkz. Akışlarda sorun giderme. Kuruluşunuzda aynı anda üçüncü bir tarama yapılırsa 429 döner.

GET /api/automation/flows/{flowId}/status yanıtı { "status" } biçimindedir: çalışan akışın en son bildirdiği düğüm durum satırları, sayaçlar, hız ve kuyruk; ilk bildirimden önce ise null. Editörün canlı akışı yalnızca oturum açmış kişiler içindir; bir program bunun yerine bu rotayı sorgular.

Webhook’lar

GET /api/automation/flows/{flowId}/hooks, yayınlanmış ve açık bir akışın webhook tetikleyicilerini listeler: { "hooks": [ { "nodeId", "hookId", "auth", "reply", "path" } ] }. Yanıt hiçbir zaman gizli anahtar içermez.

POST .../hooks/{nodeId}/rotate yeni bir gizli anahtar üretir ve bunu yalnızca bir kez gösterir: { "hookId", "secret", "previousValidHours": 24 }. Eski gizli anahtar 24 saat boyunca çalışmaya devam eder; hemen sonlandırmak için { "revokePrevious": true } gönderin. session webhook’unun gizli anahtarı yoktur (409 no_secret).

Bir webhook’u çağıran program API anahtarı kullanmaz: Tetikleyici blokları altında Webhook başlığında anlatıldığı gibi, hook’un kendi gizli anahtarını kullanır.

Başarısız mesajlar

GET /api/automation/dlq, başarısız mesajları en yeniden eskiye doğru listeler; pageSize en fazla 200 (varsayılan 50). Sonraki sayfa için next değerini before olarak (ya da firstSeenAt:asc ile sıralıyorsanız after olarak) gönderin; kuyruğun sonunda next null olur. Filtreler: reason (tenant_backlog, decode_failed, poison, host_refused, run_abandoned, retries_exhausted, expired), flow (bir slug), host (varsayılan generic). Yanıt total, byReason (en yeni 900 kayıt üzerinden sayılır), entries ve next alanlarını içerir. Her girdi id, reason, error, firstSeenAt, deliveries alanlarına sahiptir; automation.debug ile birlikte özgün girdi fields içinde gelir.

  • POST /api/automation/dlq/{entryId}/replay yanıtı { "replayed": true, "entryId" } biçimindedir; kayıt zaten yeniden oynatılmış veya atılmışsa 404 gone, girdisi bozuksa 404 unreadable, Retry-After: 30 ile birlikte 429 backpressure döner.
  • DELETE /api/automation/dlq/{entryId} yanıtı { "discarded": true } olur.

IoT host’unun kuyruğu için ?host=iot ekleyin. Yeniden oynatma, ilk denemenin yaptığı işi tekrarlayabilir; bkz. Korumalar ve başarısız mesajlar.

Dışa ve içe aktarma

  • Dışa aktarma: GET /api/automation/export?ids=<flowId>,<flowId> (1 ila 100), her akışın yayınlanmış sürümünü ve kullandığı bağlantıları içeren { "file", "skipped" } yanıtını verir. Gizli bilgiler dosyada hiçbir zaman yer almaz.
  • Önizleme ile içe aktarma: POST /api/automation/import isteği, { "file", "choices": { "<slug>": "replace" }, "host": "generic" } gövdesiyle gönderilir. choices, zaten var olan her slug için replace, copy veya skip değerini alır. Hiçbir şey yazılmaz; { "preview" } yanıtı neyin değişeceğini, beraberinde gelen onayları ve 30 dakika geçerli bir previewToken değerini içerir.
  • Kaydetme: aynı gövde ile birlikte previewToken gönderilir. 201 { "imported": { "importBatchId", … } } yanıtı döner. İçe aktarılan akışlar kapalı ve onaylanmamış olarak gelir; gizli bilgilerini yeniden girin, ardından akışları yayınlayın.
  • Geri alma: DELETE /api/automation/import/{importBatchId} (planı görmek için ?dryRun=true). İçe aktarmadan sonra yayınlanmış bir akış olduğu gibi bırakılır ve skipped listesinde gösterilir.

Dosya en fazla 5 MiB olabilir. Önizlemeden sonra bir şey yayınlandıysa kaydetme 409 stale_preview yanıtı verir; 30 dakika sonra 409 preview_expired, gövde ile token eşleşmezse 409 token_mismatch yanıtı verir. Her durumda yeniden önizleme yapın.

Kurallar kartının kurallarından oluşan akışlar

Kurallar kartındaki bir kural, akış API’sinin ownerModule ile listelediği bir akış olarak çalışır. Bunu kaydetmek, yayınlamak, silmek veya değiştirmek 409 owned_flow yanıtı verir: bunun yerine kuralı Kurallar API’si üzerinden değiştirin. POST .../detach ise bunu kalıcı olarak sıradan bir akışa dönüştürür: kural silinir ve akış bundan sonra planınızın akış sınırına dahil edilir.

Hatalar

Otomasyon rotalarının reddettiği istekler, olağan alanların yanında bir error kodu taşır:

DurumerrorAnlamı
400bad_requestİstek geçerli değil. Alan kurallarını bozan bir gövde, issues ile birlikte Validation error döner.
403forbiddenAkışın bir bloğu, anahtarın sahip olmadığı bir yetki gerektiriyor (missing)
403(yok)Bir plan sınırı: details.key değeri max_flows veya max_script_blocks, ayrıca limit, current, adding ile
404not_found“Flow not found.” veya “Flow version not found.”
409conflictSiz okuduktan sonra biri yayınladı veya kaydetti; yayınlama yanıtı conflicts ve current içerir
409in_use, slug_taken, owned_flow, not_ownedBir kök veya başka bir akış tarafından hâlâ kullanılıyor (uses); slug mevcut; bir kuralın akışı; bir kuralın akışı değil
410expired“The flow was deleted too long ago to restore.”
413“The request body is too large.”
422invalidAkış derlenmiyor; problems her birini listeler
428confirmOnaylar eksik; need bunları listeler
503secrets_unavailable, owner_unavailableDaha sonra yeniden deneyin

Genel hata gövdesi ve istek sınırları için Hatalar ve istek sınırları bölümüne bakın.

Sınırlar

SınırDeğer
Bir yayında öğeler ve işlemlerHer biri için 100
Akış içeriği, taslakHer biri için 1 MiB
İçe aktarma dosyası5 MiB
Yayın notu500 karakter
Akış adı, açıklaması100, 1.000 karakter
TestlerÜye başına dakikada 10; her biri için 2 saniye ve 200 adım
Liste sayfası başına çalıştırma100
Liste sayfası başına başarısız ileti200
Silinmiş bir akışı geri yükleme7 gün içinde
Yenilemeden sonra eski webhook gizli anahtarı24 saat

Plan sınırları ve çalışan akışların sınırları Akış sınırları sayfasındadır.