オプションの動的構成

構成フィールドは、次から値を導出できます:

キー・ペアの配列からの静的値。
"execute"フィールドで定義されるファンクション。
この関数は、フィールド値を導出します。

次のコード例は、フロー"execute": "flow:spreadsheetIdFlow"が"spreadsheetId"構成フィールドの値をどのように移入するかを示しています。

サンプル・コード:

"insertRowAction": {
  "description": "Insert Row Into Sheet",
  "summary": "This action inserts a new row into sheet.",
  "execute": "flow:insertRowFlow",
  "input": {
    "execute": "flow:sheetSchemaFlow"
  },
  "output": {
    "$ref": "#/schemas/insertRowOutput"
  },
  "configuration": [
    {
      "name": "spreadsheetId",
      "displayName": "Spreadsheet Name",
      "description": "Please select a spreadsheet to insert a row",
      "type": "COMBO_BOX",
      "options": "flow:spreadsheetIdFlow",
      "required": true
    },
    {
      "name": "workSheetId",
      "displayName": "Worksheet Name",
      "description": "Please select a worksheet to insert a row",
      "type": "COMBO_BOX",
      "options": "flow:worksheetIdFlow",
      "required": true,
      "dependencies": {
        "spreadsheetId": {
          "values": []
        }
      }
    }
  ]
}

構成フィールド・フローでは、APIを呼び出して外部アプリケーションからデータを読み取ることで、オプションkeyNameおよびdisplayNameの値を動的に導出できます。次のコード例は、Google Sheetsへの動的コールで、ユーザー選択用に表示されるスプレッドシートのセットを取得する方法を示しています。

サンプル・コード:

"flows":
{
   "spreadsheetIdFlow": {
     "id": "spreadsheetIdFlow",
     "description": "spreadsheetIdFlow",
     "specVersion": "0.8",
     "version": "0.1",
     "start": "startState",
     "functions": [
       {
         "name": "generalRestFunc",
         "type": "custom",
         "operation": "connectivity::rest"
       }
     ],
     "states": [
       {
         "name": "startState",
         "type": "operation",
         "actions": [
           {
             "functionRef": {
               "refName": "generalRestFunc",
               "arguments": {
                 "uri": "https://www.googleapis.com/drive/v3/files",
                 "method": "GET",
                 "parameters": {
                   "q": "mimeType='application/vnd.google-apps.spreadsheet' and trashed=false",
                   "pageSize": 1000
                 }
               }
             },
             "actionDataFilter": {
               "results": "${ .body.files | map({keyName:.id, displayName:.name}) }",
               "toStateData": "${ .output }"
             }
           }
         ],
         "end": true
       }
     ]
   },
   "worksheetIdFlow": {
     "id": "sheetIdFlow",
     "description": "sheetIdFlow",
     "specVersion": "0.8",
     "version": "0.1",
     "start": "startState",
     "functions": [
       {
         "name": "generalRestFunc",
         "type": "custom",
         "operation": "connectivity::rest"
       }
     ],
     "states": [
       {
         "name": "startState",
         "type": "operation",
         "actions": [
           {
             "functionRef": {
               "refName": "generalRestFunc",
               "arguments": {
                 "uri": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}",
                 "method": "GET",
                 "parameters": {
                   "spreadsheetId": "${ .configuration.spreadsheetId }"
                 }
               }
             },
             "actionDataFilter": {
               "results": "${ .body.sheets | map({keyName:.properties.title, displayName:.properties.title}) }",
               "toStateData": "${ .output }"
             }
           }
         ],
         "end": true
       }
     ]
   }
 }

".configuration"プロパティ構造では、構成フィールドから値を選択できます。たとえば、worksheetflowIDフローは、".configuration.spreadsheetId"値リストからユーザーが選択した"spreadsheetId"値にアクセスします。

"actionDataFilter"プロパティは、APIレスポンスのbody.sheets JSONオブジェクトからデータを抽出し、データをkeyNameおよびdisplayNameのキー値マップにフォーマットします。

構成フィールド・フローの作成

このタイプのフローは次の方法で作成できます:

Rapid Adapter Builderのセマンティクスと構文の理解に基づいて、アダプタ定義ドキュメントで関連するJSONコードを手動で作成します。
Visual Studio CodeのRapid Adapter Builder拡張機能を使用して、フローを作成します。
Postmanコレクションのフローをモデル化し、Visual Studio CodeのRapid Adapter Builder拡張を使用してコレクションをインポートし、それをアダプタ定義ドキュメントに変換します。

フローのPostman変換を使用した構成フィールドの設計

多くの場合、構成フィールドは、外部アプリケーションやサービスのAPIからデータを問い合せることで、その値を導出します。たとえば、リソースを作成できるアクションでは、外部サービスのAPIを問い合せて、使用可能なリソースのセットを取得する必要がある場合があります。問合せ結果にカスタム・オブジェクトが含まれる場合もあります。

このシナリオでは、アダプタ開発者は次を実行できます:

APIをテストして使用可能なリソースのリストを取得し、例をPostmanコレクションに保存します。
必須フィールドのみを含めるようにレスポンスをフィルタします。

通常、特定の構成フィールドの場合、取得されるデータは、定義された外部アプリケーションまたはサービスとしてリソース・セットに対応する名前と値のセットです。
構成フィールドに移入します。
アダプタ開発者は、Visual Studio CodeのRapid Adapter Builder拡張機能を使用して、リクエストに対応するフローのみをインポートできます。

構成フィールドでは、フローを使用して、必要な値を変数に置き換えます。入力データはハードコードされた値としてインポートされ、他の構成フィールドの選択からその値を導出できます。 APIレスポンスからのデータの形式が構成フィールドの要件に準拠していない場合、アダプタ開発者はjq式を使用して、必要な形式にデータを再構築できます。

ノート:

必要なデータの形式は、使用されるウィジェットによって異なります。テキスト・ボックスの場合、必要なデータは、名前と値プロパティを持つ単一のオブジェクトです。表ウィジェットの場合、構成フィールドを初期化するために必要なデータには、データの行の配列が必要です。詳細は、「アダプタのユーザー・インタフェース・コンポーネントの設計」を参照してください。

次のサンプル・コードは、フローを示しています:

特定のGoogle Sheetユーザーのスプレッドシートのコレクションを取得し、結果を名前と値の配列に書式設定し、コンボ・ドロップダウンに表示します。
スプレッドシート内のシートのコレクションを取得し、結果を名前と値の配列に書式設定して、コンボ・ドロップダウンに表示します。

"spreadsheetIdFlow": {
  "id": "spreadsheetIdFlow",
  "description": "spreadsheetIdFlow",
  "specVersion": "0.8",
  "version": "0.1",
  "start": "startState",
  "functions": [
    {
      "name": "generalRestFunc",
      "type": "custom",
      "operation": "connectivity::rest"
    }
  ],
  "states": [
    {
      "name": "startState",
      "type": "operation",
      "actions": [
        {
          "functionRef": {
            "refName": "generalRestFunc",
            "arguments": {
              "uri": "https://www.googleapis.com/drive/v3/files",
              "method": "GET",
              "parameters": {
                "q": "mimeType='application/vnd.google-apps.spreadsheet' and trashed=false",
                "pageSize": 1000
              }
            }
          },
          "actionDataFilter": {
            "results": "${ .body.files | map({keyName:.id, displayName:.name}) }",
            "toStateData": "${ .output }"
          }
        }
      ],
      "end": true
    }
  ]
},
"sheetIdFlow": {
  "id": "sheetIdFlow",
  "description": "sheetIdFlow",
  "specVersion": "0.8",
  "version": "0.1",
  "start": "startState",
  "functions": [
    {
      "name": "generalRestFunc",
      "type": "custom",
      "operation": "connectivity::rest"
    }
  ],
  "states": [
    {
      "name": "startState",
      "type": "operation",
      "actions": [
        {
          "functionRef": {
            "refName": "generalRestFunc",
            "arguments": {
              "uri": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}",
              "method": "GET",
              "parameters": {
                "spreadsheetId": "${ .configuration.spreadsheetId }"
              }
            }
          },
          "actionDataFilter": {
            "results": "${ .body.sheets | map({keyName:.properties.title, displayName:.properties.title}) }",
            "toStateData": "${ .output }"
          }
        }
      ],
      "end": true
    }
  ]
}

次のサンプル・コードは、トピックのリストを取得し、結果を名前と値の配列に書式設定し、コンボ・ドロップダウンに表示します。

"ListTopicsUIFlow": {
  "id": "ListTopicsUIFlow",
  "version": "0.1",
  "start": "startState",
  "specVersion": "0.8",
  "functions": [
    {
      "name": "generalRestFunc",
      "operation": "connectivity::rest",
      "type": "custom"
    }
  ],
  "states": [
    {
      "actions": [
        {
          "name": "listTopics",
          "functionRef": {
            "refName": "generalRestFunc",
            "arguments": {
              "uri": "${\"https://\"+.connectionProperties.hostName+\"/v1/projects/{projectID}/topics\"}",
              "method": "GET",
              "parameters": {
                "projectID": "${.connectionProperties.projectID}",
                "pageSize": 1000
              }
            }
          },
          "actionDataFilter": {
            "results": "${ .body|if .topics!=null then(.topics | map({keyName:(.name|split(\"/\")|.[3]), displayName:(.name|split(\"/\")|.[3])})) else map({keyName:\"\", displayName:\"\"}) end}",
            "toStateData": "${ .output }"
          }
        }
      ],
      "name": "startState",
      "type": "operation",
      "end": true
    }
  ]
}

フローのPostman変換を使用した動的スキーマのモデル化

通常、スキーマは、アクションの入出力に対して静的に定義されます。ただし、エンタープライズ・アダプタでは、外部アプリケーションまたはサービスをコールして、オブジェクトまたはリソースの特定のメタデータ・モデルを問い合せる機能をサポートする必要がある場合があります。 APIレスポンスには次のものが含まれます:

プロパティのリスト
各プロパティのプロパティ名およびデータ型。

ノート:

この形式は、サービスによって異なります。

ただし、構成フィールドには、名前と値の形式のオブジェクトの配列が必要です。動的スキーマをサポートできるフローのレスポンスには、構造を定義するサポートされているスキーマ・タイプに対応するメタデータを生成するフローのレスポンスが必要です。

Rapid Adapter Builderプラットフォームでは、次の形式がサポートされています:

application/schema+json

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

arvoスキーマの場合は、schemaTypeをavro/binary値に設定します。

APIレスポンスが、前述の形式のいずれでもないオブジェクト定義形式を返す場合、アダプタ開発者はjq式を使用してデータを変換し、JSONスキーマ形式に書式設定できます。

次のサンプル・コードは、見出しをメタデータとして使用して、Google Sheetのシートの最初の行を問い合せる方法を示しています。

"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スキーマを作成するフローを示しています。

"RetrieveAPaymentMethodCustomFieldFlow": {
    "id": "RetrieveAPaymentMethodCustomFieldFlow",
    "version": "0.1",
    "start": "startState",
    "specVersion": "0.8",
    "functions": [
        {
            "name": "staticFlow",
            "type": "expression",
            "operation": ".self.schemas.RetrieveAPaymentMethod0ResponseSchema"
        },
        {
            "name": "dynamicFlow",
            "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": "staticFlow",
                    "actionDataFilter": {
                        "toStateData": "${ .staticOutput }"
                    }
                },
                {
                    "functionRef": {
                        "refName": "dynamicFlow",
                        "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.body.properties }"
                    }
                },
                {
                    "functionRef": "constructResult",
                    "actionDataFilter": {
                        "toStateData": "${ .schema }"
                    }
                },
                {
                    "functionRef": "constructReturnObject",
                    "actionDataFilter": {
                        "toStateData": "${ .output }"
                    }
                }
            ],
            "end": true
        }
    ]
}