COBOL プログラム サービス インターフェイス用の インターフェイス マッパー のユーザー インターフェイスは 2 つの部分から構成されます。左側には COBOL エントリ ポイント フィールドが表示され、右側にはインターフェイス フィールド、再利用可能なフィールド、および COBOL 割り当てが表示されます。
COBOL フィールドからインターフェイス フィールドを作成する最も簡単な方法は、COBOL フィールドを [COBOL Entry Point] ペインからドラッグして [Interface Fields] ペインにドロップすることです。これにより、COBOL フィールドと新しいインターフェイス フィールドの間のマッピングが作成されます。[Interface Fields] ペインから、サービス インターフェイスで使用されるフィールドの詳細をさらに定義できます。
作成したインターフェイス フィールドの [Type] は、再利用可能なフィールドの名前から派生されます。たとえば、MyReusableField という名前の再利用可能なフィールドを作成して、[Interface Fields] ペインにドラッグ アンド ドロップすると、そのインターフェイス フィールドの [Type] 列の値は MyResuableField になります。
インターフェイス フィールドには、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」インスタンスは含まれません。同じ名前の本文フィールドが 2 つ以上ある場合は、目的とするフィールドの 1 つ以上の親フィールドをピリオドで区切って指定することで、クエリ文字列でそれらのフィールドを区別できます (例:car.color=red)。フィルター処理で部分的な値または不完全な値を指定するには、値の最初または最後にアスタリスク文字 (*) を使用します (例:color=red* は「red」にも「reddish」にも一致します)。大文字と小文字を区別するフィルター処理を実行するには、値を一重引用符で囲みます (例:color='Red')。Path インターフェイス フィールドまたは Query インターフェイス フィールドを出力メッセージのフィルターとして機能させたくない場合は、その名前が出力の Body インターフェイス フィールドの名前と一致しないようにしてください。さらに、応答の内容をより細かく制御できる特別な組み込みクエリ パラメーターが 4 つあります。
<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 メッセージに表示されます。