他のシステムから Kitewell を呼び出す

Camunda、intra-mart、n8n などのワークフロー基盤や、ジョブスケジューラー、EAI ツールは、自分のフローのタスクの 1 つを Kitewell に任せられます。相手のシステムが Kitewell のワークフローを開始し、値を渡し、結果を受け取ります。Kitewell は、Web サイトやデスクトップアプリなど、API のない部分を受け持ちます。

方法は 2 つあります。相手のシステムが結果をどう受け取りたいかで選んでください。

	Webhook	REST API
実行の開始	ワークフローの Webhook URL への POST	POST /api/jobs/{id}/run
値の渡し方	リクエストの本文	リクエストの本文の params
結果の受け取り方	ワークフローの最後のステップが送る	実行を読み取る
コンピューターへの届き方	Kitewell のリレー経由で、設定は不要	自分で用意したアドレス
コンピューターがスリープ中のとき	リクエストはリレーで最大 7 日間待つ	呼び出しは届かない

必要なもの

• その仕事をする、保存済みのワークフロー。
• ワークフローがあるコンピューターで Kitewell が開いていること。実行が始まるのは、そのコンピューターがスリープしていない間だけです。
• Webhook の場合は、Kitewell が Dagu Cloud にサインインしていること。
• REST の場合は、ワークフローの実行 権限の API キー。作り方はこのコンピューターのアシスタントを接続するを参照してください。

Webhook で開始する

Webhook は、HTTP の POST を送ったら先へ進むシステムに向いています。ネットワークのポートを開ける必要はありません。

1. Webhook をオンにするの手順で、ワークフローの Webhook をオンにして URL をコピーします。
2. 相手のシステムに、その URL へ POST するステップを追加し、タスクに必要な値を JSON などで本文に入れます。
3. リクエストを 1 件送らせます。Kitewell の 最近のリクエスト で、そのリクエストの 詳細 を選び、このリクエストからステップを作る を選びます。アシスタントが、本文から値を取り出すステップを追加します。

ステップは本文を WEBHOOK_PAYLOAD から読みます。中身は送り手が送ったものそのままなので、信頼できないものとして扱ってください。ステップでリクエストを読むを参照してください。

リレーはすぐに 202 を返し、本文は {"id": "…"} のようになります。これはリクエストが届いたことを示すだけで、実行の結果ではありません。

Webhook で送り手を確かめるようにしていなければ、URL を知っている人なら誰でもワークフローを開始できます。URL はパスワードと同じように扱ってください。1 つの URL が受け付けるのは 1 分あたり 60 件までです。制限を参照してください。

REST API で開始する

REST は、実行を開始してから終わりまで見届けるシステムに向いています。すべてのリクエストに Authorization: Bearer <キー> を付けます。

1. GET /api/jobs でワークフローの ID を調べます。
2. POST /api/jobs/{id}/run で実行を開始します。値は params の下に、ワークフローの入力の名前で入れます。
3. キーが複数のプロジェクトに届く場合は、?projectId=<id> でプロジェクトを指定します。プロジェクトの指定を参照してください。

POST /api/jobs/{id}/run HTTP/1.1
Host: your-host
Authorization: Bearer <Kitewell API key>
Content-Type: application/json

{"params":{"region":"west"}}

Kitewell が待ち受けるのは 127.0.0.1:19742 で、このコンピューターからの接続だけです。別のサーバーにあるシステムには、HTTPS で到達できるアドレスが必要です。用意と運用はご自身で行い、自前のプロキシを使うか、Kitewell に証明書を設定します。別のコンピューターのクライアントを参照してください。

結果を受け取る

REST では、実行を読み取ります。GET /api/runs で実行の一覧を、GET /api/runs/{jobId}/{id} で 1 件を読み取れます。終わるまで繰り返し読み取ってください。GET /api/runs/{jobId}/{id}/logs は、ステップが書き出した内容を返します。stepId と stream=stdout を指定すると、結果を出力するステップだけを読めます。

Webhook では、ワークフロー自身が結果を送ります。最後に Web サービスを呼び出す ステップか、インポートした API のアクションを置き、相手のシステムを呼び出します。相手のシステムにはプロセス ID など自分の参照番号を本文に入れてもらい、その番号を結果と一緒に返します。

人の対応を待つステップがあるとき

ワークフローは、人の対応を待って止まることがあります。ステップの後の承認や、ステップの前に置いた 人に依頼する ステップです。人の判断を待つを参照してください。実行はそこで待ち、相手のシステムのタスクも一緒に待ちます。

そのステップは、どちらの側からでも進められます。

• 人が、Kitewell の 実行とログ → 待機中 で対応します。入力待ちの実行は、アラートで知らせることもできます。
• 相手のシステムが、ワークフローの実行 権限で REST から対応します。承認には POST /api/runs/{jobId}/{id}/approvals/{stepId}/approve、/reject、/push-back を、人によるタスクには POST /api/runs/{jobId}/{id}/human-tasks/{stepId}/complete を使います。

自前のタスク一覧を持つ基盤なら、承認をそこで利用者に見せ、その答えを Kitewell に渡せます。