データ マッピング タスク

データ マッピング タスクを使用すると、統合で変数の割り当てを実行し、json オブジェクトのプロパティを取得して設定し、値にネストされた変換関数を適用できます。これらの変数は統合変数またはタスク変数です。

たとえば、統合変数 X の値をタスク変数 Y に割り当てることも、タスク変数 Y の値を統合変数 X に割り当てることもできます。Apigee Integration の変数の詳細については、Apigee Integration での変数の使用をご覧ください。

データ マッピング タスクを構成する

データ マッピング タスクを構成するには、次の手順を実施します。

  1. Apigee UI で、Apigee 組織を選択します。
  2. [Develop] > [Integrations] の順にクリックします。
  3. 既存のインテグレーションを選択するか、[Create Integration] をクリックして新しいインテグレーションを作成します。

    新しいインテグレーションを作成する場合:

    1. [Create Integration] ダイアログで名前と説明を入力します。
    2. サポートされているリージョンのリストから、インテグレーションのリージョンを選択します。
    3. [Create] をクリックします。

    インテグレーション デザイナーでインテグレーションが開きます。

  4. インテグレーション デザイナーのナビゲーション バーで、[+ Add a task/trigger] > [Tasks] の順にクリックして、使用可能なタスクのリストを表示します。
  5. 統合エディタで [Data Mapping] 要素をクリックして配置します。
  6. デザイナーの [Data Mapping] 要素をクリックして、[Data Mapping] タスク構成ペインを表示します。
  7. タスクのデフォルト値を表示して、新しいマッピングを追加するには、[Open Data Mapping Editor] をクリックします。マッピングの追加方法について詳しくは、マッピングの追加をご覧ください。

    データ マッピング エディタのレイアウトの詳細については、データ マッピングの概要をご覧ください。

マッピングを追加する

マッピングを追加する手順は、次のとおりです。

  1. データ マッピング タスク構成ペインで、[Open Data Mapping Editor] をクリックします。
  2. マッピング [Input] を構成します。
    1. 変数またはそのサブフィールドを、[Variables] リストから [Input] 行にドラッグします。変数の使用可能なサブフィールドを表示するには、[Variables] リストの変数の横にある （Expand）をクリックします。
    2. または、入力行で、変数または値をクリックし、次の操作を行います。
      • [Variable] を選択して、既存の変数を検索して使用します。新しい変数を作成するには、[+ Add new variable] をクリックして、新しい変数の名前とデータ型を入力します。
      • [値] を選択して、string、integer、double、Boolean 型のリテラル値を入力します。
      • [Function] を選択し、基本関数を検索して使用します。

        基本関数は、統合の実行中に値を取得または生成するために使用されます。たとえば、ランダムな UUID の生成、現在の統合リージョンの取得などです。サポートされている基本関数については、サポートされている基本関数をご覧ください。

      • [保存] をクリックします。
    3. [Input] 行の任意の入力変数、値、または基本関数で [+（Add a function）] をクリックして、使用可能なマッピング関数のリストからマッピング関数を追加します。マッピング関数には 1 つ以上のパラメータを指定できます。各パラメータには、さらに値、変数、または基本関数の後にマッピング関数のチェーンを記述できます。
      • ネストされた関数を追加するには、関数のパラメータの横にある [+（Add a function）] をクリックします。同様に、最後に追加された関数を削除するには、[- (Delete previous function)] をクリックします。
      • マッピング式の間で関数を追加、削除、または変更するには、関数をクリックし、プルダウン メニューから [Add Function]、[Remove Function]、または [Change Function] を選択します。

        • マッピング関数の詳細については、マッピング関数をご覧ください。

        サポートされているマッピング関数については、サポートされているデータ型とマッピング関数をご覧ください。

      • マッピング式内の変数を削除するには、変数行の横にある （Remove）をクリックします。
      • 入力行全体を削除するには、行の （Clear）をクリックします。
  3. [Output] のマッピングを構成します。
    1. 変数を [Variables] リストから [Output] 行にドラッグします。変数が使用できない場合は、[create a new one] をクリックして、新しい変数の名前とデータ型を構成します。必要に応じて、出力変数をクリックして、その変数をインテグレーションの出力として使用するか、別のインテグレーションへの入力として使用するかを選択できます。
    2. 出力変数を削除するには、 （Clear） をクリックします。
  4. （省略可）マッピング行を削除するには、 (Delete this mapping) をクリックします。
  5. マッピングが完了したら、[Data Mapping Editor] を閉じます。変更は自動的に保存されます。

完了したデータ マッピングは、次の図に示すように、[Data Mapping] タスク構成ペインに表示されます。

データ マッピング エディタの画像 データ マッピング エディタの画像

サポートされているデータ型とマッピング関数

Apigee Integration では、データ マッピング タスクの変数に対して次のデータ型がサポートされています。

  • 文字列と文字列配列
  • 整数と整数配列
  • Double と Double 配列
  • ブール値とブール値配列
  • JSON
次の表に、各データ型で使用可能なデータ マッピング関数を示します。
データ型 サポートされているマッピング関数
ブール値 AND、EQUALS、NAND、NOR、NOT、OR、TO_JSON、TO_STRING、XNOR、XOR
ブール値配列 APPEND、APPEND_ALL、CONTAINS、FILTER、FOR_EACH、GET、REMOVE、REMOVE_AT、SET、SIZE、TO_JSON、TO_SET
ダブル ADD、DIVIDE、CEIL、EQUALS、EXPONENT、GREATER_THAN、GREATER_THAN_EQUAL_TO、FLOOR、LESS_THAN、LESS_THAN_EQUAL_TO、MOD、MULTIPLY、ROUND、SUBTRACT、TO_JSON、TO_STRING
Double 配列 APPEND、APPEND_ALL、AVG、CONTAINS、FILTER、FOR_EACH、GET、MAX、MIN、REMOVE、REMOVE_AT、SET、SIZE、SUM、TO_JSON、TO_SET
整数 ADD、DIVIDE、EPOCH_TO_HUMAN_READABLE_TIME、EQUALS、EXPONENT、GREATER_THAN、GREATER_THAN_EQUAL_TO、LESS_THAN、LESS_THAN_EQUAL_TO、MOD、MULTIPLY、SUBTRACT、TO_DOUBLE、TO_JSON、TO_STRING
整数配列 APPEND、APPEND_ALL、AVG、CONTAINS、FILTER、FOR_EACH、GET、MAX、MIN、REMOVE、REMOVE_AT、SET、SIZE、SUM、TO_JSON、TO_SET
JSON APPEND_ELEMENT、FLATTEN、FILTER、FOR_EACH、GET_ELEMENT、GET_PROPERTY、MERGE、REMOVE_PROPERTY、RESOLVE_TEMPLATE、SET_PROPERTY、SIZE、TO_BOOLEAN、TO_BOOLEAN_ARRAY、TO_DOUBLE、TO_DOUBLE_ARRAY、TO_INT、TO_INT_ARRAY、TO_STRING、TO_STRING_ARRAY
文字列 CONCAT、CONTAINS、DECODE_BASE64_STRING、EQUALS、EQUALS_IGNORE_CASE、LENGTH、REPLACE_ALL、RESOLVE_TEMPLATE、SPLIT、SUBSTRING、TO_BASE_64、TO_BOOLEAN、TO_DOUBLE、TO_INT、TO_JSON、TO_LOWERCASE、TO_UPPERCASE
文字列配列 APPEND、APPEND_ALL、CONTAINS、FILTER、FOR_EACH、GET、REMOVE、REMOVE_AT、SET、SIZE、TO_JSON、TO_SET
各データ マッピング関数の詳細については、データ マッピング関数リファレンスをご覧ください。

サポートされている基本関数

次の表に、利用可能なデータ マッピングの基本関数を示します。
データ型 サポートされている基本関数
整数 NOW_IN_MILLIS
整数配列 INT_LIST
文字列 GENERATE_UUID、GET_EXECUTION_ID、GET_INTEGRATION_NAME、GET_INTEGRATION_REGION、GET_PROJECT_ID
各データ マッピングの基本関数の詳細については、データ マッピング関数リファレンスをご覧ください。

ベスト プラクティス

データ マッピング タスクは、キー変数を統合内のさまざまなタスクに渡す強力な方法になります。統合を構築する際に、次のヒントを参考にしてください。

  • マッピングは上から下に順次実行されます。つまり、入力変数 A が最初の行の出力変数 B にマッピングされている場合、変数 B は、後続の行のマッピングに使用できます。
  • 各行で、入力行のデータ型は出力行のデータ型と一致する必要があります。型の間でキャストするには、TO_STRING、TO_INT などの変換関数を使用します。
  • 変換チェーンの長さに制限はありません。ただし、大規模な連鎖変換のデバッグは難しくなる場合があります。入力変換を読み取り可能にし、複雑な変換を複数のマッピングに分割することをおすすめします。
  • マッピングにフォールバック値が必要な場合は、マッピングのフォールバック値を設定します。フォールバック値を指定しない場合、入力値または変換が null を返すときにマッピングがエラーを返します。
  • 変数を削除する場合は、それを含むマッピングをすべて削除してください。

データ マッピング タスクに適用される使用量上限については、使用量上限をご覧ください。

考慮事項

JSON 変数の場合、JSON スキーマに基づいて、Apigee Integration では次の場合に変数の子プロパティが JSON 型として解釈されます。

  • 子プロパティの型が null を指定している場合。次に例を示します。
    {
  "properties": {
    "PersonID": {
      "type": [
        "double",
        "null"
      ],
      "readOnly": false
    }
  }
}
  • 子プロパティの型が複数のデータ型を指定している場合。次に例を示します。
    {
  "properties": {
    "PersonID": {
      "type": [
        "integer",
        "string",
        "number"
      ],
      "readOnly": false
    }
  }
}

このような場合、データ マッピング関数を使用して、子変数を目的の型に明示的に変換する必要があります。

次の例は、さまざまなタイプのプロパティ宣言を示しており、データ マッピング関数を使用して目的のタイプを取得する方法を示しています。

例 1

{
  "type": "object",
  "properties": {
    "dbIntegers": {
      "type": "array",
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "dbBooleans": {
      "type": [
        "array"
      ],
      "items": {
        "type": "boolean"
      }
    }
  }
}
Apigee Integration では dbIntegers が JSON 型として、dbBooleans が BOOLEAN_ARRAY 型として解釈されます。

dbIntegers を変換するには、次を使用します。

dbIntegers.TO_INT_ARRAY()

例 2

{
  "type": "object",
  "properties": {
    "dbId": {
      "type": [
        "number",
        "null"
      ],
      "readOnly": false
    },
    "dbStatus": {
      "type": [
        "boolean",
        "null"
      ],
      "readOnly": false
    }
  }
}
Apigee Integration では dbId と dbStatus の両方が JSON 型として認識されますが、dbId は単一の double 値または null 値を取ることができるパラメータであり、単一のブール値または null 値をとることができる dbStatus パラメータです。

dbId と dbStatus を変換するには、次を使用します。

dbId.TO_DOUBLE()
dbStatus.TO_BOOLEAN()

例 3

{
  "type": "object",
  "properties": {
    "dbString": {
      "type": [
        "string"
      ],
      "readOnly": false
    }
  }
}
Apigee Integration では、dbString を文字列型として認識します。

エラー処理方法

タスクのエラー処理方法では、一時的なエラーによってタスクが失敗した場合のアクションを指定します。エラー処理方式と、さまざまな種類のエラー処理方式の詳細については、エラー処理方法をご覧ください。