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ı
| İzin | Varsayılan rol | İzin verir |
|---|---|---|
automation.read | Admin | Akışları, sürümleri, mesaj içerikleri olmadan çalışmaları, girdisiz başarısız mesajları, webhook’ları ve kullanımı okuma |
automation.manage | Admin | Akış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_privileged | Admin | Kontrol düzeyindeki bloklarla akışları dağıtma |
automation.debug | Admin | Ç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
| Metot | Yol | İzin | İşlevi |
|---|---|---|---|
| GET | /api/automation/flows | automation.read | Akışları listeler |
| POST | /api/automation/flows | automation.manage | İlk taslak olarak bir akış oluşturur (hiçbir zaman dağıtılmaz, kapalı) |
| GET | /api/automation/flows/{flowId} | automation.read | Akışı, dağıtılmış içeriğini ve paylaşılan taslağını getirir |
| PUT | /api/automation/flows/{flowId} | automation.manage | Paylaşılan taslağı kaydeder |
| PATCH | /api/automation/flows/{flowId} | automation.manage | Açıklamayı değiştirir |
| DELETE | /api/automation/flows/{flowId} | automation.manage | Siler (7 gün boyunca geri yüklenebilir) |
| DELETE | /api/automation/flows/{flowId}/draft | automation.manage | Taslağı atar |
| POST | /api/automation/flows/{flowId}/restore | automation.manage | Silinmiş bir akışı geri yükler; kapalı olarak geri döner |
| POST | /api/automation/flows/{flowId}/resume | automation.manage | Duraklatılmış bir akışı sürdürür |
| POST | /api/automation/flows/{flowId}/detach | automation.manage | Bir kuralın akışını kalıcı olarak sıradan bir akışa dönüştürür |
| GET | /api/automation/flows/{flowId}/versions | automation.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}/status | automation.read | Çalışan akışın canlı durumu |
| POST | /api/automation/deploy | automation.manage | Akışları ve işlemleri ya hep ya hiç dağıtır |
| POST | /api/automation/deploy/preflight | automation.manage | Aynı dağıtımın ne yapacağını, yapmadan gösterir |
| POST | /api/automation/test | automation.manage | Kaydedilmiş taslağı bir kez deneme çalıştırması olarak çalıştırır |
| GET | /api/automation/debug/runs?flowId= | automation.read | Bir akışın kayıtlı çalışmaları |
| GET | /api/automation/debug/runs/{runId} | automation.read | Adımlarıyla birlikte tek bir çalışma |
| GET | /api/automation/flows/{flowId}/hooks | automation.read | Akışın webhook’ları |
| POST | /api/automation/flows/{flowId}/hooks/{nodeId}/rotate | automation.manage | Tek bir webhook için yeni bir gizli anahtar |
| GET | /api/automation/dlq | automation.read | Başarısız mesajlar |
| POST | /api/automation/dlq/{entryId}/replay | automation.manage | Tek bir başarısız mesajı yeniden oynatır |
| DELETE | /api/automation/dlq/{entryId} | automation.manage | Tek bir başarısız mesajı atar |
| GET | /api/automation/export?ids= | automation.manage | Dağıtılmış akışları bir dosya olarak dışa aktarır |
| POST | /api/automation/import | automation.manage | Bir içe aktarmayı önizler, ardından onaylar |
| DELETE | /api/automation/import/{batchId} | automation.manage | Bir içe aktarmayı geri alır |
| GET, POST | /api/automation/emergency-stop | okuma: automation.read; değişiklik: automation.manage | Acil durdurma |
| GET | /api/automation/hosts | automation.read | Host’lar ve kuruluşunuzun bunları kullanıp kullanamayacağı |
| GET | /api/automation/blocks?host= | automation.read | Bir host üzerinde kullanılabilir bloklar |
| GET | /api/automation/usage | automation.read | Bu 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/flowsilehost,kind(flow),slug,name(en fazla 100 karakter), isteğe bağlıdescriptionvetemplategönderin. Yanıt201 { "flow" }olarak döner. Kullanımda olan bir slug409 slug_takendöner. - Taslağı kaydedin:
PUT /api/automation/flows/{flowId}ile{ "draftRev": n, "draft": <content> }gönderin; buradadraftRev, 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.
| Alan | Anlamı |
|---|---|
items | Yayı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 |
confirm | Akış 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}/replayyanıtı{ "replayed": true, "entryId" }biçimindedir; kayıt zaten yeniden oynatılmış veya atılmışsa404 gone, girdisi bozuksa404 unreadable,Retry-After: 30ile birlikte429 backpressuredö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/importisteği,{ "file", "choices": { "<slug>": "replace" }, "host": "generic" }gövdesiyle gönderilir.choices, zaten var olan her slug içinreplace,copyveyaskipdeğerini alır. Hiçbir şey yazılmaz;{ "preview" }yanıtı neyin değişeceğini, beraberinde gelen onayları ve 30 dakika geçerli birpreviewTokendeğerini içerir. - Kaydetme: aynı gövde ile birlikte
previewTokengö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 veskippedlistesinde 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:
| Durum | error | Anlamı |
|---|---|---|
| 400 | bad_request | İstek geçerli değil. Alan kurallarını bozan bir gövde, issues ile birlikte Validation error döner. |
| 403 | forbidden | Akışı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 |
| 404 | not_found | “Flow not found.” veya “Flow version not found.” |
| 409 | conflict | Siz okuduktan sonra biri yayınladı veya kaydetti; yayınlama yanıtı conflicts ve current içerir |
| 409 | in_use, slug_taken, owned_flow, not_owned | Bir 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 |
| 410 | expired | “The flow was deleted too long ago to restore.” |
| 413 | “The request body is too large.” | |
| 422 | invalid | Akış derlenmiyor; problems her birini listeler |
| 428 | confirm | Onaylar eksik; need bunları listeler |
| 503 | secrets_unavailable, owner_unavailable | Daha 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ır | Değer |
|---|---|
| Bir yayında öğeler ve işlemler | Her biri için 100 |
| Akış içeriği, taslak | Her biri için 1 MiB |
| İçe aktarma dosyası | 5 MiB |
| Yayın notu | 500 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ırma | 100 |
| Liste sayfası başına başarısız ileti | 200 |
| Silinmiş bir akışı geri yükleme | 7 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.

