メインコンテンツへスキップ

​
概要

Jinba Flowは、公開されたワークフローをプログラムで実行できるREST APIエンドポイントを提供します。ワークフローが公開されると、外部システム、Webhook、またはHTTPリクエストを送信できる任意のアプリケーションから呼び出すことができます。

​
APIアクセス

​
前提条件

APIを使用するには、以下が必要です：
  1. 公開されたワークフロー: ワークフローが公開されている必要があります（公開を参照）
  2. APIキー: ワークフローを公開すると、APIキーが自動的に生成されます
  3. 認証: AuthorizationヘッダーでAPIキーを使用

​
APIエンドポイント

​
公開ワークフローの実行

エンドポイント: POST /api/v2/external/flows/{flowId}/published-run 認証: Bearerトークン（APIキー） リクエストボディ: 
{
  "args": [
    {
      "name": "input1",
      "value": "example value"
    }
  ],
  "mode": "sync" // または "async"
}
レスポンス: ワークフロー実行結果

​
認証

​
APIキー

ワークフローを公開すると、APIキーが自動的に生成されます：
  • 自動生成: 初めて公開するときに作成されます
  • フロースコープ: 各ワークフローには独自のAPIキーがあります
  • 安全な保存: キーはワークスペースに安全に保存されます
  • キーの表示: ワークフロー設定からキーにアクセス

​
APIキーの使用

AuthorizationヘッダーにAPIキーを含めます： 
Authorization: Bearer YOUR_API_KEY
セキュリティのベストプラクティス:
  • APIキーを公開で共有しない
  • 環境変数にキーを安全に保存
  • 侵害された場合は定期的にキーをローテーション
  • 異なる環境で異なるキーを使用

​
API経由でワークフローを呼び出す

​
同期実行

同期実行は、ワークフローが完了するまで待機してから返します： 
curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      {"name": "input1", "value": "example"}
    ],
    "mode": "sync"
  }'
特徴:
  • ブロッキング: リクエストは完了を待機します
  • 即座のレスポンス: ワークフローが終了すると結果を返します
  • タイムアウト: 長時間実行されるワークフローではタイムアウトする場合があります
  • ユースケース: 即座の結果が必要な場合

​
非同期実行

非同期実行は即座に返し、ワークフローをバックグラウンドで実行します： 
curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      {"name": "input1", "value": "example"}
    ],
    "mode": "async"
  }'
特徴:
  • 非ブロッキング: 実行IDと共に即座に返します
  • バックグラウンド実行: ワークフローが非同期で実行されます
  • ステータス確認: 後で実行IDを使用してステータスを確認
  • ユースケース: 長時間実行されるワークフローまたはファイアアンドフォーゲットシナリオ

​
入力引数

​
引数の形式

引数は名前と値のペアの配列として渡されます： 
{
  "args": [
    {
      "name": "parameter_name",
      "value": "parameter_value"
    }
  ]
}

​
引数のタイプ

引数は以下にできます：
  • 文字列: テキスト値
  • 数値: 数値
  • ブール値: True/false値
  • オブジェクト: 複雑なネストされたデータ構造
  • 配列: 値のリスト

​
引数の例

{
  "args": [
    {
      "name": "email",
      "value": "user@example.com"
    },
    {
      "name": "count",
      "value": 10
    },
    {
      "name": "options",
      "value": {
        "includeMetadata": true,
        "format": "json"
      }
    }
  ]
}

​
レスポンス形式

​
成功レスポンス

{
  "status": "success",
  "result": {
    // ワークフロー出力
  },
  "stepOutputs": {
    "step_1": {
      "status": "success",
      "result": {}
    }
  }
}

​
エラーレスポンス

{
  "status": "failed",
  "error": {
    "name": "ErrorType",
    "value": "エラーメッセージ",
    "traceback": "スタックトレース"
  },
  "stepOutputs": {
    "step_1": {
      "status": "failed",
      "error": {
        "name": "StepError",
        "value": "ステップエラーメッセージ"
      }
    }
  }
}

​
API使用例

​
Pythonの例

import requests

url = "https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "args": [
        {"name": "input1", "value": "example"}
    ],
    "mode": "sync"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

​
JavaScript/Node.jsの例

const fetch = require('node-fetch');

const url = 'https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};
const body = {
  args: [
    { name: 'input1', value: 'example' }
  ],
  mode: 'sync'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(body)
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

​
Webhook統合

Webhookからワークフローを呼び出すことができます： 
# Webhookペイロードの例
curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      {"name": "webhook_data", "value": "{\"event\": \"user_signup\", \"user_id\": 123}"}
    ]
  }'

​
エラーハンドリング

​
一般的なエラー

​
401 Unauthorized

原因: 無効または欠落しているAPIキー 解決策: APIキーが正しく、Authorizationヘッダーに含まれていることを確認

​
404 Not Found

原因: ワークフローが見つからない、または公開されていない 解決策:
  • ワークフローIDが正しいことを確認
  • ワークフローが公開されていることを確認
  • ワークフローがアーカイブされていないことを確認

​
403 Forbidden

原因: APIキーがこのワークフローにアクセスできない 解決策: APIキーが正しいワークフローまたはワークスペースにスコープされていることを確認

​
400 Bad Request

原因: 無効なリクエスト形式または必須引数の欠落 解決策:
  • リクエストボディの形式を確認
  • すべての必須引数が提供されていることを確認
  • 引数のタイプがワークフローの期待と一致することを確認

​
リトライロジック

本番アプリケーションでは、リトライロジックを実装します： 
import time
import requests

def call_workflow_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data, timeout=30)
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:  # レート制限
                time.sleep(2 ** attempt)  # 指数バックオフ
                continue
            else:
                response.raise_for_status()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    return None

​
レート制限

APIリクエストはレート制限の対象となる場合があります：
  • レート制限: サブスクリプションプランに基づいて制限が適用される場合があります
  • 429ステータス: 制限を超えると429 Too Many Requestsを返します
  • Retry-After: ヘッダーは再試行するタイミングを示します
  • ベストプラクティス: リトライには指数バックオフを実装

​
APIキー管理

​
APIキーの表示

  1. 公開されたワークフローを開く
  2. ワークフロー設定に移動
  3. APIまたは公開設定セクションに移動
  4. APIキーを表示

​
APIキーの再生成

APIキーが侵害された場合：
  1. ワークフロー設定に移動
  2. APIセクションに移動
  3. APIキーを再生成
  4. 古いキーを使用しているすべてのアプリケーションを更新
重要: キーを再生成すると、古いキーは即座に無効になります。

​
ベストプラクティス

  1. 環境変数を使用: APIキーをコードではなく環境変数に保存
  2. エラーハンドリング: 適切なエラーハンドリングとリトライロジックを実装
  3. タイムアウト設定: API呼び出しに適切なタイムアウトを設定
  4. ログ記録: デバッグと監視のためにAPI呼び出しをログに記録
  5. セキュリティ: APIキーをバージョン管理にコミットしない
  6. 長時間タスクには非同期: 長時間実行されるワークフローには非同期モードを使用
  7. 入力検証: APIに送信する前に入力を検証

​
関連機能