> ## Documentation Index > Fetch the complete documentation index at: https://docs.jinba.io/llms.txt > Use this file to discover all available pages before exploring further. # API > 公開されたワークフローをAPI経由で呼び出す方法を学ぶ ## 概要 Jinba Flowは、公開されたワークフローをプログラムで実行できるREST APIエンドポイントを提供します。ワークフローが公開されると、外部システム、Webhook、またはHTTPリクエストを送信できる任意のアプリケーションから呼び出すことができます。 ## APIアクセス ### 前提条件 APIを使用するには、以下が必要です： 1. **公開されたワークフロー**: ワークフローが公開されている必要があります（[公開](/ja/pages/basics/publish)を参照） 2. **APIキー**: ワークフローを公開すると、APIキーが自動的に生成されます 3. **認証**: AuthorizationヘッダーでAPIキーを使用 ### APIエンドポイント #### 公開ワークフローの実行 **エンドポイント**: `POST /api/v2/external/flows/{flowId}/published-run` **認証**: Bearerトークン（APIキー） **リクエストボディ**: ```json theme={null} { "args": [ { "name": "input1", "value": "example value" } ], "mode": "sync" // または "async" } ``` **レスポンス**: ワークフロー実行結果 ## 認証 ### APIキー ワークフローを公開すると、APIキーが自動的に生成されます： * **自動生成**: 初めて公開するときに作成されます * **フロースコープ**: 各ワークフローには独自のAPIキーがあります * **安全な保存**: キーはワークスペースに安全に保存されます * **キーの表示**: ワークフロー設定からキーにアクセス ### APIキーの使用 AuthorizationヘッダーにAPIキーを含めます： ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` **セキュリティのベストプラクティス**: * APIキーを公開で共有しない * 環境変数にキーを安全に保存 * 侵害された場合は定期的にキーをローテーション * 異なる環境で異なるキーを使用 ## API経由でワークフローを呼び出す ### 同期実行 同期実行は、ワークフローが完了するまで待機してから返します： ```bash theme={null} 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" }' ``` **特徴**: * **ブロッキング**: リクエストは完了を待機します * **即座のレスポンス**: ワークフローが終了すると結果を返します * **タイムアウト**: 長時間実行されるワークフローではタイムアウトする場合があります * **ユースケース**: 即座の結果が必要な場合 ### 非同期実行 非同期実行は即座に返し、ワークフローをバックグラウンドで実行します： ```bash theme={null} 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を使用してステータスを確認 * **ユースケース**: 長時間実行されるワークフローまたはファイアアンドフォーゲットシナリオ ## 入力引数 ### 引数の形式 引数は名前と値のペアの配列として渡されます： ```json theme={null} { "args": [ { "name": "parameter_name", "value": "parameter_value" } ] } ``` ### 引数のタイプ 引数は以下にできます： * **文字列**: テキスト値 * **数値**: 数値 * **ブール値**: True/false値 * **オブジェクト**: 複雑なネストされたデータ構造 * **配列**: 値のリスト ### 引数の例 ```json theme={null} { "args": [ { "name": "email", "value": "user@example.com" }, { "name": "count", "value": 10 }, { "name": "options", "value": { "includeMetadata": true, "format": "json" } } ] } ``` ## レスポンス形式 ### 成功レスポンス ```json theme={null} { "status": "success", "result": { // ワークフロー出力 }, "stepOutputs": { "step_1": { "status": "success", "result": {} } } } ``` ### エラーレスポンス ```json theme={null} { "status": "failed", "error": { "name": "ErrorType", "value": "エラーメッセージ", "traceback": "スタックトレース" }, "stepOutputs": { "step_1": { "status": "failed", "error": { "name": "StepError", "value": "ステップエラーメッセージ" } } } } ``` ## API使用例 ### Pythonの例 ```python theme={null} 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の例 ```javascript theme={null} 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からワークフローを呼び出すことができます： ```bash theme={null} # 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 **原因**: 無効なリクエスト形式または必須引数の欠落 **解決策**: * リクエストボディの形式を確認 * すべての必須引数が提供されていることを確認 * 引数のタイプがワークフローの期待と一致することを確認 ### リトライロジック 本番アプリケーションでは、リトライロジックを実装します： ```python theme={null} 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に送信する前に入力を検証 ## 関連機能 * [公開](/ja/pages/basics/publish) - ワークフローの公開について学ぶ * [スケジューリング](/ja/pages/basics/scheduling) - ワークフローのスケジューリングについて学ぶ * [ワークスペース](/ja/pages/basics/workspace) - ワークスペース管理について学ぶ