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

出力スキーマ

一部のノードでは、そのノードの出力に対する JSON スキーマ を定義できます。スキーマは、ノードが返す JSON の形状（例：instanceId と state を持つオブジェクト、バケット名の配列など）を記述し、後続のノードがフィルター・条件・次のステップで個々のフィールドを参照できるようにします。例えば、Code ノードが EC2 インスタンス ID とステータスの一覧を返す場合、出力スキーマを定義することで、後続の Filter ノードは state を参照して running のインスタンスだけを残したり、Notification ノードがメッセージに特定のフィールドを含めたりできます。スキーマを定義することで、スクリプト・CLI コマンド・LLM 応答からの構造化された出力を、フロー全体で利用できるようになります。

出力スキーマは、ノードのパラメータ内の Referencing the output で Advanced referencing を選択して設定します。出力スキーマをサポートするノードは次のとおりです。

スキーマを生成する​

JSON スキーマを生成する際は、次のいずれかの方法を利用できます。

  • AI によるスキーマ生成を使用する: ノードのパラメータから Suggest schema を選択し、プロンプトの内容に基づいて出力スキーマを自動的に推論・生成します。生成されたスキーマは後から編集できますが、必ずペイロードのみを記述するようにしてください。

  • 定義ルール と スキーマパターン に従って、JSON スキーマを手動で記述します。

スキーマの範囲​

出力スキーマは、ノードがコードまたは設定から返す値、つまり他のノードが利用する実際のペイロードのみを記述します。実行ログや Test results タブに表示される実行メタデータやランタイムのラッパー（例：results、message、context）は対象外です。ノードの機能的な出力だけをスタンドアロンの JSON ドキュメントとして取り出したときに得られる JSON 値に対してスキーマを定義し、その外側のラッパーはモデル化しないでください。

定義ルール​

出力スキーマを定義する際は、次の点に注意してください。

  • トップレベルの型 を正確に一致させる：object、array、string、number、boolean、null のいずれか。
  • 形状を 再帰的に 定義する：
    • object の場合は properties（および任意で required）を定義します。
    • array の場合は items（各要素のスキーマ）を定義します。
  • CloudFlow の予約済みフィールド（例：results、message、context）を参照しないでください。これらはランタイムのラッパーの一部であり、ノードの機能的な出力ではありません。
  • 出力スキーマからは $schema と $id キーワードを省略してください。これらの JSON Schema 識別子はサポートされていません。

機微なフィールドの指定​

スキーマ内の特定のフィールドを sensitive としてマークし、その値を CloudFlow がシークレットとして扱うようにできます。プロパティに "sensitive": true を指定すると、CloudFlow はそのフィールドの値を保存時に暗号化し、必要に応じて CloudFlow の UI やログ上でマスクしますが、実行時には後続ノードからその値を利用できるようにします。

例えば、入れ子になった key フィールドを機微情報としてマークするには、次のようにします。

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "id": { "type": "integer" },
        "key": { "type": "string", "sensitive": true }
      }
    }
  }
}

"sensitive": true は、シークレットやその他の機密値（例：API キー、トークン、認証情報）を含むフィールドに対してのみ使用し、CloudFlow がそれらを適切に保護できるようにしてください。

スキーマパターン​

その他のペイロード形状には、次のパターンを使用してください。繰り返しになりますが、スキーマはあくまでペイロード（例：results[0] の中身）のみを記述し、実行時のラッパーは対象外である点に注意してください。

ノードがオブジェクトを返す場合：

{ "type": "object", "properties": { "foo": { "type": "string" } } }

ノードが配列を返す場合：

{ "type": "array", "items": { "type": "number" } }

ノードが入れ子のオブジェクトを返す場合：

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "id": { "type": "integer" }
      }
    }
  }
}

ノードが必須フィールドを持つオブジェクトを返す場合：

{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "count": { "type": "number" }
  },
  "required": ["status"]
}

例​

例：Code ノードが EC2 インスタンスデータを返す場合​

Code ノードがデータ（例：インスタンス ID とステータス）を返すとき、実行結果には CloudFlow のラッパーが含まれます。出力スキーマは ペイロード、つまり results[0] 内の値に対してのみ定義します。

実行出力（簡略化。ラッパーには results、message、context が含まれます）:

[
  {
    "results": [
      {
        "instanceId": "i-0abc123",
        "state": "running"
      }
    ],
    "message": "OK",
    "context": {}
  }
]

ペイロード（後続ノードが参照する値）は、results[0] 内のオブジェクトです。

{
  "instanceId": "i-0abc123",
  "state": "running"
}

定義すべき 出力スキーマ（ラッパーではなくペイロードのみを記述）:

{
  "type": "object",
  "properties": {
    "instanceId": { "type": "string" },
    "state": { "type": "string" }
  }
}

スキーマをテストする​

スキーマをテストするには、ノードを実行するか保存済みのテストデータを使用し、出力を利用可能な状態にしてください。スキーマがペイロードと一致していること、および後続ノードが必要なフィールドを参照できることを確認してください。ノードの実行方法、テストデータの保存方法、および後続ノードのテスト方法については、Test nodes を参照してください。

関連項目​

に最終更新