インターフェイス マッパー

インターフェイス マッパーのコンポーネントおよびそれぞれの目的について説明します。

COBOL プログラム サービス インターフェイス用の インターフェイス マッパー のユーザー インターフェイスは 2 つの部分から構成されます。左側には COBOL エントリ ポイント フィールドが表示され、右側にはインターフェイス フィールド、再利用可能なフィールド、および COBOL 割り当てが表示されます。

[COBOL Entry Point] ペイン
選択した COBOL プログラムから、選択した [COBOL Entry Point] が表示されます。
[Interface Fields] ペイン
[Interface Fields] ペインでは、サービス インターフェイスに含める各フィールドの詳細を定義します。一般に、インターフェイス フィールドは、[COBOL Entry Point] ペインに表示される COBOL フィールドに対応します。現在の操作のインターフェイス フィールドのみが、このペインに表示されます。

COBOL フィールドからインターフェイス フィールドを作成する最も簡単な方法は、COBOL フィールドを [COBOL Entry Point] ペインからドラッグして [Interface Fields] ペインにドロップすることです。これにより、COBOL フィールドと新しいインターフェイス フィールドの間のマッピングが作成されます。[Interface Fields] ペインから、サービス インターフェイスで使用されるフィールドの詳細をさらに定義できます。

[Reusable Fields] ペイン
主に、補助的な用途で使用します。このペインでは、さまざまな操作で使用するフィールドを作成します。作成後に、そのフィールドを使用する各操作で、[Reusable Fields] ペインから [Interface Fields] ペインにフィールドをドラッグ アンド ドロップします。[Reusable Fields] ペインの内容は、1 つのサービス インターフェイス内であれば、どの操作でも変わりません。

作成したインターフェイス フィールドの [Type] は、再利用可能なフィールドの名前から派生されます。たとえば、MyReusableField という名前の再利用可能なフィールドを作成して、[Interface Fields] ペインにドラッグ アンド ドロップすると、そのインターフェイス フィールドの [Type] 列の値は MyReusableField になります。

[COBOL Assignments] ペイン
サービス インターフェイス用に作成した COBOL 割り当てが表示されます。たとえば、COBOL 割り当てを使用して、固有のパラメーター値を指定することで、現在の操作でアプリケーションが利用するパスを定義できます。これにより、すべての操作で同じエントリ ポイントを使用している場合でも、各操作で異なる機能を実行できます。プログラムは、パラメーターの値に応じて異なるパスを利用します。特定のパラメーターにマッピングするインターフェイス フィールドを定義する代わりに、ここに値を指定することで、プログラムは必要なパスを利用できるようになります。

JSON (RESTful) サービス インターフェイスのインターフェイス フィールドに関する特別な考慮事項

Path フィールドと Query フィールド

インターフェイス フィールドには、Body、Path、Query という 3 つの場所オプションがあります。Body は、インターフェイ スフィールドが JSON メッセージの本文に対応することを意味します。Path および Query は、操作の呼び出しに使用される要求 URI に対応するフィールド用です。Path フィールドの場合は、[Operation]> [Properties] に移動し、[Path/HTTP] タブを選択して、URI の対応する部分を指定します。Query インターフェイス フィールドは、要求 URI の最後にあるクエリ文字列に対応します。Path インターフェイス フィールドと Query インターフェイス フィールドはどちらもプリミティブ データ型である必要がありますが、ゼロ以外の Occurs 値を持つ場合があります (実際の URI ではカンマ区切りの配列として表される)。次に説明するように、Path インターフェイス フィールドまたは Query インターフェイス フィールドが出力のフィルター処理のみでの使用を目的としている場合は、マッピングが不要であることに注意してください。

実行時、出力応答の本文は、URI で受信したパス パラメーターまたはクエリ パラメーターの名前と、応答本文の出力フィールドの名前が一致すると、そのパラメーター値でフィルター処理されます。たとえば、ある操作に「/cars/{make}」というパスと、「car」の各項目から成る出力応答配列が定義されていて、実行時の要求 URI が「.../cars/ford?color=red&doors=4」だったとします (ここで、「make」、「color」、「doors」はいずれも、「car」内に定義されたフィールドの名前)。この場合の応答本文配列には、「make」、「color」、「doors」の値が URI で指定された値に一致しない「car」インスタンスは含まれません。Path インターフェイス フィールドまたは Query インターフェイス フィールドを出力メッセージのフィルターとして機能させたくない場合は、その名前が出力の Body インターフェイス フィールドの名前と一致しないようにしてください。さらに、特別な組み込みクエリ パラメーター「$fields=<出力フィールド名のカンマ区切りリスト>」を使用すれば、指定したフィールド (およびその親フィールドと従属フィールド) のみを応答本文に含めると明示し、応答の他のすべての定義済みフィールドを除外することができます。

匿名のルート フィールド
JSON メッセージ本文を送受信するサービス インターフェイス操作の場合、メッセージ内では名前なしでなければならない最も外側の (ルート) 構造 (JSON オブジェクト、配列、プリミティブなど) も、操作のインターフェイス フィールド内には最上位の Body フィールドとして表示される必要があります (これは、Type と Occurs を指定できるようにするためです)。このいわゆる「匿名ルート」インターフェイス フィールドには、[Location] 列の右側にアスタリスク (*) が付きます。このようなフィールドは、インターフェイス マッパーでは名前が付いていますが、その名前は JSON メッセージには表示されません。最上位の Body インターフェイス フィールドは入力と出力のいずれにおいても 1 つの操作に複数存在することはないので、メッセージの本文に表示されるすべてのインターフェイス フィールドは必ず、その最上位の Body フィールドの子となります。次の図に例を示します。インターフェイス マッパーには匿名ルート グループ フィールドを含むメッセージ本文があり、JSON メッセージ内には、それに対応する {} で囲まれた JSON オブジェクトがあります。
匿名ルート
JSON の配列フィールド
SOAP では (COBOL と同様に)、配列はゼロ以外の Occurs 属性が定義されたアイテムであり、そのようなアイテムはメッセージ内で複数回繰り返されます。たとえば、「group1」という名前のインターフェイス フィールド グループ配列に「Occurs 2」が指定されている場合、SOAP メッセージでは次のように表されます。
<group1>
  <field1>someValue1</field1>
  <field2>someValue2</field2>
</ group1>
< group1>
  <field1>someValue3</field1>
  <field2>someValue4</field2>
</ group1>

これに対し、JSON は明示的な配列構文を備えているという点が異なります。JSON の配列アイテムは、繰り返しアイテムではなく、繰り返しの値を含む単一のアイテムとなります。したがって、上記の同じインターフェイス フィールド グループ配列は、JSON メッセージでは次のようになります。「group1」は繰り返されず 1 回だけ表示されます。この中に、個々の配列要素の値が格納され、{} で囲まれた JSON オブジェクトの繰り返しとして表示されます。

"group1":
[
  {
   "field1":"someValue1",
   "field2":"someValue2"
  },
  {
   "field1":"someValue3",
   "field2":"someValue4"
  }
]

JSON メッセージ内で繰り返される各配列要素値に「group1」が含まれるようにする (SOAP メッセージにより近い表示にする) には、インターフェイス マッパーで「group1」フィールドの親となるインターフェイス フィールド グループを追加し、ゼロ以外の Occurs を、「group1」ではなく、その追加した親フィールドに設定します。結果の JSON メッセージは次のようになります。

"extraGroup":
[
  {
    "group1":
    {
      "field1":"someValue1",
      "field2":"someValue2"
    }
  },
  {
    "group1":
    {
      "field1":"someValue3",
      "field2":"someValue4"
    }
  }
]

一般的にどのサービス インターフェイスでも、ゼロ以外の Occurs プロパティは、そのインターフェイス フィールドが配列であることを示します。しかし、特に JSON サービス インターフェイスでは、明確に「Occurs 1」が設定されているインターフェイス フィールドは、JSON 配列構文のない、単一のオブジェクトまたはプリミティブとして JSON メッセージに表示されます。