メッセージ・マップ を使用した REST API 操作の実装

グラフィカル・データ・マッピング・エディター を使用して、REST API 操作を実装できます。 REST API 操作のマップを作成するときに、REST API Swagger 文書または OpenAPI 3.0 文書内の定義からマップ入出力を自動的に定義することを選択できます。

このタスクの概要

REST API 操作を実装するサブフローで Mapping ノードのマップを作成する場合、「REST API 操作 operation_name の入出力を含むメッセージ・マップ」オプションを選択できます。 このオプションを選択すると、REST API Swagger 文書または OpenAPI 3.0 文書内の JSON スキーマ・データ定義によって完全に定義された入出力データを使用してマップが作成されます。

ローカル環境が自動的にマップ入力に追加され、 「ローカル環境」 > 「REST」 > 「入力」 > 「パラメーター」の下にパスまたは照会パラメーターが追加され、変換を接続できるようになります。 Task 変換は、この情報を見つけるのに役立つように、 「ローカル環境」 > REST > 入力 に事前にワイヤリングされています。

マップ入力メッセージ本体には、操作の要求本体に応じてデータが取り込まれ、出力メッセージ本体には、応答本体に応じてデータが取り込まれます。 本体がモデルまたは JSON 配列として定義される場合、マップは JSON ドメイン・メッセージを使用して作成されます。 本体がない場合、または単純タイプの場合、マップは BLOB ドメイン・メッセージを使用して作成されます。

注: REST API を更新し、パスまたは照会パラメーター、あるいは要求または応答の本体を変更すると、メッセージ・マップは再オープン時に新しい定義を反映するように自動的に更新されます。 既存の変換がワイヤリングされている場合、それらの変換は無効または切断される可能性があり、マップは新規データ・モデルと一致するように変更する必要があります。 操作に対して定義された要求本体または応答本体がないときにマップが作成された場合、後で追加するためにマップを再作成する必要があります。

メッセージ・マップが含まれる JSON スキーマの要件に注意してください。 詳しくは、 メッセージ・マップの JSON スキーマ要件を参照してください。

グラフィカル・データ・マッピング・エディターでの変換タイプを使用して処理を実行できる REST API 操作を実装する場合は、以下の手順で説明するように、単一のメッセージ・マップを使用して操作を実装できます。 ただし、REST API 操作の処理で中間データ・フォーマットに変換し、実装の一部として追加ノードを使用する必要がある場合は、 メッセージ・マップを使用した中間処理による REST API 操作の実装で説明されている手順に従ってください。

手順

単一のメッセージ・マップを使用して REST API に操作を実装するには、以下のステップを実行します。

  1. REST API 操作のサブフローを作成するか開きます。
    操作の新規メッセージ・マップを作成する前に、REST API を保存する必要があります。これにより、Swagger 文書または OpenAPI 3.0 文書内の必要な情報が最新かつ一貫性のあるものになります。
  2. サブフローに Mapping ノードを追加します。
  3. Mapping ノードをダブルクリックして 「新規メッセージ・マップ」 ウィザードを開き、メッセージ・マップを作成します。 現在の REST API 操作のマップが作成されていることがウィザードによって検出され、「REST API 操作 operation_name の入出力を含むメッセージ・マップ」オプションが事前選択されています。 「終了」をクリックします。
  4. REST API 操作メッセージ・マップが REST API プロジェクトに作成され、 グラフィカル・データ・マッピング・エディターで開きます。
  5. REST API からの入力データがマップで提供されます。 これはローカル環境内にあり、マップ入力に自動的に追加されます。 操作に対して定義された REST API パスまたは照会パラメーターは、 「ローカル環境」 > 「REST」 > 「入力」 > 「パラメーター」の下で自動的に定義されます。
    Task 変換がマップに追加され、その入力が ローカル環境 > 「REST」 > 「入力」に接続されます。これにより、マッピングで必要になる可能性がある REST API 入力データを見つけることができます。 マッピングが完了したら、Task を削除できます。 Task 変換を残したままマップをデプロイして実行することはできますが、何も効果はありません。
    注: 入力フォームと配列タイプのパラメーターはサポートされていません。
  6. マップの入出力のメッセージ本文も、REST API Swagger 文書または OpenAPI 3.0 文書によって自動的に定義されます。
    入力メッセージ本体は、以下のいずれかのタイプとして定義されます。
    • Swagger 文書または OpenAPI 3.0 文書内の操作に対して定義された要求本体のデータ・タイプを持つ JSON。
    • 操作に要求本体データがない場合は、BLOB。
    出力メッセージ本体は、以下のいずれかのタイプとして定義されます。
    • HTTP 状況 200 の応答に対してデータ・タイプが定義された JSON。 ステータス200のレスポンスがない場合は、デフォルトのレスポンスまたはSwaggerドキュメントまたはドキュメントで定義された最初のレスポンスが使用されます。 OpenAPI 3.0 ドキュメントが使用されます。
    • 操作に応答本体データがない場合は、BLOB。
    JSON 入力または出力のデータ・タイプは、以下の方法で定義されます。
    • REST API 操作の要求または応答がモデル・タイプ (Swagger 文書または OpenAPI 3.0 文書定義内のタイプへの JSON 参照) として定義されている場合は、モデル名としてタイプ名 ( Pet や Departmentなど) が使用されます。 モデルで定義されているタイプの配列の場合、タイプ名には JSONArray_ という接頭部が付きます。例えば、JSONArray_Pet のようになります。
    • API 操作要求本体が Swagger スキーマ・ステートメントまたは OpenAPI 3.0 スキーマ・ステートメントによってインラインで定義されている場合、そのタイプ名は以下のように形成されます。
      <Json type>_<operation name>_body
    • API 操作応答本体が Swagger スキーマ・ステートメントまたは OpenAPI 3.0 スキーマ・ステートメントによってインラインで定義されている場合、そのタイプ名は以下のように形成されます。
      <Json type>_<operation name>_<http status code>
      例:
      string_getSurname_200
      または
      object_getItem_200
    • 要求本体または応答本体がインライン配列として定義されている場合、タイプ名には接頭部として JSONArray_ が付けられます (例えば、JSONArray_string_getAllSurnames_200)。
  7. 「グラフィカル・データ・マッピング・エディターでの変換タイプ」のいずれかを使用して、REST API 操作を実装するために、マップで必要な変換ロジックを完成させます。 詳しくは、 メッセージ・マップの編集を参照してください。
    メッセージ・データの変換に加えて、以下のトピックの説明に従ってリソースと対話することができます。

次のタスク

REST API をメッセージ・マップとともにデプロイして、操作を実行して、出力メッセージが予期したとおりであることを確認します。 詳しくは、 メッセージ・マップのトラブルシューティングを参照してください。