コネクターテンプレートについて

概要

コネクターテンプレートとテンプレート変数を使用すると、コネクター用のカスタムAPIリクエストを構築できます。これらを使用して、ベンダーのエンドポイントが要求する形式（JSONやXMLなど）でペイロードを動的に生成します。

テンプレートはAPIリクエストの構造を定義し、テンプレート変数は動的な値を提供します。

こちらは属性がテンプレート変数にマッピングされた例です：

これらの変数の例示値です：

email      = "user@example.com"
orderTotal = 9.99
orderID    = "0123456789"

これらの変数を使用したテンプレートの例です：

{
  "order": {
    "customerEmail": "{{email}}",
    "total": {{orderTotal}},
    "id": "{{orderID}}"
  }
}

変数のプレースホルダーが値で置き換えられたレンダリングされたテンプレートの例です：

{
  "order": {
    "customerEmail": "user@example.com",
    "total": 9.99,
    "id": "0123456789"
  }
}

テンプレート

テンプレートはAPIリクエストの設計図です。受信エンドポイントが期待する構造と形式を指定します。

リクエストの各コンポーネントには、ベンダーのAPIの正確な要件を満たすための独自のテンプレートがあります：

• ヘッダー：認証トークン、メディアタイプ、またはベンダーが要求するカスタムヘッダーなどのリクエストヘッダーを構成します。
• URL：エンドポイントURLをカスタマイズします。ホスト名やパスの動的パラメータをテンプレート変数で置き換えます。これは、送信されるデータに基づいてエンドポイントまたはリソースパスが変更される場合に便利です。
• URLパラメータ：エンドポイントにクエリ文字列を動的に追加します。このテンプレートを使用して、URLのクエリ文字列パラメータ全体を追加または変更します。このテンプレートの結果はURLテンプレートの結果と組み合わされて、最終的なリクエストエンドポイントURLが構築されます。
• ボディ：リクエストのカスタムペイロードボディを作成します。
• カスタム：独自のテンプレートを作成し、名前を付けて、リクエストの任意の部分にマッピングします。

コネクターは、URL、クエリパラメータ、ヘッダー、ボディに動的な値を必要とする場合があります。以下の例は、各テンプレートタイプの使用方法を示しています：

URL

URLテンプレートは、発信リクエストのURLエンドポイントを構成します。テンプレートでレンダリングされる値には、https://からクエリ文字列?までのすべてが含まれるべきです。クエリ文字列を構成するには、URLパラメータを参照してください。

このURLテンプレートは、パスのアカウントID部分を動的に構成します。このオプションは、データソースの地域、サイト、または環境に基づいて異なるエンドポイントが必要なベンダーに役立ちます。この例では、アカウントID値の属性からテンプレート変数accountIDへのマッピングが必要です。

https://api.example.com/track/{{accountID}}/

URLパラメータ

URLパラメータテンプレートは、発信リクエストのURLエンドポイントのクエリ文字列を構成します。テンプレートでレンダリングされる値は、クエリ文字列文字?を使用してリクエストのURLに結合されます。

このURLパラメータテンプレートは、動的なorder_idパラメータと静的なsourceパラメータでクエリ文字列を構築します。

order_id={{orderID}}&source=tealium

このテンプレートが前のURLテンプレートと一緒に使用された場合、最終的にレンダリングされたURLは次のようになるでしょう：

https://api.example.com/track/ABC123/?order_id=0123456789&source=tealium

ヘッダー

ヘッダーテンプレートは、発信リクエストのヘッダーに追加されます。このテンプレートを使用して、認証やベンダーエンドポイントの他の特別な要件のためのカスタムヘッダーを追加します。

このヘッダーテンプレートは、動的に作成されたハッシュを使用してリクエストを安全に保つカスタムヘッダーを指定します。この例では、マッピングされた属性または別のカスタムテンプレートから構成されたテンプレート変数secretHashが必要です。

X-Secret: {{secretHash}}

ボディテンプレート

ボディテンプレートは、リクエストペイロードを構成します。

このボディテンプレートは、ユーザーのメール、注文合計、およびアイテムのリストに対して動的な値を持つJSONペイロードを作成します。

{
  "order": {
    "customerEmail": "{{email}}",
    "total": {{orderTotal}},
    "id": "{{orderID}}"
  }
}

テンプレート変数

テンプレート変数は、テンプレートの動的データを提供する属性マッピングです。

たとえば、テンプレートに動的な注文ID値を含めるには、属性order_idをorderIDという名前のテンプレート変数にマッピングします。その後、注文ID値が表示されるべきテンプレートで{{orderID}}を参照します。

詳細については、コネクターテンプレート変数を参照してください。

構文

これらの例は、テンプレート変数を参照し、テンプレート内で制御構造を構築するための構文を示しています。

変数

変数は、テンプレートに代入可能な値を表します。変数の値を参照するには、変数名の周りに二重の波括弧を使用します。例：{{var}}.

次の例では、テンプレート変数{{str}}がその値Helloで置き換えられます。

配列

次の例では、数字の配列{{arrn}}の最初の値を、インデックスを指定して参照します。

セクション

{{#var}} {{/var}} タグで囲まれたコンテンツのセクションは、与えられたキーのオブジェクトが見つかった場合にレンダリングされます。これには、値がtrueのブール値、空でない集計、および空でない配列が含まれます。

次の例では、ブール変数blnがtrueであるため、コンテンツがレンダリングされます。値がfalseの場合、コンテンツはレンダリングされません。

次の例では、文字列の配列arrsが空でないため、コンテンツが3回レンダリングされます。各配列要素について1回ずつです。配列が空の場合、コンテンツはレンダリングされません。

反転セクション

{{^var}} {{/var}} タグで囲まれたコンテンツのセクションは、コンテキスト内でオブジェクトが見つからない場合にレンダリングされます。これには、値がfalseのブール値、空の集計、または空の配列が含まれます。

次の例では、blnがtrueであるため、コンテンツはレンダリングされません。値がfalseの場合、コンテンツはレンダリングされます。

次の例では、変数missingが定義されていないため、コンテンツがレンダリングされます。

反復処理

テンプレートには、配列を反復処理するためのいくつかのヘルパー関数が用意されています。

以下の組み込み反復ヘルパーがサポートされています：

• iter.index（最初の要素はインデックス 1 にあります）
• iter.isFirst
• iter.isLast
• iter.hasNext

次の例では、ブール値の配列を変数 arrb にマッピングし、配列を反復処理する方法を示しています：

テンプレート

{
  "MyData": [
  {{#arrb}}
  {
    "idx": {{iter.index}},
    {{#iter.isFirst}}"first": true,{{/iter.isFirst}}
    {{#iter.isLast}}"last": true,{{/iter.isLast}}
    "val": {{.}}
  }{{#iter.hasNext}},{{/iter.hasNext}}
  {{/arrb}}
  ]
}

レンダリングされた値

{
  "MyData": [
    {
      "idx": 1,
      "first": true,
      "val": true,
    },
    {
      "idx": 2,
      "val": true,
    },
    {
      "idx": 3,
      "last": true,
      "val": false,
    }
  ]
}

また、集計属性を反復処理することもできます。次の例では、集計を変数 tly にマッピングし、entrySet を使用して集計の各項目を反復処理します。各項目では、key と value を参照します：

テンプレート

{
  "MyTally": {
    {{#each tly.entrySet}}
      "{{key}}": {{value.toInteger}}{{#iter.hasNext}},{{/iter.hasNext}}
    {{/each}}
  }
}

レンダリングされた値

"MyTally": {
    "A": "1",
    "B": "2",
    "C": "3"
}

ヘルパー関数

テンプレートで追加の機能を提供するために、いくつかのヘルパー関数がサポートされています。

詳細については、テンプレートヘルパー関数を参照してください。

参考文献

コネクタテンプレートは、Mustacheに基づいたJavaテンプレートエンジンであるTrimouをベースに構築されています。

• Trimou 2.3.0 ドキュメント