# Yahoo Ads Conversion Export Integration

Yahoo Adsにおいて、コンバージョンとは、広告をクリックした後にユーザーがウェブサイト上で行う特定のアクションを指します。このアクションは通常、広告主によって事前に定義され、商品の購入、フォームへの入力、ニュースレターの購読、アプリのダウンロードなどが含まれます。Yahoo Adsのコンバージョントラッキング機能により、広告主は、広告をクリックした後にユーザーが目的のアクションを完了した回数をカウントすることで、広告キャンペーンの効果を追跡・測定できます。このデータを使用して、広告キャンペーンを最適化し、全体的なパフォーマンスを向上させることができます。

詳細については、[Yahoo! JAPAN Ads Help](https://ads-help.yahoo-net.jp/s/?language=en_US)を参照してください。

## この連携で何ができるか?

- このTD Export連携により、Treasure Dataからジョブ結果をYahoo! Ads Conversionに直接書き込むことができます。


## 前提条件

- Yahoo! JAPAN IDを取得してください。**[こちら](https://account.edit.yahoo.co.jp/registration?.src=developer&.done=https%3A%2F%2Fdeveloper.yahoo.co.jp%2Fstart%2F)**から取得できます。
- 次に、[アプリケーションを登録](https://e.developer.yahoo.co.jp/register)してClient IDを発行します。


## 要件と制限事項

- Yahoo Display Adsのみをサポート。Yahoo Search Adsはサポートされていません。
- イベントペイロードがYahoo CAPIのルールに一致することを検証します。
- 1秒あたり500リクエストというAPIのレート制限を超えないようにします。
- SHA-256を使用して一部のPII（個人識別情報）フィールドをハッシュ化します。
- ローカル検証に合格しない無効なレコードをスキップすることをサポートします。
- 一般的なHTTPエラー（429、500など）での再試行をサポートします。
- 処理済み、失敗、成功したレコード数をログに記録します。


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

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

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

## TD Consoleを使用して接続を作成する

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

### 新しい認証を作成する

1. **TD Console**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. Yahooを検索し、**Yahoo! Ads Conversion API**を選択します。
4. **Create Authentication**を選択します。
5. 認証するための認証情報を入力します。


| Parameter | Description |
|  --- | --- |
| Application ID | Yahoo! Developer Networkで発行されたApplication ID（Client ID）。 |


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


### クエリを定義する

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


![](/assets/image2023-7-22_9-54-20.175fe02292d8ba18ec28539807ce67024cc8f389ca03c9fd64e78c25ed211798.4713a25f.png)

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


少なくとも、以下のカラムのいずれか1つが存在する必要があります。

- hashed_email
- hashed_phone_number
- yclid
- yjr_yjad


| Column | Data type | Required | Hashing? | Validation | Value (example) | Description |
|  --- | --- | --- | --- | --- | --- | --- |
| hashed_email | string | No
** はい | 2つの形式のいずれか: 1. SHA-256ハッシュ形式 2. 生のメールアドレス | 1. ハッシュ値 **31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66** (メールアドレス: **example@example.com** をSHA-256でハッシュ化する前) 2. 生のメールアドレス (example@example.com)

 | SHA-256を使用してハッシュ化されたメールアドレス。小文字の英数字を使用してください。 |
| hashed_phone_number | string | いいえ | はい | 2つの形式のいずれか: 1. SHA-256ハッシュ形式 2. 国コード付きまたは国コードなしの生の電話番号 | 1. ハッシュ値
**4e6a6c5c6f8a086ce4babac3247364cc93a8a995a1968105d9b408f7e6b72e51**
(電話番号: **090xxxxyyyy** をSHA-256でハッシュ化する前)
2. 生の電話番号 (**0281234567** または +**84281234567**)

 | SHA-256を使用してハイフンなしでハッシュ化された電話番号。小文字の英数字を使用してください。 |
| yclid | string | いいえ | いいえ | N/A | YJAD.1234567890.1EALEzSJBNabcdEFGBE1 | 広告をクリックしたユーザーを識別するためのパラメータ。*_ycl_yjad* Cookieの値を使用します。 |
| yjr_yjad | string | いいえ | いいえ | N/A | 1600000000.f0 | 広告をクリックしたユーザーを識別するためのパラメータ。*_yjr_yjad* Cookieの値を使用します。 |
| event_time | long | はい | いいえ | リクエストから現在時刻と90日前の間の10桁のUnix時間を使用します。符号なし | 1600000000 | コンバージョンが発生した日時。 |
| yahoo_ydn_conv_io | string | はい | いいえ | N/A | 1EALEzSJBNabcdEFGBE1 | アカウント固有の値。
Yahoo! Ads UIの「Conversion APIリクエストパラメータ」にある *yahoo_ydn_conv_io* の値をコピーして貼り付けてください。 |
| yahoo_ydn_conv_label | string | はい | いいえ | N/A | AB0ABCDEFGHIJKLMNOP123456 | タグを識別するためのラベル。
Yahoo! Ads UIの「*Conversion APIリクエストパラメータ*」にある *yahoo_ydn_conv_label* の値をコピーして貼り付けてください。 |
| yahoo_ydn_conv_transaction_id | string | いいえ | いいえ | 64バイトを超えないこと、値の前後にスペースがないことを確認してください。 | order1234 | 重複したコンバージョンをチェックするための一意のID。同じIDを持つ複数のコンバージョンがある場合、タグによって発火されたものが優先されます。 |
| yahoo_ydn_conv_value | long | いいえ | いいえ | 符号なしの有効な数値形式 | 10 | 1つのコンバージョンの価値を表す数値。任意の値、またはYahoo! Ads UIの「*Conversion APIリクエストパラメータ*」にある *yahoo_ydn_conv_value* の値を使用します。 |


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

1. **Export Results**を選択します。


![](/assets/image2021-9-7_15-10-56.ee7ed43caab64adefafcc22595462fd8068c974c4f47b5959a7babd7d99972b8.4713a25f.png)

1. 既存の認証を選択するか、出力に使用する外部サービスの新しい認証を作成できます。次のいずれかを選択します:


**Use Existing Integration**

![](/assets/image2021-9-7_15-28-30.d271866c7c3cea4dab234b61bea815a69b186746c80435855b4b86d1f77cc30e.4713a25f.png)

**新しいインテグレーションの作成**

1. このインテグレーションの名前を入力します。
2. **（オプション）** 他のユーザーとこのインテグレーションを共有したい場合は、**Share with others** をチェックします。
3. Yahoo 認証用の **Application ID (Client ID)** の値を入力します。


![](/assets/image2023-7-22_9-47-2.f14b9e8545cf929b9ed1c926c26a35f4a8b808d4a035c3df350500cdccdaeb4b.4713a25f.png)
4. **Next** をクリックして **Export Results** 設定を開きます。

**Export Results 設定**

![](/assets/image2023-7-22_9-49-31.bf7da510bc68675300c065e0a00251db45c72edca17a4aeb9796bed59dc76994.4713a25f.png)

| フィールド | 説明 |
|  --- | --- |
| Data Operation | 列挙値: Export Yahoo Conversion Data（**デフォルト**） |
| Ignore Invalid Records | このフラグを有効にすると、無効なレコードは無視され、処理フローが続行されます。**デフォルト: false** |
| Maximum Retry | **（オプション）** システムが諦めるまでの再試行回数。**デフォルト: 5、最小: 1、最大: 10。** |
| Seconds to Wait For First Retry | **（オプション）** 1回目と2回目の試行の間の時間（秒単位）。**デフォルト: 15、最小: 10、最大: 60** |
| Seconds for Max Retry Wait | **（オプション）** 2回目以降のすべての試行の間の時間（秒単位）。**デフォルト: 300、最小: 10、最大: 7200**。 |
| Seconds for Connection Timeout | **（オプション）** HTTP 呼び出し操作を中止するまで待機する時間（秒単位）。**デフォルトは 300、最小: 10、最大: 600**。 |
| Seconds for Write Timeout | **（オプション）** HTTP 呼び出し操作の書き込みタイムアウト時間（秒単位）。**デフォルトは 300、最小: 10、最大: 600**。 |
| Seconds for Read Timeout | **（オプション）** HTTP 呼び出し操作の読み取りタイムアウト時間（秒単位）。**デフォルトは 300、最小: 10、最大: 600**。 |


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

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

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

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

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

#### TD Console を使用してジョブをスケジュールする

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.


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

| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'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 を有効にすることで、クエリの開始時刻を遅延させることができます。


### クエリを実行する

クエリに名前を付けて保存して実行するか、単にクエリを実行します。クエリが正常に完了すると、クエリ結果は指定された宛先に自動的にエクスポートされます。

設定エラーにより継続的に失敗するスケジュールジョブは、複数回通知された後、システム側で無効化される場合があります。

(オプション) 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) を参照してください。

## （オプション）ワークフローで Export Results を設定する

Treasure Workflow 内で、このインテグレーションを使用してデータをエクスポートすることを指定できます。

詳細については、[Using Workflows to Export Data with the TD Toolbelt](https://docs.treasuredata.com/smart/project-product-documentation/exporting-data-with-parameters) を参照してください。


```yaml
_export:
  td:
  database: td.database

+yahoo_capi_export_task:
  td>: export_yahoo_capi.sql
  database: ${td.database}
  result_connection: {your_connection_name}
  result_settings:
     app_id: yahoo_app_id
     ignore_invalid_records: true
```

## （オプション）CLI を使用した Export Integration

Yahoo! Ads Conversion への Result Export には、CLI（Toolbelt）も使用できます。

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

このオプションの形式は JSON で、一般的な構造は次のとおりです。

### パラメータ

| 名前 | データ型 | 説明 | 値 | デフォルト値 | 最小値 | 最大値 | 必須 |
|  --- | --- | --- | --- | --- | --- | --- | --- |
| type | string | エクスポート先のサービス名を記述します。 | **yahoo_conversion** | N/A | N/A | N/A | **はい** |
| app_id | string | Application ID または Yahoo Client ID | N/A | N/A | N/A | N/A | **はい** |
| ignore_invalid_records | boolean | 無効なレコードを無視して処理フローを続行するかどうかを指定します。 | **true/false** | false | N/A | N/A | いいえ |
| max_retry | integer | システムが諦めるまでの再試行回数。 | N/A | **5** | **1** | **10** | いいえ |
| initial_retry_wait | integer | 1回目と2回目の試行の間の時間（秒単位）。 | N/A | **15** | **10** | **60** | いいえ |
| max_retry_wait | integer | 2回目以降のすべての試行の間の時間（秒単位）。 | N/A | **300** | **10** | **7200** | いいえ |
| connection_timeout | integer | HTTP 呼び出し操作を中止するまで待機する時間（秒単位）。 | N/A | **300** | **10** | **600** | いいえ |
| write_timeout | integer | HTTP 呼び出し操作の書き込みタイムアウト時間（秒単位）。 | N/A | **300** | **10** | **600** | いいえ |
| read_timeout | integer | HTTP 呼び出し操作の読み取りタイムアウト時間（秒単位）。 | N/A | **300** | **10** | **600** | いいえ |