Map ポリシー構造

「 マップ 」ポリシーには、そのタイトルと説明に加えて、以下の 4 つのメイン・セクションがあります。

inputs

「マップ」 ポリシーの入力を形成する変数のリスト。 各入力には、入力変数が検出されたコンテキスト変数、 「マップ」 ポリシー内の変数の名前、変数のコンテンツ・タイプ、および変数またはその構造を定義するスキーマの定義があります。

outputs

「マップ」 ポリシーの出力を形成する変数のリスト。 各出力には、出力変数を格納する (または出力変数が作成される) コンテキスト変数、出力時の変数の名前、変数の定義 (または変数の構造を定義するスキーマ) が含まれます。

action

順番に実行するべきアクションの詳細が含まれた配列。 各エントリーには、set フィールドまたは create フィールドが含まれます。これらのフィールドにより、出力変数またはアクションの一部を構成する変数が指定されます。 アクションには、from フィールドが含まれる場合もあります。このフィールドにより、入力変数またはアクションの一部を構成する変数が指定されます。

出力を設定または作成した場合、各アクションには value フィールドも含まれます。最初のアクション内で追加のアクションをネストして、ネストされた配列内でエレメントを設定または作成した場合、各アクションには foreach フィールドと新しい actions セクションも含まれます。

options

以下のプロパティー・オプションを選択できます。

• 「空を含める」。 このチェック・ボックスを選択すると (デフォルトで選択されます)、マップ・ポリシーの出力に空の XML エレメントが含まれます。 マップ・ポリシーの出力に空の XML エレメントを含めたくない場合は、このチェック・ボックスをクリアしてください。
• 名前空間の継承。 このチェック・ボックスを選択すると (デフォルトで選択されます)、親エレメントから XML の名前空間が継承されます。 map ポリシーに明示的な名前空間を使用させる場合は、このチェック・ボックスをクリアしてください。
• 名前空間のインライン化。 このチェック・ボックス (デフォルトのオプション) が選択されている場合、XML の名前空間は、それが最初に使用されたドキュメントに挿入されます。 すべての名前空間をルート・エレメントで定義する場合は、このチェック・ボックスをクリアします。
• XML入力データの型を解決する。 このチェック・ボックスが選択されている場合、スキーマの型がブールまたは数値として構成されている XML エレメントは、そのデータ型に変換されます。 すべての XML エレメント値をストリングとして返すようにする場合は、このチェック・ボックスをクリアします (デフォルト・オプション)。
• XML出力を解析する ：このチェックボックスがオンになっている場合、マップポリシーはXML出力を解析済みのXML message.body ドキュメントとして書き込みます。 デフォルトでは、XML は XML ストリングとして出力されます。 他の変数への XML 出力は常に XML ストリングとして書き込まれます。
• 空のXML要素の処理。 このプロパティーは、map ポリシーが空の XML エレメントの出力を処理する方法を制御します。 以下の選択項目を使用できます。
  • String (デフォルト・オプション): 空の XML エレメントは空ストリングとして処理されます。
  • NULL: 空の XML エレメントはヌル値として処理されます。
  • なし: データは無視されます。
  • String Badgerfish : 空のXML要素の値は、空の文字列と見なされます。 空ストリング値は、JSON BadgerFish 値プロパティーに入れられます。
  • Null Badgerfish ：空のXML要素の値はnullと見なされます。 ヌル値は、JSON BadgerFish 値プロパティーに入れられます。 「ヌル値を許可」オプションが選択されていないと、このエレメントは JSON 出力プロパティーにマップされません。
• 配列の最初の要素のみを使用してください。 このチェック・ボックスを選択すると、入力のトラバーサルで配列が検出された場合に、最初のエレメントだけが使用されます。 map ポリシーですべての配列エレメントを使用する場合は、このチェック・ボックスをクリアしてください (デフォルトで選択されています)。
• API Connect 変数の参照を解決します。 このチェックボックスがオフになっている場合（デフォルト設定）、マップポリシーはマップのプロパティ内の変数参照を API Connect 無視します。 マップのプロパティ内で見つかった変数参照を解決 API Connect したい場合は、このチェックボックスをオンにしてください。
• NULL値を許可する。 このチェック・ボックスを選択すると、null 値である入力プロパティーの値が出力文書にマップされます。 null の入力値を map ポリシーで無視する場合は、このチェック・ボックスをクリアしてください (デフォルトで選択されています)。
• スキーマ定義を最適化します。 このチェック・ボックスを選択すると、複合スキーマ・タイプ評価で循環タイプの参照が最適化された方法で処理されます。 これらのスキーマ・タイプを標準の方法で評価するには、(デフォルトで選択されている) このチェック・ボックスをクリアしてください。
• 配列オブジェクトおよびマッピングされたオプションのオブジェクトに対して、必須の子プロパティを作成します。 このチェック・ボックスが選択されている場合、以下の特定の場合に、マップされず、かつ入力データが存在しない必須プロパティーに対してデフォルト値が出力で生成されます。
  • 配列が、1 つ以上の必須プロパティーが含まれているオブジェクトで構成されている。
  • オプションであるオブジェクトに、1 つ以上の必須の子プロパティーが含まれている。
  デフォルトでは、これらの必須プロパティーは出力に存在しません。 このオプションを選択した場合、これらの必須プロパティーが出力に含まれます。 出力スキーマが出力プロパティーの default プロパティーを定義している場合、指定されたデフォルト値が使用されます。それ以外の場合は、以下のように、デフォルト値がデータ型に応じて割り当てられます。

  • ストリング: 空ストリング ("")
  • 数値: 0
  • ブール: false
  • オブジェクト: 空のオブジェクト
  • 配列: 空の配列

  例 1

  入力データは、以下のオブジェクトの配列を持ちます。

  [{“a”: “value1”}, {“a”: “value2", "b": “value3”}]

  出力スキーマでは、a と b という 2 つのプロパティーを持つ出力オブジェクトが定義されます。このうち、b は必須です。 マップ・ポリシーは、以下のマッピングを定義します。

  • input.array.a から output.array.a へ
  • input.array.b から output.array.b へ

  このチェック・ボックスが選択されていて、b がマップされておらず、かつ入力データも存在しない場合、b には空ストリングのデフォルト値が割り当てられ、出力は次のようになります。

  [{“a”: “value1", "b": ""}, {"a": "value2", "b": "value3"}]

  例 2

  出力スキーマは、以下の構造を定義します。

  {"a" : {"b" : {"c" : "value1", "d" : "value2"} } }

  プロパティー b はオプションですが、b 内のプロパティー d は必須です。

  マップ・ポリシーは、output.a.b.c へのマッピングを定義します。

  このチェック・ボックスが選択されていて、d がマップされていない場合、d には空ストリングのデフォルト値が割り当てられ、出力は次のようになります。

  {"a" : {"b" : {"c" : "value1", "d" : ""} } }

  このチェック・ボックスが選択されていない場合、これらの必須プロパティーは、デフォルト値を使用して出力に作成されません。

• 空のJSON配列の処理。 このプロパティーは、map ポリシーが空の配列の出力を処理する方法を制御します。 以下の選択項目を使用できます。
  • すべて (デフォルト値): 空の子配列を含め、空の配列をすべて出力します。
  • 親: 現在のプロパティーの空の配列値のみを出力します。 このプロパティーの子のマップ・アクションは試行されません。
  • なし: 空の出力配列値が生成されないようにします。
• JSONのポスト処理を有効にする。 マップされた JSON 出力の後処理を有効にするには、このチェック・ボックスを選択します。 JSON 出力の後処理では、プロパティー値のデータ型がスキーマで定義されたデータ型と同じであることを確認するために出力スキーマが使用されます。 また、XML 入力のオブジェクト・マッピングが原因で Badgerfish JSON 構文を持つ出力プロパティー値が正規化されます。 このチェック・ボックスは、デフォルトではクリアされています。つまり、マップされた JSON 出力の後処理は行われません。
• スキーマ定義の循環参照の制限。 このプロパティーの値は、循環スキーマ定義の反復の最大許容回数を指定する整数値に設定します。

  デフォルト値は 1 です。この場合、循環スキーマ定義をたどって反復処理することはありません。 可能な最大値は 5 です。

• 入力データ・ログ・メッセージの重大度レベル。このプロパティーは、入力データに関連するログ・メッセージの重大度レベルを指定します。 以下の選択項目を使用できます。
  • エラー
  • 警告
  • INFO
• マッピングに失敗したケース用に、空の親オブジェクトを作成します。 マッピングの入力が存在せず、デフォルトのマッピングが構成されていないためにマッピングが失敗した場合、デフォルトの動作では、出力マッピングに対する変更は行われません。 このチェックボックスをオンにすると、ターゲットマッピングの親として空のオブジェクトが作成され、 IBM® API Management Version 4.0. の動作がエミュレートされます。

  例

  マップ・ポリシーは、output.a.b.c へのマッピングを定義します。

  入力データが存在する場合、出力は次のようになります。

  {
    "a": {
      "b": {
        "c": "inputvalue"
      }
    }
  }

  入力データが存在せず、「失敗したマッピングに対する空の親オブジェクトの作成」オプションが選択されている場合、出力は以下のようになります。

  {
    "a": {
      "b": {
      }
    }
  }

  プロパティー a および b が作成されますが、b の値は空のオブジェクトです。

  このチェック・ボックスは、デフォルトでクリアされています。

以下の例は、 Map ポリシーの inputs および outputs セクションを示しています。

          inputs:
            input_string:
              schema:
                type: string
              variable: request.parameters.name_in
            input_integer:
              schema:
                type: integer
              variable: request.parameters.age_in
          outputs:
            output:
              schema:
                $ref: '#/definitions/output'
              variable: message.body

actions セクションに含まれているフィールドは、次のように使用されます。

set

value フィールドの結果を set フィールドで指定した出力変数に割り当てるには、set フィールドを使用します。これにより、出力変数の既存の値が置き換えられます。 指定できる出力変数は 1 つだけですが、この変数は配列またはオブジェクトにすることができます。

create

value フィールドの結果を使用して、create フィールドで指定した出力配列の新しいエントリーを作成するには、createフィールドを使用します。これにより、新しいエントリーが配列に追加されます。 指定できる出力変数は 1 つだけですが、この変数は配列またはオブジェクトにすることができます。

from

アクション内で単一の変数または変数の配列として使用する変数を指定します。変数は、配列として指定することも、オブジェクトとして指定することもできます。 inputs が使用されない場合、from フィールドは組み込まれません。

value

出力変数を生成するスクリプトを指定するには、GatewayScript を使用します。 1 つの入力を 1 つの出力にマップする場合、value フィールドは省略してかまいません。その場合、from で指定した変数は、set または create で指定した変数として設定または作成されます。

default

入力値が提供されない場合に出力に適用される、静的な値、またはインライン変数参照を指定します。 インライン変数参照については、 インライン参照を参照してください。

foreach

関連する actions フィールドを配列内の各エントリーに対して実行する場合は、任意の変数を指定します。 この変数は、 Map ポリシーの入力または出力から取得できます。

actions

actions フィールドを使用して、1 つのアクション内に複数のアクションをネストします。 1 回しか適用しない場合は、別のアクションで同じ結果が得られるため、これは主に foreach フィールドと一緒に使用します。

from、set、およびcreate

各アクションでは、そのアクションの適用先となる出力変数を指定する set フィールドまたは create フィールドを 1 つだけ指定する必要があります。 各アクションではさらに、アクションで使用する入力変数 (複数可) を指定するための 1 つ以上のエントリーが含まれた from フィールドを設定できます。

set および create フィールドはどちらも出力変数に値を割り当てるために使用されます。

• set フィールドは、出力変数の現在の値を置き換えます。出力変数が存在しない場合は、新しく作成します。
• create は、新しい配列エントリーを出力変数に追加します。

set および createでは、 output_variable_name.variable_name を使用して、どの定義済み出力変数を使用するかを指定します。ここで、 output_variable_name は Map ポリシーの出力セクションで定義されているとおりで、 variable_name は出力変数に属するオプション・フィールドです。

fromの場合、 input_variable_name.variable_name を使用して、どの定義済み出力変数を使用するかを指定します。ここで、 input_variable_name は Map ポリシーの出力セクションで定義されているとおりで、 variable_name は出力変数に属するオプション・フィールドを指します。

foreach

配列内の各エントリーに対して後続の actions フィールドまたは value フィールドを実行する入力配列を指定するには、foreach フィールドを使用します。

例:

foreach: input.in
actions:
   actions

ここで、input.in は配列型の入力変数であり、actions は親セクションと同じ形式をとる 1 つ以上のアクションです。 この例では、actions で指定した手順が、input.in の各配列エントリーに対して 1 回だけ実行されます。

foreach フィールドで指定した入力変数を参照すると、現在の反復に対応する配列エントリーが参照されます。

foreach フィールドに配列ではなく単一の変数を使用する場合、後続の actions または value フィールドは、1 回その単一変数に適用されるか、またはその単一変数に基づき、その後ループは終了します。

from フィールドの変数を参照する場合は、変数の名前を使用するか、数値の前に「$」を付けて括弧で囲んだ値を使用します。 変数は 1 から番号付けされます。ここで、1 は配列の最初の変数です。あるいは、from フィールドに変数が 1 つだけリストされている場合は、唯一の変数を表します。 例:

value: '$(1) + $(2)'

または

value: '$(variable_1) + $(variable_2)'

ここで、各 variable は from フィールドに含まれている変数です。

foreach ループの実行中は、$(0) を参照することができます。 $(0) 変数は空の foreach ループを開始しますが、反復が終了するとその反復の出力と同じ内容になるため、もう一度参照できるようになります。 この方法で、配列を単一の値に割り当てることができます。 例:

- set: out.total
from: in.input
foreach: in.input
value: '$(0) + $(in.input)'

out.total は、$(0) によって参照されます。 反復ごとに、out.total の現行値と in.input の現在の配列エントリーが合計され、この合計として out.total の値が設定されます。