REST APIで公開済みのJinba Flowを実行する

フローを公開し、そのトリガーパネルに表示されるエンドポイントを呼び出します。パネルには正確なURLと、そのフロー用のシークレットが表示されます。

公開フローのエンドポイントとシークレットキーを表示するトリガーパネル — トリガーパネルには公開フローのエンドポイント、シークレットキー、コピーして使えるcURLリクエストが表示されます

始める前に

呼び出すフローを公開します。
呼び出し元から値を受け取る場合は、値ごとにINPUT_*ステップを追加します。ステップIDが引数名になります。
フローのトリガーパネルでエンドポイントとシークレットキーをコピーします。

シークレットキーはパスワードと同様に扱ってください。安全に保管し、ソース管理に登録しないでください。

同期実行する

同期リクエストはフローの完了を待ちます。APIは実行ID、ステータス、ステップ出力を返します。トリガーパネルに表示されるURLとシークレットを設定して、リクエストを送信します。

export JINBA_FLOW_URL="https://api.jinba.io/api/v2/external/flows/FLOW_ID/published-run"
export JINBA_FLOW_KEY="YOUR_FLOW_SECRET"

curl -X POST "$JINBA_FLOW_URL" \
  -H "Authorization: Bearer $JINBA_FLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      { "name": "name", "value": "Jinba" }
    ],
    "mode": "sync"
  }'

FLOW_IDとYOUR_FLOW_SECRETをパネルの値に置き換えてください。name引数は、公開フロー内の入力ステップのIDと一致させます。modeは省略可能で、省略時はsyncになります。実行に成功すると、レスポンスのstatusは"success"になります。レスポンスには実行のidと、ステップIDをキーとするstepOutputsが含まれます。ツールごとに結果の形式は異なります。フローにOUTPUT_*ステップがある場合、その値はresultにも含まれます。実行が失敗した場合はstatus: "failed"が返ります。errorと、stepOutputs内の失敗したステップを確認してください。

コードからフローを呼び出す

以下の例では、URLとシークレットを同じ環境変数JINBA_FLOW_URLとJINBA_FLOW_KEYから読み込みます。 Python（requestsパッケージを使用）:

import os

import requests

response = requests.post(
    os.environ["JINBA_FLOW_URL"],
    headers={"Authorization": f"Bearer {os.environ['JINBA_FLOW_KEY']}"},
    json={
        "args": [{"name": "name", "value": "Jinba"}],
        "mode": "sync",
    },
)
response.raise_for_status()

run = response.json()
print(run["id"], run["status"])
print(run["stepOutputs"])

JavaScript（Node.js 18以降。call-flow.mjsなどESモジュールとして実行）:

const response = await fetch(process.env.JINBA_FLOW_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JINBA_FLOW_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    args: [{ name: "name", value: "Jinba" }],
    mode: "sync",
  }),
});
if (!response.ok) {
  throw new Error(`Flow request failed: ${response.status} ${await response.text()}`);
}

const run = await response.json();
console.log(run.id, run.status, run.stepOutputs);

どちらの例も、実行ID、ステータス、ステップ出力を表示します。2xx以外のレスポンスではエラーになります。

数値、JSON、Webhookのデータを渡す

引数のvalueはすべて文字列にする必要があります。数値、真偽値、オブジェクトを値として送るとリクエストは拒否されます。数値や真偽値は"10"や"true"のように文字列で送り、構造化データはJSON文字列に変換してください。たとえば、Webhookの受信側で受け取ったイベントをそのままフローに転送できます。ここでのwebhook_dataは、フロー内のINPUT_*ステップのIDです。

export async function forwardToFlow(event) {
  const response = await fetch(process.env.JINBA_FLOW_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JINBA_FLOW_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      args: [{ name: "webhook_data", value: JSON.stringify(event) }],
      mode: "async",
    }),
  });
  if (!response.ok) {
    throw new Error(`Flow request failed: ${response.status}`);
  }
  return response.json();
}

webhook_dataステップは、イベント全体をJSONテキストとして受け取ります。非同期モードにすると、受信側はフローの完了を待たずに応答でき、返されたidで実行を特定できます。 Jinba Flowに保存済みのファイルをフローに渡すには、INPUT_FILEステップの値としてjinbaflow://<fileId>を指定します。サーバーがフロー実行前にダウンロードURLへ解決します。解決されるのは、そのフローが属するワークスペース内のファイルだけです。これは実行時の引数でもフローのステップに保存した参照でも、またAPIキー・Webhook・Slackメッセージ・スケジュールのいずれから実行しても同じです。他のワークスペースのファイルへの参照は、フローの所有者やキーの作成者がそのワークスペースにアクセスできる場合でも、そのままフローに渡されます。

非同期実行する

フローをバックグラウンドで実行する場合は、modeにasyncを指定します。

{
  "args": [
    { "name": "name", "value": "Jinba" }
  ],
  "mode": "async"
}

レスポンスには実行のidとstatus: "running"が含まれます。実行レコードと結果を取得するには、認証済みのGETリクエストを次のURLに送信します。

https://api.jinba.io/api/v2/external/flow-runs/RUN_ID

この照会にはワークスペーススコープのAPIキーを使います。トリガーパネルのフロー専用シークレットは、公開フローの実行に使うもので、ワークスペースの実行履歴へのアクセスには使えません。ワークスペースAPIキーは、発行元のワークスペースでのみ使えます。あなたが他のワークスペースや組織のメンバーであっても、それらや組織設定・アカウント情報にはアクセスできず、GET /api/v2/workspaces（自分のワークスペース一覧）は404を返します。発行元のワークスペース内でも、APIキー・メンバー・招待・アクセス設定の管理、ワークスペースの公開範囲の変更、フローの共有やテンプレート公開、承認リクエストへの対応、チャットリレーの利用、ワークスペースのアーカイブ・凍結・復元・削除・別組織への移動はできません。これらの操作はログインして行ってください。

リクエストが失敗した場合

401 Unauthorized: Authorization: Bearerヘッダーにフローのシークレットが含まれているか確認します。
404 Not Found: フローIDが正しく、フローが公開済みか確認します。
フローは実行されるが入力が空: argsのnameがINPUT_*ステップの正確なIDと一致しているか確認します。
ステップでエラーが発生する: ステップ出力を調べ、ツールのドキュメントで必須入力、認証情報、権限を確認します。

Jinba Flow上でステップのエラーを調べる方法は実行エラーのデバッグを参照してください。

​始める前に

​同期実行する

​コードからフローを呼び出す

​数値、JSON、Webhookのデータを渡す

​非同期実行する

​リクエストが失敗した場合