Validate Payload

基本的な使い方​

Validate Payload は API 呼び出しで渡されたデータが正しいかを確認します。API の門番として働き、形式の整ったデータだけを後続の処理へ通します。

主な役割​

1. 構造の検証: JSON Schema で受け取ったデータの形、型、必須項目を確認します
2. アップロードの確認: アップロードされたファイルの種類と形式（画像、動画、文書など）を検証します
3. フローの保護: 不正または悪意あるデータが後続の処理に届くのを防ぎます

処理の流れ​

• 検証成功: データが通り、ワークフローが続きます。検証済みのデータは prevPayload として後続のプロセッサーで利用できます
• 検証失敗: データが拒否され、エラーの経路に進み、prevError 変数にエラー情報が記録されます

押さえておく点​

• これは Automation Tool ワークフローの必須の入口で、すべての API ツールはここから始まります
• Response プロセッサーと対になって、一つの API ツールを構成します
• 文字列長、数値の範囲、列挙値など、細かな検証規則に対応しています
• 入れ子構造の特定の部分だけを検証できます

設定項目​

Name​

キャンバス上に表示される名前です。ワークフロー内でこのプロセッサーを識別するために使います。

Description​

このプロセッサーの用途を補足し、ワークフローの読みやすさを高めます。

Properties​

Schema（必須）​

入力を検証する JSON Schema です。API リクエストが満たすべき構造、型、制約を定義します。

Path​

検証する範囲を JSON Path 構文で指定します。既定値は $ で、ルートオブジェクト全体を対象とします。Automation Tool では読み取り専用です。

File Requirements​

アップロードされるファイルの要件で、件数、種類、形式を確認します。

• File Alias: ファイルに変数名を与えます。検証が通ると、その名前でファイル情報にアクセスできます
• File Type: 種類を制限します。IMAGE、VIDEO、AUDIO、DOCUMENT、BINARY に対応しています

Workflow CRD での設定​

- name: proc-validate
  type: validate-payload
  labels:
    display_name: 入力の検証
  configs:
    - name: path
      value: $.prevPayload
    - name: schema
      value: |-
        {
          "type": "object",
          "required": ["order_id"],
          "properties": {
            "order_id": {
              "type": "string",
              "description": "照会する注文番号"
            }
          }
        }

path の既定値は $.prevPayload で、直前のノードが渡した payload 全体を検証します。その中の一項目だけを検証したい場合は、JSONPath をより深く指定します（たとえば $.prevPayload.order）。

schema は JSON Schema の文字列です。ノードを新規に追加すると foo という項目だけの見本 schema が入っているので、実務では全体を差し替えます。

接続関係​

Success​

構造の検証が通り、ファイルの要件も満たされると、この接続点から次へ進みます。検証済みのデータは prevPayload として利用でき、ファイルの別名変数も作られます。

Failure​

検証に失敗した場合、またはファイルの要件を満たさない場合、この接続点から続き、prevError 変数にエラー情報が入ります。

適用範囲​

Validate Payload は Automation Tool 型のワークフローにのみ適用され、Bot 型には使えません。Response プロセッサーと対になり、Validate Payload が入力を、Response が出力を担います。

使用例​

API アクセスのツール​

外部 API にアクセスするツールです。Validate Payload が呼び出し側のパラメータ（ID など）を確認し、HTTP Request が API を呼び、Response が結果を返します。

schema の例:

{
  "type": "object",
  "properties": {
    "todoId": {
      "type": "string",
      "description": "照会する Todo の ID"
    }
  },
  "required": ["todoId"]
}

画像認識のツール​

画像を認識するツールです。Validate Payload がユーザーの質問とアップロードされた画像の形式を確認し、視覚に対応した LLM が認識し、結果を返します。

schema の例:

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "ユーザーの質問"
    }
  },
  "required": ["question"]
}

File Requirements:

• File Type: IMAGE
• File Alias: img

複数のデータ源をまとめるツール​

複数のデータ源をまとめる API ツールです。Validate Payload が必要なパラメータを確認し、データベースと外部 API から順にデータを取得し、まとめて返します。

schema の例:

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "ユーザー ID"
    },
    "category": {
      "type": "string",
      "enum": ["A", "B", "C"],
      "description": "照会する分類"
    }
  },
  "required": ["userId", "category"]
}

schema の設計​

よく使う検証規則​

{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 150
    },
    "category": {
      "type": "string",
      "enum": ["A", "B", "C"]
    }
  }
}

ファイルの種類​

• IMAGE: JPEG、PNG、GIF などの画像
• VIDEO: MP4、MOV などの動画
• AUDIO: MP3、M4A、WAV などの音声
• DOCUMENT: PDF、DOCX、TXT などの文書
• BINARY: 種類を判別できないバイナリ

出力変数​

検証に成功すると、後続のプロセッサー向けに次が生成されます。

• prevPayload: 検証済みのデータオブジェクト
• ファイルの別名変数: blobId、fileType、fileName、size、mime を持ちます

Preview での確認​

Validate Payload を作成したら、Automation Tool の Preview で確認できます。

1. Preview をクリックします
2. schema に沿ったテストデータを入力します
3. ファイルの要件があれば、対応するテストファイルをアップロードします
4. 検証の結果と後続の処理を確認します

注意事項​

• Automation Tool ワークフローの必須の入口ノードです。
• スキーマは JSON Schema 標準に従う必要があります。
• ファイル種別のチェックは MIME タイプと拡張子の両方を見ます。