アクション定義の入力および出力スキーマ

inputおよびoutputプロパティは、アクション定義の契約をモデル化します。プロパティ値は、スキーマの形成を決定する様々なタイプの値を受け入れることができます。アクション定義の入出力プロパティは、アダプタ定義ドキュメントのスキーマ・セクションで定義されたスキーマを参照できます。アクション定義は、JSONスキーマ形式で表されたインライン・スキーマを受け入れることもできます。次のコード・スニペットでは、入力はスキーマを参照し、出力はフローを参照します。 schemaTypeプロパティは、スキーマのタイプを定義します。

"output": {
        "schemaType": "application/schema+json",
        "schema": {
          "$ref": "#/schemas/insertRowOutput"
        }

Rapid Adapter Builderプラットフォームでは、次のタイプのスキーマがサポートされています:

application/schema+json
JSONスキーマの場合、schemaTypeをapplication/schema+jsonに設定します。
avro/binary
Avroスキーマの場合、schemaTypeをavro/binaryに設定します。

次の項では、静的スキーマ、動的スキーマを定義する方法、および静的スキーマを動的スキーマとブレンドする方法について説明

静的スキーマ

アダプタを明示的に構築して、特定の顧客のインスタンスをサポートできます。このビジネス・シナリオでは、アダプタは内部消費に使用されるため、アダプタはカスタマイズに適した動的動作をサポートする必要はありません。この要件のために、アダプタ開発者は、名前、データ型およびその他のプロパティを使用してJSONスキーマを定義することを選択できます。 JSONスキーマは静的スキーマであり、簡単に定義できます。

一部の外部アプリケーションおよびサービスでは、カスタム・リソースまたはカスタム・オブジェクトを定義する機能、およびユーザー定義属性を使用して既存のリソースまたはオブジェクトを拡張する機能が提供されない場合があります。このビジネス・シナリオでは、アダプタ開発者は、外部アプリケーションによって定義および文書化されたAPIスキーマを使用できます。

Google Sheetsサービスのスプレッドシートおよびシート・オブジェクトのスキーマを説明するサンプル・コード:

"schemas": {
  "Sheet": {
    "type": "object",
    "properties": {
      "properties": {
        "type": "object",
        "properties": {
          "sheetId": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "index": {
            "type": "integer"
          },
          "sheetType": {
            "type": "string"
          }
        }
      }
    }
  },
  "Spreadsheet": {
    "type": "object",
    "properties": {
      "spreadsheetId": {
        "type": "string"
      },
      "spreadsheetUrl": {
        "type": "string"
      },
      "properties": {
        "type": "object",
        "properties": {
          "title": {
            "type": "integer"
          },
          "locale": {
            "type": "string"
          },
          "autoRecalc": {
            "type": "integer"
          },
          "timeZone": {
            "type": "string"
          }
        }
      },
      "sheets": {
        "type": "array",
        "items": {
          "$ref": "#/schemas/Sheet"
        }
      }
    }
  }
}

動的スキーマ生成

このコード・サンプルでは、inputプロパティはflow:sheetSchemaFlow値に設定されています。これは、スキーマがフローによって動的に形成されることを示します。

フローは、外部アプリケーションによって提供されるメタデータAPIをコールします。次に、フローはjq式とJSONスキーマを使用してレスポンスを提供します。フロー・ロジックとjq式は、メタデータAPIのレスポンスによって異なります。一部のAPIはJSONスキーマに近いメタデータを返し、JSONスキーマへのレスポンスを変更するために必要なjq式は最小限です。

上記の例では、Google SheetはメタデータAPIを提供していません。かわりに、アダプタはメタデータを最初の行の値として解釈します。フローでは、すべての列が文字列型であると想定し、最初の行を読み取ります。次に、フローによってJSONスキーマが作成されます。

ノート:

Rapid Adapter Builder拡張機能では、トリガーの自動作成はサポートされていません。ただし、この拡張機能は、トリガー・ロジックを推進するスキーマおよびフローをインポートできます。

次のサンプル・コードは、最初の行に基づくJSONスキーマの動的生成を示しています:

"sheetSchemaFlow": {
  "id": "sheetSchemaFlow",
  "description": "sheetSchemaFlow",
  "specVersion": "0.8",
  "version": "0.1",
  "start": "startState",
  "functions": [
    {
      "name": "generalRestFunc",
      "type": "custom",
      "operation": "connectivity::rest"
    },
    {
      "name": "constructReturnObject",
      "type": "expression",
      "operation": "{\"schemaType\": \"application/schema+json\", \"schema\": .schema}"
    }
  ],
  "states": [
    {
      "name": "startState",
      "type": "operation",
      "actions": [
        {
          "functionRef": {
            "refName": "generalRestFunc",
            "arguments": {
              "uri": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}",
              "method": "GET",
              "parameters": {
                "spreadsheetId": "${ .configuration.spreadsheetId }",
                "range": "${ .configuration.sheetId + \"!A1:Z1\" }",
                "majorDimension": "ROWS"
              }
            }
          },
          "actionDataFilter": {
            "results": "${ .body.values[0] | map({key:., value: {type:\"string\"}}) | from_entries | {type: \"object\", properties: .} }",
            "toStateData": "${ .schema }"
          }
        },
        {
          "functionRef": "constructReturnObject",
          "actionDataFilter": {
            "toStateData": "${ .output }"
          }
        }
      ],
      "end": true
    }
  ]
}

静的スキーマと動的スキーマのブレンド

外部アプリケーションが既存のビジネス・オブジェクトの拡張フィールドをサポートしているビジネス・シナリオでは、アダプタ開発者は静的スキーマを動的スキーマと組み合せることができます。これを行うには、次の手順を実行します。

JSONスキーマを入力または出力に提供するフローを実行します。
JSONスキーマの静的部分をスキーマ・セクションで設計します。

フローでは、アダプタ開発者は次の構文を使用してスキーマを参照できます:

"functions": [
  {
    "name": "getStaticSchema",
    "type": "expression",
    "operation": ".self.schemas.OrderEventSchema"
  },

静的スキーマと動的スキーマのブレンドに関連する様々なステップは次のとおりです:

.self.schemasオブジェクトを使用して、スキーマにマップするファンクションを使用してフローを宣言します。
この関数がフロー内でコールされると、状態ロジックは文字列の形式でスキーマを返します。スキーマは、アダプタ定義ドキュメントのschemasセクションで定義されます。
静的スキーマに、オブジェクトのスキーマ情報の拡張プロパティを追加します。この操作を実行するには、jqを使用します。

ノート:
アダプタ開発者は、外部アプリケーションのAPIレスポンスを考慮してこれを設計する必要があります。

拡張フィールドを含むZuoraオーダー・オブジェクトのJSONスキーマを設計する方法を示すサンプル・コード:

"OrderOutputSchemaFlow": {
    "id": "OrderOutputSchemaFlow",
    "version": "0.1",
    "start": "startState",
    "specVersion": "0.8",
    "functions": [
      {
        "name": "getStaticSchema",
        "type": "expression",
        "operation": ".self.schemas.OrderEventSchema"
      },
      {
        "name": "dynamicFlow1",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "dynamicFlow2",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "dynamicFlow3",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "dynamicFlow4",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "constructResult",
        "type": "expression",
        "operation": ".staticOutput"
      },
      {
        "name": "constructReturnObject",
        "type": "expression",
        "operation": "{\"schemaType\": \"application/schema+json\", \"schema\": .schema}"
      }
    ],
    "states": [
      {
        "name": "startState",
        "type": "operation",
        "actions": [
          {
            "functionRef": "getStaticSchema",
            "actionDataFilter": {
              "toStateData": "${ .staticOutput }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow1",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/Order\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow2",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/Account\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow3",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/PaymentMethod\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow4",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/Contact\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
            },
          {
            "functionRef": "constructResult",
            "actionDataFilter": {
              "toStateData": "${ .schema }"
            }
          },
          {
            "functionRef": "constructReturnObject",
            "actionDataFilter": {
              "toStateData": "${ .output }"
            }
          }
        ],
        "end": true
      }
    ]
}

サンプル・コード:

{
  "flows": {
    "insertRecordInputFlow": {
      "id": "insertRecordInputFlow",
      "specVersion": "0.8",
      "version": "0.1",
      "start": "startState",
      "functions": [
        {
          "name": "generateSchema",
          "type": "expression",
          "operation": "{\"schemaType\": \"application/schema+json\", \"schema\": {type:\"object\", properties:{firstName:{type:\"string\"},lastName:{type:\"string\"},address:{type:\"string\"}}}}"
        }
      ],
      "states":[
        {
          "name":"startState",
          "type":"operation",
          "actions":[
            {
              "functionRef": "generateSchema",
              "actionDataFilter": {
                "toStateData": "${ .output }"
              }
            }
          ],
          "end": true
        }
      ]
    }
  }
}