Webhook - カスタムリクエストの送信 - テンプレート変数ガイド

前提条件

• Webhook - アクションパラメータ
• Webhook - Trimouテンプレートエンジンガイド

概要

カスタムリクエストが複雑なペイロード（ネストされたJSONやXMLなど）を必要とする場合、ベンダーのエンドポイントが必要とする形式でペイロードを構築するためにテンプレートオプションを使用します。データレイヤーの属性は、カスタムテンプレート変数にマッピングでき、その結果、任意のテンプレート内で参照できます。このガイドでは、単一のキー/値ペアと配列値の両方のテンプレート変数の作成方法を示します。

単一値変数

テンプレート変数の最も一般的な使用法は、属性から動的な値をテンプレート内のプレースホルダーに渡すことです。テンプレート変数は、その名前を二重中括弧で囲むことで、任意のテンプレートで参照できます。例：{{VARIABLE NAME}}。

以下は、ショッピングカートのステータスを追跡するために必要なペイロードの例です：

{
    "userEmail" : "bob@email.com",
    "total"     : 9.99,
    "discount"  : "10%",
    "date"      : "2016-07-13T12:30:59.000Z"
}

各値が動的であり、対応する属性によって入力される必要があることがわかります。このペイロードの各値の名前は、リクエストの形式に対するベンダーの要件です。テンプレート変数は、このようなリクエストに属性値を入力する方法です。

このペイロードを作成するために必要なテンプレートは、以下のようになるかもしれません。ここでは、値が使用するテンプレート変数を参照するプレースホルダーに置き換えられています：

{
    "userEmail" : "{{userEmail}}",
    "total"     : {{itemTotal}},
    "date"      : "{{date}}",
    "discount"  : "{{discount}}"
}

テンプレート変数を使用してこれを達成する方法は次のとおりです：

1. まず、Body Dataに含めたい属性を特定します。この例では、次のカートの詳細を使用します：

   Data Layer Attribute	Type	Template Variable	Value
   Cart User Email	String	userEmail	user@example.com
   Cart Total	Number	itemTotal	9.99
   Cart Date	Date	date	2016-07-13T12:30:59.000Z
   Cart Discount	String	discount	10%

2. テンプレート変数セクションで、各属性を選択したテンプレート変数名にマッピングします。
3. テンプレートセクションで、ベンダーの仕様に従った適切なテンプレートを構築します。このテンプレートには有用な名前を付けてください。なぜなら、これも後で二重中括弧で参照されるからです。このテンプレートは"cartdetails"と呼びます。
4. Body Dataセクションで、Custom Valueの{{cartdetails}}をBodyにマッピングします。

ネストマップ：1レベルのオブジェクト配列

JSONのオブジェクト配列を構築するには、配列属性と特別な"ドット名"表記をテンプレート変数の命名に使用する必要があります。この表記を使用すると、".“の前に来る名前の部分が自動的にその名前で参照されるテンプレート内のセクションの使用を可能にします。この仕組みを理解するための例を見てみましょう。

以下は、ショッピングカートの内容を追跡するために必要なペイロードの例です：

{
    "cart": [{
        "item"    : "Plate",
        "quantity": "1",
        "price"   : "5.00",
        "id"      : "001"
    },
    {
        "item"    : "Fork",
        "quantity": "2",
        "price"   : "0.99",
        "id"      : "002"
    },
    {
        "item"    : "Mug",
        "quantity": "1",
        "price"   : "6.99",
        "id"      : "003"
    }]
}

このようなペイロードを構築するためには、以下のようなテンプレートが必要になります：

{
    "cart": [
    {{#cart}}
    {
        "item"     : "{{item}}",
        "quantity" : "{{quantity}}",
        "price"    : "{{price}}",
        "id"       : "{{id}}"
    }{{#iter.hasNext}}, {{/iter.hasNext}}
    {{/cart}}
    ]
}

この例では、テンプレート変数でドット名を使用してcartをプレフィックスとして使用します。例：cart.item

以下に、必要なテンプレート変数の定義方法を示します：

オブジェクトの配列に対する制限

• ネストされた要素は1レベルまでしかサポートされていません。より深いJSON構造は不可能です。
• データレイヤー属性はすべて同じ長さの配列でなければなりません。

カスケードマップ：オブジェクト全体に値を構成

単一のデータ属性をすべての配列オブジェクトにカスケードすることが可能です。変数名が特別な"ピリオド"文字表記に従っている限り、すべての非セットオブストリング属性がカスケードされます。

例：

結果となるJSON：

{
 "cart": [
	  {
	   "item": "Plate",
	   "transactionId": "T1284"
	  },
	  {
	   "item": "Fork",
	   "transactionId": "T1284"
	  },
	  {
	   "item": "Mug",
	   "transactionId": "T1284"
	  }
	 ]
}