> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 人間の入力 API 連携フロー

> 一時停止中の人間の入力フォームを API で扱うエンドツーエンドのフロー

ワークフローが [人間の入力](/ja/3.10.x/use/nodes/human-input) ノードに到達すると一時停止し、ストリーミングレスポンスから `human_input_required` イベントが送出されます。このイベントが運ぶ `form_token` を使って、ワークフローが再開するまでフォームのライフサイクルを進めます。

各エンドポイントのリファレンスは [人間の入力 API](/ja/3.10.x/develop/api/human-input/get-human-input-form) を参照してください。

## フロー

以下のフローは Workflow アプリと Chatflow アプリの両方に共通します。両者は手順 1 のエントリエンドポイントだけが異なります。

<Steps>
  <Step title="アプリをストリーミングモードで起動">
    1. Workflow アプリは [ワークフローを実行](/ja/3.10.x/develop/api/workflow-runs/run-workflow) を、Chatflow アプリは [チャットメッセージを送信](/ja/3.10.x/develop/api/chat-messages/send-chat-message) を呼び出します。その際、エンドユーザーの `user` 識別子を渡します。
    2. SSE ストリームで `human_input_required` イベントを監視し、その `form_token` を取得します。

       `form_token` が `null` の場合、フォームはメール配信を使用しており、API から操作できません（[配信方法の前提](#配信方法の前提) を参照）。

       `human_input_required` イベントには実行の `workflow_run_id` も含まれます。手順 4 で監視を再開する必要がある場合に備えて、保持しておきます。
  </Step>

  <Step title="フォーム定義を取得">
    `form_token` を指定して [人間の入力フォームを取得](/ja/3.10.x/develop/api/human-input/get-human-input-form) エンドポイントを呼び出します。レスポンスにはレンダリング済みの Markdown、入力フィールド定義、利用可能なアクション、事前入力済みのデフォルト値が含まれます。`expiration_time` を過ぎると、フォームは送信できなくなります。フォームを受信者に表示します。

    フォームが送信前に期限切れになった場合、一時停止中の実行はノードに設定されたタイムアウト動作に従います。再開後のストリームには `human_input_form_filled` ではなく `human_input_form_timeout` が含まれます。
  </Step>

  <Step title="応答を送信">
    [人間の入力フォームを送信](/ja/3.10.x/develop/api/human-input/submit-human-input-form) エンドポイントを呼び出し、受信者の入力値、選択された `action`、そして `user` を送ります。`action` は手順 2 のフォーム定義に含まれるアクションのいずれかである必要があります。

    送信が成功すると確定し、フォームは閉じられ、ワークフローは該当するアクション分岐から再開するため、同じ `form_token` で再送信することはできません。

    送信が拒否された場合（無効なアクションや必須入力の欠落）、フォームはそのまま変わりません。入力を修正し、同じ `form_token` で再送信してください。
  </Step>

  <Step title="ワークフローの監視を継続">
    元の SSE ストリームが切断されている場合は、[ワークフローイベントをストリーム](/ja/3.10.x/develop/api/workflow-runs/stream-workflow-events) で再接続します。手順 1 の `workflow_run_id` と、実行を開始したときと同じ `user` を指定してください。`user` が異なると 404 が返されます。

    再開後のストリームには、送信を確認する `human_input_form_filled`（フォームが期限切れの場合は `human_input_form_timeout`）が含まれます。その後は一時停止しなかった実行と同じように、残りのノードイベントを完了までストリーミングします。

    実行済みノードのステータスを先に再送するには、`include_state_snapshot=true` を付けます。ワークフローに人間の入力ノードが複数連続する場合、ストリームはデフォルトで一時停止のたびに閉じます。`continue_on_pause=true` を渡すと、1 つのストリームですべての一時停止をまたいで接続を維持できます。
  </Step>
</Steps>

## 配信方法の前提

人間の入力 API は、人間の入力ノードで WebApp 配信方法が設定されたフォームのみを対象とします。メール配信のみのフォームは、API に `form_token` を公開しません。

## 例：フォームの送信

このフォームには、`feedback` 段落入力と `approve` / `reject` アクションがあるものとします。

1. [人間の入力フォームを取得](/ja/3.10.x/develop/api/human-input/get-human-input-form) エンドポイントを呼び出してフォーム定義を取得します。

   ```http theme={null}
   GET /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   ```

   フォーム定義が返ります。

   ```json theme={null}
   {
     "form_content": "Please review the draft and confirm or request changes.",
     "inputs": [
       {
         "type": "paragraph",
         "output_variable_name": "feedback",
         "default": {
           "type": "constant",
           "selector": [],
           "value": ""
         }
       }
     ],
     "resolved_default_values": {},
     "user_actions": [
       {
         "id": "approve",
         "title": "Approve",
         "button_style": "primary"
       },
       {
         "id": "reject",
         "title": "Request changes",
         "button_style": "default"
       }
     ],
     "expiration_time": 1745510400
   }
   ```

2. [人間の入力フォームを送信](/ja/3.10.x/develop/api/human-input/submit-human-input-form) エンドポイントを呼び出し、受信者の入力と選択されたアクションを送ります。

   ```http theme={null}
   POST /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   Content-Type: application/json

   {
     "inputs": {
       "feedback": "公開して問題ありません"
     },
     "action": "approve",
     "user": "abc-123"
   }
   ```

   `{}` が返ります。ワークフローは `approve` 分岐から再開します。

3. [ワークフローイベントをストリーム](/ja/3.10.x/develop/api/workflow-runs/stream-workflow-events) で実行のストリームに再接続し、完了まで追跡します。上記フローの最後の手順と同様です。