# Yelp Conversions API エクスポート連携

## 概要

Yelp Conversions API（CAPI）コネクタは、Yelp 広告キャンペーンのオフライン/サーバーサイドコンバージョンイベントのサーバーサイドトラッキングと測定を可能にします。Yelp の Conversions API と直接連携することで、マルチロケーション広告主がキャンペーンパフォーマンスの測定、広告アトリビューションの改善、ROAS（広告費用対効果）測定の最適化を実現します。

主な機能：

- **オフラインコンバージョン**: Yelp プラットフォーム外で発生した購入、リード、その他のコンバージョンイベントを追跡
- **PII ハッシュ化**: ユーザー識別子（メール、電話番号、名前など）の SHA-256 自動ハッシュ化によるプライバシー準拠のマッチング
- **データ正規化**: Yelp CAPI 仕様に準拠した自動フィールド正規化


このサーバーサイド連携により、広告主は Yelp 広告のクリックとダウンストリームコンバージョン間のアトリビューションループを閉じ、より完全な ROAS 測定を実現できます。

## 前提条件

- Treasure AI の基本的な知識（TD Toolbelt を含む）。
- Yelp Ads が有効な Yelp Business アカウント。
- Yelp デベロッパーアプリの認証情報から取得した Yelp API キー（Bearer トークン）。


## 制限事項と既知の問題

- **日次レート制限**: 1日あたり50,000イベントの上限があり、大規模なエクスポートが制限される場合があります。複数日にわたるバッチ処理/スケジューリングが必要になる場合があります。
- **レート制限**: 1秒あたり100リクエスト。コネクタはスロットリングと指数バックオフを実装しています。
- **限定的なイベントタイプ**: カスタムイベントは `custom_` プレフィックスが必要で、英数字、アンダースコア、ハイフンのみ使用可能です。
- **単一値配列**: ユーザーデータの配列フィールド（email、phone、country、state、zip_code、city、external_id）は、単一の値を持つ配列として送信されます。
- **content_category/content_ids 非対応**: `custom_data.content_category`、`custom_data.content_ids`、`custom_data.contents`、`custom_data.event_labels` は初期リリースではサポートされていません。


## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[IP Addresses for Integrations](/apis/endpoints/ip-addresses-integrations-result-workers)

## Data Workbench を使用した接続の作成

Data Workbench では、クエリを実行する前にデータ接続を作成・設定する必要があります。データ接続の一部として、連携にアクセスするための認証を提供します。

### 新しい認証の作成

1. **Data Workbench** を開きます。
2. **Integrations Hub** > **Catalog** に移動します。
3. **Yelp Conversions API** を検索して選択します。
4. **Create Authentication** を選択します。
5. 認証のための認証情報を入力します：


| パラメータ | 説明 |
|  --- | --- |
| API key | 必須。Yelp デベロッパーアプリの認証情報から取得した Yelp API キー（Bearer トークン）。 |


1. **Continue** を選択します。
2. 接続の名前を入力します。
3. **Done** を選択します。


### クエリの定義

1. **Data Workbench > Queries** に移動します。
2. **New Query** を選択します。
3. クエリを実行して結果セットを検証します。



```sql
SELECT
  transaction_id AS event_id,
  time AS event_time,
  'purchase' AS event_name,
  'website' AS action_source,
  email,
  first_name,
  last_name,
  phone,
  birthday,
  gender,
  country,
  state,
  zip_code,
  city,
  external_id,
  ip_address,
  user_agent,
  lead_id,
  total_amount AS value,
  'USD' AS currency,
  order_id
FROM
  my_database.conversions
WHERE
  TD_TIME_RANGE(time, TD_TIME_ADD(TD_SCHEDULED_TIME(), '-1d'), TD_SCHEDULED_TIME())
  AND email IS NOT NULL
```

1. クエリでカラムマッピングを定義する必要があります。クエリのカラムは Yelp Conversions API に送信されるデータを表します。


マッチングには少なくとも1つのユーザー識別子が必要です。推奨される識別子：

- email
- phone
- external_id
- lead_id


### エクスポート先の指定

1. **Export Results** を選択します。
2. 既存の Yelp Conversions API 認証を選択するか、上記の手順で新しい認証を作成します。
3. エクスポートパラメータを設定します：


| フィールド | 説明 |
|  --- | --- |
| Upload Mode | イベント送信のアップロードモード。現在は `single_event`（1リクエストにつき1イベント）のみサポートされています。**デフォルト: single_event** |
| Skip Invalid Records | 有効にすると、バリデーションに失敗したレコードをスキップし、ジョブ全体を失敗させません。**デフォルト: false** |
| Test Event | 有効にすると、すべてのバリデーションを通常通り実行しますが、データを本番環境に送信しません。ライブデータを送信する前にデータパイプラインを検証するために使用します。**デフォルト: false** |


1. **Done** を選択します。


### クエリ結果データ仕様の詳細ガイド

Yelp Conversions API にイベントデータをアップロードするには、Yelp CAPI ガイドラインに準拠した標準フィールドの組み合わせを含むデータエクスポートクエリを作成する必要があります。カラム名が「フィールド/カラムレベルの仕様」セクションに記載されたものと一致することを確認してください。

コネクタはカラム名を自動的に正規化します（大文字小文字を区別しないマッチング）。例えば、「event_name」フィールドの場合、エクスポートクエリのカラム名は「EVENT_NAME」、「event_name」、「Event_Name」のいずれでも記述できます。

Yelp CAPI にコンバージョンデータを正常にアップロードするには、特定のデータ仕様に準拠したエクスポートクエリを構築する必要があります。これらの仕様は2つのレベルに分かれています：

- **エクスポートクエリ仕様**（データセットレベルのデータ仕様）：必須フィールドの存在やクロスフィールドバリデーションルールなど、クエリ結果データセット全体に適用される要件とルール。
- **フィールド/カラムレベルの仕様**：データ型、フォーマット、正規化ルールなど、データセット内の個々のフィールド/カラムの要件とルール。


#### エクスポートクエリ仕様

| 仕様 | 説明 |
|  --- | --- |
| **必須フィールド** | エクスポートクエリに以下のフィールドが存在する必要があります：- `event_time`
- `event_name`
- `action_source`

 |
| **PURCHASE イベントの条件付き必須フィールド** | エクスポートクエリに purchase イベント（`event_name = 'purchase'`）が含まれる場合、以下のフィールドが必須です：- `value`（数値、非負である必要があります）

 |
| **標準フィールド名** | 標準フィールドのカラム名は任意の大文字小文字で記述できます（例：「EVENT_NAME」、「event_name」、「Event_Name」）。コネクタが自動的に標準化します。 |
| **NULL 値の処理** | NULL 値を持つカラムはエクスポート時に無視されます。 |
| **重複カラム** | エクスポートクエリ内でのカラム名の重複は許可されていません（大文字小文字を区別しないチェック）。 |
| **日時フォーマット** | `event_time` フィールドでは、以下のフォーマットが受け付けられます：- 整数（Unix エポックタイムスタンプ、秒単位）
- ISO 8601 フォーマット文字列（タイムゾーンあり/なし。タイムゾーンなしの場合は UTC として扱われます）
- Timestamp データ型

 |
| **ハッシュフィールドの処理**
 | `user_data` オブジェクトで SHA-256 ハッシュが必要なフィールド（email、phone、first_name、last_name、birthday、gender、country、state、zip_code、city、external_id）について、コネクタは以下を行います：
1. データの正規化（小文字化、トリム、該当する場合は句読点の除去）
2. SHA-256 ハッシュの自動適用

生データ（ハッシュ化されていないデータ）を提供してください。コネクタがすべての正規化とハッシュ化を処理します。
 |


#### フィールド/カラムレベルの仕様

##### サーバーパラメータ（トップレベルフィールド）

| カラム | データ型 | 必須 | 正規化 | 説明 |
|  --- | --- | --- | --- | --- |
| event_id | string | いいえ | 最大128文字 | 重複排除のための一意の識別子。 |
| event_time | long/string/timestamp | はい | Unix タイムスタンプ（秒単位）、過去である必要あり | コンバージョンイベントが発生した時刻。Unix エポック（秒）、ISO 8601 文字列、または timestamp 型を受け付けます。 |
| event_name | string | はい | 最大50文字。カスタム値は "custom_" で始まり、A-Z、a-z、0-9、_、- のみ含むこと | コンバージョンイベントタイプ。標準値：`purchase`、`lead`。カスタム値は `custom_` プレフィックスが必要です。 |
| action_source | string | はい | website、app、physical_store のいずれか | コンバージョンイベントのソース。 |


##### ユーザーデータフィールド

以下のフィールドは、コンバージョンマッチングのためにユーザーを識別するために使用されます。正確なマッチングには、少なくとも1つのユーザー識別子（email、phone、external_id、または lead_id）が推奨されます。

| カラム | 送信先フィールド | データ型 | 必須 | 正規化 | 説明 |
|  --- | --- | --- | --- | --- | --- |
| email | user_data.em | string | いいえ | 小文字化、トリム、SHA-256 ハッシュ | ユーザーのメールアドレス。配列として送信されます。 |
| first_name | user_data.fn | string | いいえ | 小文字化、スペースと句読点を除去、SHA-256 ハッシュ | ユーザーの名。 |
| last_name | user_data.ln | string | いいえ | 小文字化、スペースと句読点を除去、SHA-256 ハッシュ | ユーザーの姓。 |
| phone | user_data.ph | string | いいえ | +/-/()/スペースを除去。数字のみ、先頭ゼロなし。国コードを含む必要あり（例：12031231234）。10桁の場合、先頭に1を自動追加。SHA-256 ハッシュ | ユーザーの電話番号。配列として送信されます。 |
| birthday | user_data.db | string | いいえ | YYYYMMDD フォーマット、SHA-256 ハッシュ | ユーザーの生年月日。 |
| gender | user_data.ge | string | いいえ | 小文字化、f、m、n のいずれか。SHA-256 ハッシュ | ユーザーの性別。 |
| country | user_data.country | string | いいえ | 小文字の2文字 ISO-3166 コード、SHA-256 ハッシュ | ユーザーの国。配列として送信されます。 |
| state | user_data.st | string | いいえ | 小文字の2文字略称、SHA-256 ハッシュ | ユーザーの州/都道府県。配列として送信されます。 |
| zip_code | user_data.zp | string | いいえ | 小文字の英数字、SHA-256 ハッシュ | ユーザーの郵便番号。配列として送信されます。 |
| city | user_data.ct | string | いいえ | 小文字化、スペースと句読点を除去、SHA-256 ハッシュ | ユーザーの都市。配列として送信されます。 |
| external_id | user_data.external_id | string | いいえ | SHA-256 ハッシュ | マッチングのための外部識別子。配列として送信されます。 |
| ip_address | user_data.client_ip_address | string | いいえ | なし（パススルー）。IPv4 と IPv6 をサポート。 | ユーザーの IP アドレス。 |
| user_agent | user_data.client_user_agent | string | いいえ | なし（パススルー） | ユーザーのブラウザエージェント文字列。 |
| madid | user_data.madid | string | いいえ | なし（パススルー） | モバイル広告 ID。 |
| lead_id | user_data.lead_id | string | いいえ | なし（パススルー） | クリックトラッキングからの Yelp リード ID。 |


##### カスタムデータフィールド

| カラム | 送信先フィールド | データ型 | 必須 | 正規化 | 説明 |
|  --- | --- | --- | --- | --- | --- |
| value | custom_data.value | double | はい（purchase の場合） | 数値、非負 | コンバージョンの金額。event_name が "purchase" の場合に必須。 |
| currency | custom_data.currency | string | いいえ | USD、CAD のいずれか | コンバージョン値の通貨コード。 |
| order_id | custom_data.order_id | string | いいえ | なし（パススルー） | 注文識別子。 |


##### 重要な注意事項：

1. **電話番号のフォーマット**: 電話番号には国コード、市外局番、番号を含める必要があります。コネクタは許可された文字（+、-、括弧、スペース）を除去し、数字のみを検証して、以下のルールを適用します：
  - 10桁：先頭に "1" を自動追加
  - "1" で始まる場合：正確に11桁である必要あり
  - その他の国コード：最大15桁
2. **自動処理**: コネクタはすべての PII フィールドに対してフィールドの正規化（小文字化、トリム、句読点の除去）と SHA-256 ハッシュ化を自動的に処理します。
3. **エラー収集**: レコードのすべてのバリデーションエラーがまとめて収集・報告されるため、データの問題を診断しやすくなります。


### (オプション) Query Export ジョブをスケジュールする

Scheduled Jobs と Result Export を使用して、指定したターゲット宛先に出力結果を定期的に書き込むことができます。

Treasure Data のスケジューラー機能は、高可用性を実現するために定期的なクエリ実行をサポートしています。

2 つの仕様が競合するスケジュール仕様を提供する場合、より頻繁に実行するよう要求する仕様が優先され、もう一方のスケジュール仕様は無視されます。

例えば、cron スケジュールが `'0 0 1 * 1'` の場合、「月の日」の仕様と「週の曜日」が矛盾します。前者の仕様は毎月 1 日の午前 0 時 (00:00) に実行することを要求し、後者の仕様は毎週月曜日の午前 0 時 (00:00) に実行することを要求するためです。後者の仕様が優先されます。

#### Treasure コンソール を使用してジョブをスケジュールする

1. **Data Workbench > Queries** に移動します
2. 新しいクエリを作成するか、既存のクエリを選択します。
3. **Schedule** の横にある None を選択します。
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| ドロップダウン値 | 説明 |
|  --- | --- |
| Custom cron... | [Custom cron... の詳細](#custom-cron-details)を参照してください。 |
| @daily (midnight) | 指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。 |
| @hourly (:00) | 毎時 00 分に実行します。 |
| None | スケジュールなし。 |


#### Custom cron... の詳細

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron 値** | **説明** |
|  --- | --- |
| `0 * * * *` | 1 時間に 1 回実行します。 |
| `0 0 * * *` | 1 日 1 回午前 0 時に実行します。 |
| `0 0 1 * *` | 毎月 1 日の午前 0 時に 1 回実行します。 |
| "" | スケジュールされた実行時刻のないジョブを作成します。 |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

次の名前付きエントリを使用できます:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


各フィールド間には単一のスペースが必要です。各フィールドの値は、次のもので構成できます:

div
| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'0 0 1 * *'` | 毎月 1 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 範囲 `'2-5'`
フィールドの許可される値の範囲を示します。 | `'0 0 1-10 * *'` | 毎月 1 日から 10 日までの午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| カンマ区切りの値のリスト `'2,3,4,5'`
フィールドの許可される値のリストを示します。 | `0 0 1,11,21 * *'` | 毎月 1 日、11 日、21 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 周期性インジケータ `'*/5'`
フィールドの有効な値の範囲に基づいて、
スケジュールが実行を許可される頻度を表現します。 | `'30 */2 1 * *'` | 毎月 1 日、00:30 から 2 時間ごとに実行するようにスケジュールを設定します。
`'0 0 */5 * *'` は、毎月 5 日から 5 日ごとに午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| `'*'`
ワイルドカードを除く上記の
いずれかのカンマ区切りリストもサポートされています
`'2,*/5,8-10'` | `'0 0 5,*/10,25 * *'` | 毎月 5 日、10 日、20 日、25 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |


1. (オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。


## Audience Studio で Segment をアクティベートする

Audience Studio で activation を作成することで、segment データをターゲットプラットフォームに送信することもできます。

1. **Audience Studio** に移動します。
2. parent segment を選択します。
3. ターゲット segment を開き、右クリックして、**Create Activation** を選択します。
4. **Details** パネルで、Activation 名を入力し、前述の Configuration Parameters のセクションに従って activation を設定します。
5. **Output Mapping** パネルで activation 出力をカスタマイズします。


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - **Export All Columns** を選択すると、変更を加えずにすべての列をエクスポートできます。
  - **+ Add Columns** を選択して、エクスポート用の特定の列を追加します。Output Column Name には、Source 列名と同じ名前があらかじめ入力されます。Output Column Name を更新できます。**+ Add Columns** を選択し続けて、activation 出力用の新しい列を追加します。
- String Builder
  - **+ Add string** を選択して、エクスポート用の文字列を作成します。次の値から選択します:
    - String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    - Timestamp: エクスポートの日時。
    - Segment Id: segment ID 番号。
    - Segment Name: segment 名。
    - Audience Id: parent segment 番号。


1. **Schedule** を設定します。


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- スケジュールを定義する値を選択し、オプションでメール通知を含めます。


1. **Create** を選択します。


batch journey の activation を作成する必要がある場合は、[Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation) を参照してください。

## （オプション）ワークフローでエクスポート結果を設定

Treasure Workflow 内でこの連携を使用してデータをエクスポートできます。

詳細については、[TD Toolbelt を使用したワークフローでのデータエクスポート](https://docs.treasuredata.com/smart/project-product-documentation/exporting-data-with-parameters)を参照してください。


```yaml
_export:
  td:
    database: my_database

+yelp_conversions_export:
  td>: export_yelp_conversions.sql
  database: ${td.database}
  result_connection: {your_connection_name}
  result_settings:
    upload_mode: single_event
    skip_invalid_records: false
    test_event: false
```

## （オプション）CLI を使用したエクスポート連携

CLI（Toolbelt）を使用して Yelp Conversions API へのエクスポートも可能です。

`td query` コマンドの `--result` オプションで Yelp Conversions へのエクスポート情報を指定する必要があります。`td query` コマンドについては、[こちらの記事](https://docs.treasuredata.com/smart/project-product-documentation/td-toolbelt-job-and-query-command-reference)を参照してください。

オプションのフォーマットは JSON で、一般的な構造は以下の通りです。


```json
{
  "type": "yelp_conversion",
  "api_key": "your-yelp-api-key-here",
  "upload_mode": "single_event",
  "skip_invalid_records": false,
  "test_event": false
}
```

### パラメータ

| 名前 | データ型 | 説明 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | string | コネクタタイプ識別子。 | N/A | はい（`yelp_conversion` を指定） |
| api_key | string | 認証用の Yelp API キー（Bearer トークン）。 | N/A | はい |
| upload_mode | string | アップロードモード。現在は `single_event` のみサポート。 | single_event | いいえ |
| skip_invalid_records | boolean | 有効にすると、無効なレコードをスキップしてジョブを続行します。 | false | いいえ |
| test_event | boolean | 有効にすると、本番環境に送信せずにデータを検証します。 | false | いいえ |


### 使用例


```bash
td query --result '{"type":"yelp_conversion","api_key":"your-api-key","upload_mode":"single_event","skip_invalid_records":false,"test_event":false}' -d my_database "SELECT transaction_id AS event_id, time AS event_time, 'purchase' AS event_name, 'website' AS action_source, email, total_amount AS value, 'USD' AS currency FROM conversions" -T presto
```

## 関連記事

- [Yelp Conversions API ドキュメント](https://docs.developer.yelp.com/docs/conversions-api)
- [Yelp Conversions API ハッシュガイド](https://docs.developer.yelp.com/docs/conversions-api#hashing-data)
- [Yelp Conversions API 正規化ガイド](https://docs.developer.yelp.com/docs/conversions-api#normalizing-data)