Webhookコネクタ構成ガイド
この記事では、Webhookコネクタの構成方法について説明します。
Webhookコネクタについて
Webhookコネクタを使用すると、カスタマイズされたHTTPリクエストを使用してデータをベンダーに送信し、URL、URLパラメータ、ヘッダー、クッキー、ボディコンテンツタイプ、ボディデータなど、HTTPリクエストのすべての側面を構成できます。Webhookはバッチ処理と、複雑で動的なデータ形式を扱うために設計された強力なテンプレート機能もサポートしています。
ベンダーの認証要件に基づいて選択できるWebhookコネクタは4種類あります：
- Webhook (BasicAuth)：認証が不要、またはユーザー名とパスワードのみの基本認証が必要なサービス用。
- Webhook OAuth2 (3-Legged)：ユーザーがサービスにログインしてアクセストークンを取得する必要があります。
- Webhook OAuth2 (2-Legged)：ユーザーがサービスにログインする必要はありません。Webhookは認証に必要な情報を構成します。
- Webhook JWT：JSON Webトークン認証を使用します。ユーザーがサービスにログインする必要はありません。Webhookは認証に必要な情報を構成します。
Webhook OAuth2は、OAuth 2.0認証を明示的に要求するサービスに使用されます。
始めるには、コネクタマーケットプレイスにアクセスし、使用したいWebhookインスタンスを追加します。コネクタの追加方法については、コネクタ概要を参照してください。
次のセクションでは、各タイプのWebhookコネクタの構成について説明します。
Webhook (BasicAuth) 構成
このWebhookは、HTTPヘッダーフィールド Authorization を使用して基本HTTP認証をサポートします。認証情報は {username}:{password} のBase64エンコードされた文字列として渡されます。
BasicAuth Webhook構成のための以下の構成を使用します：
- タイトル
- 必須
- Webhookの説明的なタイトルを入力します。
- BasicAuth ユーザー名
- Webhookの認証用ユーザー名を入力します。
- BasicAuth パスワード
- Webhookの認証用パスワードを入力します。
- JWT 認証
- JSON Webトークンを入力します。
次へをクリックするか、アクションタブに進みます。
- アクションタブを使用して、トリガーするHTTPリクエストを構成します。
Webhook OAuth2 (3-Legged) 構成
このWebhookのOAuth実装はサーバーサイドアプリケーションのみをサポートします。
OAuth 2.0サービスにWebアプリケーションを登録することを忘れないでください。アプリケーションはリダイレクトURLを許可するように構成する必要があります：https://my.tealiumiq.com/oauth/webhook/callback.html
OAuth2 (3-legged) Webhook構成のための以下の構成を使用します：
- クライアントID
- 必須。
- OAuthサービスから割り当てられたアプリケーションのクライアント識別子を入力します。
- クライアントシークレット
- 必須。
- OAuthサービスから割り当てられたアプリケーションのクライアントシークレットを入力します。
- スコープ
- アプリケーションへのアクセス許可を要求するタイプを選択します。
- 認証URL
- 必須。
- ユーザーを認証後にリダイレクトするURLを入力します。
- 認証URLクエリパラメータ
- 認証URLのための1つ以上の名前-値ペアを選択します。
- 複数のペアをアンパサンド (
&) を使用して区切ります。 - 先頭にアンパサンド (
&) を使用しないでください。- 正しい:
access_type=offline&prompt=consent - 誤り:
&access_type=offline&prompt=consent
- 正しい:
- アクセストークンURL
- 必須。
- リフレッシュトークンを取得するためのトークンURLを入力します。
接続を確立をクリックして接続をテストします。
Webhook OAuth2 (2-Legged) 構成
TealiumのWebhook OAuth2コネクタは、OAuth2 Two-Legged認証を必要とするAPIに完全にカスタマイズされたデータをHTTPリクエストとして送信することを可能にします。これはクライアント資格情報とリソースオーナーパスワード資格情報の付与をサポートします。
コネクタを追加した後、OAuth2 2-Legged Webhook構成のための以下の構成を使用します：
- アクセストークンURL
- 必須。
- アクセストークンを要求するAPIエンドポイントURLを入力します。
- クライアントID
- 必須。
- WebアプリケーションのクライアントIDを入力します。
- クライアントIDはクライアント資格情報の付与タイプのリクエストボディに構成されます。
- クライアントシークレット
- 必須。
- Webアプリケーションのクライアントシークレットを入力します。
- クライアントシークレットはクライアント資格情報の付与タイプのリクエストボディに構成されます。
- ユーザー名
- ユーザー名を入力します。
- パスワード付与タイプを使用する場合、ユーザー名が必要です。
- トークンエンドポイントが基本認証ヘッダーも要求する場合は、クライアント認証IDとクライアント認証シークレットを入力します。
- パスワード
- パスワードを入力します。
- パスワード付与タイプを使用する場合、パスワードが必要です。
- クライアント認証ID
- 認証ヘッダーの一部として送信するクライアントID。
- クライアント認証シークレット
- 認証ヘッダーの一部として送信するクライアントシークレット。
- スコープ
- 要求する権限の範囲を選択します（一部のOAuth2サービスでのみ必要）。
- 追加の認証パラメータ
- 追加の認証パラメータを追加します（一部のOAuth2サービスでのみ必要）。
- 複数のパラメータを
&で区切ります。
- 認証トークンの位置
- 認証トークンを配置する場所を指定します。
- 認証ヘッダープレフィックス
- デフォルト値は
Bearerです。 - 新しい値を指定して上書きします（一部のOAuth2サービスでのみ必要）。
- デフォルト値は
すべてのWebhookアクションのためのアクションパラメータ
以下のパラメータはすべてのWebhookアクションで利用可能です。
| 入力フィールド | 必須/オプション | テンプレートサポート | 備考 |
|---|---|---|---|
| メソッド | 必須 | 次のメソッドをサポートしています：
|
|
| URL パラメータ | 任意 | ✔ |
|
| ヘッダー | Webhook（BasicAuth）では任意、Webhook OAuth2では必須 | ✔ |
|
| クッキー | 任意 | ✔ |
|
| ボディコンテンツタイプ | 任意 |
|
|
| ボディデータ | 任意 | ✔ |
|
| バッチングオプション | 任意 | ✔ |
|
| テンプレート変数 | 任意 |
|
|
| テンプレート | 任意 |
|
テンプレートサポートについて: カスタムテンプレートからフィールド値を入力することができます。例えば、テンプレートが some-template と名付けられている場合、その内容は {{some-template}} を参照することでフィールドに注入されます。
要件
- EventStream用に有効化されたTealiumアカウント（イベントデータ用）
- AudienceStream用に有効化されたTealiumアカウント（訪問データ用）
コネクタアクション
| アクション名 | 説明 | Webhook (BasicAuth) | Webhook OAuth2 |
|---|---|---|---|
| HTTPリクエストを介してイベントデータを送信 | イベントオブジェクト全体を、URLエンコードされたJSON文字列またはJSONペイロードとして送信します。 | ✓ | ✗ |
| HTTPリクエストを介して訪問データを送信 | 訪問プロファイルオブジェクト全体を、URLエンコードされたJSON文字列またはJSONペイロードとして送信します。 | ✓ | ✗ |
| HTTPリクエストを介してカスタマイズされたデータを送信 (Advanced) | マッピングを通じて指定された個々のイベント/訪問属性を送信します。 | ✓ | ✓ |
| HTTPリクエストを介してバッチ処理されたカスタマイズされたデータを送信 (Advanced) | マッピングを通じて指定されたバッチ処理されたイベント/訪問属性を送信します。 | ✓ | ✓ |
構成の構成
コネクタマーケットプレースにアクセスして新しいコネクタを追加します。コネクタを追加する一般的な手順については、コネクタ概要記事を読んでください。
コネクタを追加した後、次の構成を構成します：
-
基本認証
- ユーザー名 (任意)
- APIエンドポイントが基本認証を要求する場合はユーザー名を入力してください
-
基本認証
- パスワード (任意)
- APIエンドポイントが基本認証を要求する場合はパスワードを入力してください
アクション構成 - パラメータとオプション
次へをクリックするか、アクションタブに進みます。ここでコネクタアクションを構成します。
このセクションでは、各アクションのパラメータとオプションの構成方法について説明します。
アクション - HTTPリクエストを介してイベントデータを送信
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| テンプレート変数 |
|
| テンプレート |
|
| 属性名の印刷 |
|
| リダイレクション |
|
アクション - HTTPリクエストを介して訪問データを送信する
パラメータ
| パラメータ | 説明 | |:—————————|:——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————–|| メソッド |
- 必須
- リクエストメソッドを選択してください。
- GET が選択された場合、訪問データは
dataキーで JSON URLエンコードされたクエリ文字列パラメータとして配信されます。
- 必須。
- リクエストを送信するURLを提供してください。
- テンプレートサポート：テンプレート名を参照してURLを生成します。
- オプション。
- URLに追加するパラメータを提供してください。
- テンプレートサポート：テンプレート名を参照してパラメータ値を生成します。
- オプション。
- HTTPヘッダー名にヘッダー値をマッピングします。
- テンプレートサポート：テンプレート名を参照してヘッダー値を生成します。
- オプション。
- クッキー名にクッキー値をマッピングします。
- クッキーは単一のHTTPヘッダー値として追加されます。例：
Cookie: name1=value1; name2=value2 - テンプレートサポート：テンプレート名を参照してクッキー値を生成します。
- オプション。
- 利用可能なタイプを選択するか、カスタム値を提供してください。
- すべてのタイプはUTF-8でエンコードされ、ヘッダーとして追加されます。例：
Content-Type: text/plain; charset=UTF-8 - ボディデータが提供される場合、コンテンツタイプが必要です。
- オプション。
- テンプレートのデータ入力としてテンプレート変数を提供してください。詳細はテンプレート変数ガイドを参照してください。
- ドット表記を使用してネストされたテンプレート変数を名付けます。例：
items.name - ネストされたテンプレート変数は通常、データレイヤーリスト属性から構築されます。
- オプション。
- URL、URLパラメータ、ヘッダー、またはボディデータで参照されるテンプレートを提供してください。詳細はテンプレートガイドを参照してください。
- テンプレートは名前で二重中括弧を使用してサポートされるフィールドに注入されます。例：
{{SomeTemplateName}} - OAuthを使用する場合、テンプレート変数
{{webhook_access_token}}は認証リクエストによって返されるトークンを指します。
- 現在の訪問データを含めたい場合は、このボックスをチェックしてください。
- 属性名が更新された場合、ペイロードには更新された名前が反映されます。
- メソッドがGETの場合のみリダイレクションを許可します。
アクション - HTTPリクエストを介してカスタマイズされたデータを送信する（高度）
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL パラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| ボディデータ |
|
| テンプレート変数 |
|
| テンプレート |
|
アクション - HTTPリクエストを介してバッチカスタマイズデータを送信（高度）
バッチ制限
このアクションは、ベンダーへの大量データ転送をサポートするためにバッチリクエストを使用します。詳細はバッチアクションを参照してください。リクエストは、次のいずれかの閾値に達するか、プロファイルが公開されるまでキューに入れられます：
- 最大リクエスト数：100
- 最古のリクエストからの最大時間：60分
- リクエストの最大サイズ：16 MB
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| ボディコンテンツタイプ |
|
| サフィックス |
|
| プレフィックス |
|
| ジョイナー |
|
| レコード数の最大値 |
|
| 生存時間（分） |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| テンプレート変数 |
|
| テンプレート |
|
イベントデータJSON
イベントに含まれる予想されるJSONペイロードには、イベントの一部である標準属性すべてと、イベントを送信したプラットフォーム固有の追加属性が含まれます。例えば、ウェブサイトから受け取ったイベントにはDOMおよびクッキー属性が含まれ、モバイルデバイスから受け取ったイベントにはデバイスおよびキャリア属性が含まれます。
イベントデータJSONオブジェクトの形式例：
{
"account": "tealium",
"profile": "main",
"env": "prod",
"data": {
"dom": {
"referrer": "",
"domain": "tealium.com",
"title": "Tealium | Customer Data Hub and Enterprise Tag Management",
"query_string": "",
"url": "http://tealium.com/",
"pathname": "/"
},
"udo": {
"tealium_event": "page_view",
"page_name": "Tealium | Customer Data Hub and Enterprise Tag Management",
"page_type": "home",
"device_type": "desktop"
},
"firstparty_tealium_cookies": {
"trace_id": "",
"s_fid": "3EF757DF6253B144-0D0194366CD4479B",
"utag_main_ses_id": 1383677957942,
"s_cc": "true",
"utag_mainst": 1383678970903,
"TID": "2cff51e585ed4a5a9330324d5dbc6bb7",
"s_sq": "[[B]]"
}
},
"post_time": 1500999541000,
"useragent": "PostmanRuntime/6.1.6",
"event_id": "1a1ee055-1456-46f8-ab4d-779628c05dd4",
"visitor_id": "1a1ee055145646f8ab4d779628c05dd4"
}
訪問データJSON
訪問に関連する適用可能な訪問属性をすべて含む予想されるJSONペイロードです。データオブジェクトは属性タイプ別に整理されています。属性が割り当てられていない場合、訪問オブジェクトには表示されません。現在の訪問のデータも current_visit キーの下に含まれます。
訪問データJSONオブジェクトの形式例：
{
"metrics": {
"Weeks since first visit": 0.0,
"Lifetime visit count": 1.0,
"Lifetime event count": 1.0,
"Total direct visits": 1.0
},
"dates": {
"Last visit": 1500999541000,
"last_visit_start_ts": 1500999541000,
"First visit": 1500999541000
```## 使用例
このセクションでは、HTTPリクエストの例を提供します。明確性のために、これらの例では単純なJSONオブジェクトが使用されています。実際に送信されるデータは完全なイベントまたは訪問オブジェクトです。また、追加のパラメータがどのように送信されるかを示すために、`param1` が `value1` の値を受け取る単一のURLパラメータも含まれています。
### イベント/訪問の送信 - GETメソッド
Send Event DataまたはSend Visitor Dataアクションを使用する場合、GETメソッドではデータが `data` という名前の単一のクエリ文字列パラメータとして送信されます。値はイベント/訪問データオブジェクトのURLエンコードされたJSON文字列です。構成されたURLパラメータは追加のクエリ文字列パラメータとして追加されます。
この例ではデータは以下の通りです：
```json
{
"foo" : "bar"
}
結果のURLエンコードされたJSON文字列は以下の通りです：
%7B%22foo%22%3A%22bar%22%7D
これは最終的なGETリクエストで以下のクエリ文字列パラメータとして表示されます：
data=%7B%22foo%22%3A%22bar%22%7D
**GET** /webhook-service?data=%7B%22foo%22%3A%22bar%22%7D¶m1=value1
VERSION: HTTP/1.1
CONNECTION: close
ACCEPT-ENCODING: gzip
X-HEADER-KEY: header_value
COOKIE: cookie_key=cookie_valie,cfduid=d63c6b0e0a23195e9a7142f314360b4e11502122913
USER-AGENT: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
イベント/訪問の送信 - POSTメソッド
以下は、application/json および application/x-www-form-urlencoded コンテンツタイプのPOSTリクエストのサンプルです。
Content-Type: application/json
本文データはJSONペイロードとして送信されます。
POST /webhook-service?param1=value1
VERSION: HTTP/1.1
CONNECTION: close
ACCEPT-ENCODING: gzip
X-HEADER-KEY: header_value
COOKIE: cookie_key=cookie_valie
CONTENT-TYPE: application/json; charset=UTF-8
USER-AGENT: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
CONTENT-LENGTH: 13
{
"foo": "bar"
}
Content-Type: application/x-form-urlencoded
本文データは data という名前のフォームデータフィールドを使用してURLエンコードされたJSON文字列として送信されます。
POST /webhook-service?param1=value1
VERSION: HTTP/1.1
CONNECTION: close
ACCEPT-ENCODING: gzip
X-HEADER-KEY: header_value
COOKIE: cookie_key=cookie_valie,cfduid=d63c6b0e0a23195e9a7142f314360b4e11502122913
CONTENT-TYPE: application/x-www-form-urlencoded; charset=UTF-8
USER-AGENT: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
CONTENT-LENGTH: 32
data=%7B%22foo%22%3A%22bar%22%7D
最終更新日 :: 2022年June月23日