# Yahoo Japan Ads エクスポートインテグレーション

Yahoo! JAPAN Adsは、シンプルな設定、さまざまなマーケティングチャネル、柔軟な拡張性により、企業のマーケティング活動をサポートします。Yahoo! JAPAN独自のさまざまな広告配信面により、戦略的なマーケティングコミュニケーションが可能です。

このインテグレーションにより、Treasure Dataは、企業のWebサイトやYahoo! Japanに関連する基幹システムからのファーストパーティデータのカスタマイズリストを使用して、Yahoo! JAPAN Adsで広告キャンペーンを作成できるようにすることで、ユーザーセグメントをYahoo! JAPAN Adsに送信するのを支援します。

Treasure Dataエクスポートでは、次のことが可能です。

- **Direct Targeting**: 分析を使用してTreasureData上でユーザーセグメントを作成します。次に、それをYahoo! JAPAN Adsに送信し、Yahoo! JAPAN Ads上でCustomListとしてターゲティングキャンペーンを設定します。
- **Custom Segment Targeting**: ユーザーデータをその属性とともに送信して、Yahoo! JAPAN Adsでカスタムセグメントを分析・作成します。次に、Yahoo! JAPAN Ads上でCustomListとしてターゲティングキャンペーンを設定します。


2022年12月に、オーディエンスリスト（カスタム）は新しいオーディエンスリストに移行されました。Treasure Dataと連携する新しいリストを作成するには、オーディエンスリスト（顧客データ）を使用してください。詳細については[こちら](https://ads-promo.yahoo.co.jp/support/release/30368839.md)をご覧ください。

図は、Direct TargetingとCustom Segment Targetingのフローを示しています。td_global_id

## 前提条件

- Treasure Dataアカウント
- Yahoo! JAPAN Adsアカウント


## 制限事項

- コネクタは、圧縮されたレコードの1GBのアップロードのみをサポートします。
- インテグレーションは、ファイルをYahoo! JAPANにアップロードします。Yahoo! JAPANでのインポートおよびマッチング中に失敗する可能性があります。したがって、お客様はYahoo! JAPAN Adsコンソールで有効なパラメータを確認する必要があります。


## ユーザーの特定について

Treasure Dataでは、ユーザーを特定するために以下の方法があります。

| 方法 | 説明 | 備考 |
|  --- | --- | --- |
| td_global_id | Treasure Dataが提供するサードパーティCookie。2023年1月からYahoo! JapanのWebサイトでtd_global_idが同期されなくなったため、CookieSyncを実装せずにユーザーを特定できます。 | 推奨されなくなりました |
| hashed_email | Cookieなしでユーザーを特定できます。Yahoo! JAPAN Adsに送信されたハッシュ化されたメールは、Yahoo! JAPAN Ads上の同じハッシュ化されたメールとマッチングすることで、ユーザーリストを作成します。 |  |
| IDFA/ADID | Cookieを使用する代わりに、iOS上のIDFA（Identifier for Advertisers）またはAndroid上のADID（AdvertisingId）を使用してユーザーを特定できます。 | 推奨されなくなりました。 |


## Yahoo! JAPAN Adsへのエクスポート

### Yahoo! JAPAN Adsでオーディエンスリストを作成する

1. [Yahoo! Business Center](https://business.yahoo.co.jp/)にログインし、Display Adsタブのドロップダウンリストから「ツール」を選択し、ターゲットリストページを開きます。Yahoo! Ads Campaign Management Toolのレイアウトのナビゲーションに問題がある場合は、Yahoo! Japanサポートチームにお問い合わせください。
![](/assets/image-20200529-231627.02a5496a7e65c17ee2384a6e4ad581e15b41ca6bf202e9653af00fbdca6f19c7.658a5540.png)
2. ターゲットリストを追加のドロップダウンリストを選択し、カスタムリストを作成オプションを選択します。
![](/assets/image-20200529-231704.4d5e20d0c0e8def12e3625b11293cfafa86233cae801f749b05fd926997fb5db.658a5540.png)
3. Custom Audience ID / Target List IDを確認します。
![](/assets/image2022-9-8_6-10-1.9f6aa51908128f42deea95e02feb26f23be9040951dfde2c3784ce8722fd45fb.658a5540.png)
4. Audience List-ID列が表示されていない場合は、表示タブを選択し、Target List IDチェックボックスを選択します。
![](/assets/image-20200529-231928.1d37e2aee3c738525b9fdd326a4eb9fb58fd713c5f0ff0daa7943dcd47f1f517.658a5540.png)


## Treasureインテグレーション用のYahoo! JAPAN AdsでBrand IDを取得する

Treasure Dataカスタマーサクセス担当者にお問い合わせください。

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

### 新しい接続を作成する

Treasure Dataでは、クエリを実行する前に、エクスポート用のデータ接続を作成および設定する必要があります。データ接続の一部として、インテグレーションにアクセスするための認証を提供します。

1. **TD Console**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. **Yahoo! JAPAN Ads**を検索して選択します。
4. 次のダイアログが開きます。
![](/assets/screen-shot-2021-04-08-at-14.36.27.bcdec2bc7eb8e63e42e2ca529f7af3ab49ff70ecab26257f5643789c7242d8d6.658a5540.png)
5. Brand IDを入力します。
6. 接続の名前を入力します。
7. **Done**を選択します。


### クエリを定義する

### Yahoo! JAPAN Ads（Direct Targeting）のインテグレーションパラメータ

以下のパラメータを設定します。

| パラメータ | 説明 |
|  --- | --- |
| `user_list_type`（必須） | ユーザーリストタイプ：- `direct_targeting`
- `custom_segment_targeting`

 |
| `user_id_type`（必須） | ユーザーIDタイプ：- cookie
- email: 最初の列、uidは、メールまたはハッシュ化されたメールSHA256です
  - ハッシュ化の結果が大文字の場合は、小文字に変換してください
- IDFA: 最初の列、uidは、UUIDです
- AAID: 最初の列、uidは、UUIDです

 |
| `ignore_invalid_records`（オプション） | 無効なレコードを無視します。 |
| `custom_audience_id`（オプション） | `user_list_type`が`direct_targeting`の場合、カスタムオーディエンスID（サイトリターゲティングID）が必要です。IDを取得するには、こちらを参照してください。 |
| account_id（オプション） | `user_list_type`が`direct_targeting`の場合、アカウントIDが必要です |
| `target_list_id`（オプション） | `user_list_type`が`direct_targeting`の場合、オーディエンスリストIDが必要です。 |


以下はサンプル設定です。


```
  type: yahoo_dmp
  brand_id: brand_id
  user_list_type: direct_targeting
  user_id_type: hashed_email
  custom_audience_id: custom_audience_id
  account_id: account_id
  target_list_id: target_list_id
  ignore_invalid_records: false
```

### Yahoo! JAPAN Ads（Segment Targeting）のインテグレーションパラメータ

以下のパラメータを設定します。

| パラメータ | 説明 |
|  --- | --- |
| `user_list_type`（必須） | ユーザーリストタイプ：- `direct_targeting`
- `custom_segment_targeting`

 |
| `user_id_type`（必須） | ユーザーIDタイプ：- cookie
- hashed_email: 最初の列、uidは、メールまたはハッシュ化されたメールSHA256です
  - 列の内容がハッシュ化されていない場合は、自動的にハッシュ化されます
  - ハッシュ化の結果が大文字の場合は、小文字に変換してください
- IDFA: 最初の列、uidは、UUIDです
- AAID: 最初の列、uidは、UUIDです

 |
| `ignore_invalid_records`（オプション） | 無効なレコードを無視します。 |
| `client_id`（オプション） | `user_list_type`が`custom_segment_targeting`の場合、クライアントIDが必要です |
| `data_source_number`（オプション） | `user_list_type`が`custom_segment_targeting`の場合、データソース番号が必要です |


以下はサンプル設定です。


```
  type: yahoo_dmp
  brand_id: brand_id
  user_list_type: custom_segment_targeting
  user_id_type: hashed_email
  client_id: client_id
  data_source_number: data_source_number
  ignore_invalid_records: false
```

Yahoo! JAPAN Adsのクエリ例

`direct_targeting`の場合、Treasure Dataは文字列または数値形式の1つの列をサポートします。例えば：


```sql
SELECT 'my@email.com' as uid;
```

`custom_segment_targeting`の場合、最初の列は`UID`で、文字列または数値形式です。


```sql
SELECT 'my@email.com' as uid,
       '012345' as sms,
       '123' as sid,
       'My Name' as name,
       'Mar 11' as dob;
```

または、属性を持つユーザーデータを抽出し、Yahoo! JAPAN Adsでカスタムセグメントを分析・作成するためのSQLクエリを記述します。ユーザーIDは最初の列である必要があります。たとえば、属性を持つtd_global_idを削除します。


```sql
SELECT
   td_global_id AS td_global_id,
   MAX(td_os) AS type,
   COUNT(td_global_id) AS price
FROM
   demo_pageviews
GROUP BY
   td_global_id
```

または、生のメールについては、Yahoo! JAPAN Adsに送信する前に、そのまま送信するか、SQLでハッシュ化することができます。

データは、Yahoo! JAPAN Adsに送信される際にgzipで圧縮されます。圧縮されたデータが1GBを超える場合は、送信前に分割する必要があります。


```sql
SELECT
  LOWER(TO_HEX(SHA256(TO_UTF8(email))))
FROM
  demo_email
```

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

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

Treasure Workflow内でこのデータコネクタを使用してデータをエクスポートするよう指定できます。

詳細については、[パラメータを使用したデータのエクスポート](https://docs.treasuredata.com/smart/project-product-documentation/exporting-data-with-parameters)をご覧ください。

### Yahoo! JAPAN Adsに送信するユーザーリストを抽出する

1. お好みのテキストエディタまたはTreasure Data Workflowエディタを使用して、Yahoo! JAPAN Adsワークフローファイルを開きます。
2. Yahoo! JAPAN Adsに送信したいユーザーリストを抽出するSQLクエリを記述します。[ファイルの作成と削除](https://docs.treasuredata.com/smart/project-product-documentation/creating-and-deleting-files)を参照してください。


### ワークフローを実行してユーザーリストをYahoo! JAPAN Adsに送信する

Yahoo! JAPAN Adsの新しいカスタムターゲットリストを作成したばかりの場合は、最新のリストが処理されるまでに時間がかかる可能性があるため、ワークフローを実行する前に約1時間待ってください。

1. **TD Console**を開きます。
2. **Data Workbench** > **Workflows**に移動します。
3. Yahoo! JAPAN Adsワークフローをハイライトします。
4. **New Run**ボタンを選択するか、[ワークフローを繰り返し実行するスケジュール](https://docs.treasuredata.com/articles/project-product-documentation/scheduling+a+Workflow+from+within+the+Workflow+Definition)を定義します。
5. ワークフローの結果を確認して、正常に実行されたことを確認します。
6. ワークフローの処理後（通常は3〜4時間かかります）、`Reach`の数値が正しいことを検証します。


![](/assets/image-20200529-232807.6a9ea04ecf46008b45a64a6a6844b1fbe131f229dd96f3febc63f81bd8b39ebc.658a5540.png)

### Yahoo! JAPAN Adsで処理ステータスを検証する

3〜4時間の処理期間後もReach数値がゼロのままで更新されない場合は、Yahoo! JAPAN Adsで処理ステータスを確認してそのステータスを検証できます。

1. Yahoo! JAPAN Ads APIへのエクスポートのワークフローログで`GUID`値を検証します。
![](/assets/image-20200529-232933.71c0d2b17ff95c79c089e8e42ca24abc34033a9f75ff0607aa808a0fd090a231.658a5540.png)
2. Yahoo! JAPAN Ads APIのHTTP GET照会を使用します。例えば：



```bash
$ curl --location \
--request GET 'https://api.tgm.yahoo-net.jp/v3/userlists/guid_value' \ --header 'x-api-key: x-api-key'
```


```json
{
  "guid": "guid_value",
  "brandGuid": "brandguid_value",
  "vendorGuid": "vendorGuid_value",
  "entityId": "entityId_value",
  "uidKey": "uidKey_value",
  "tagDefinitionGuid": "yahoo_japan_ydn_custom_audience_server",
  "tagFields": {
    "p": "p_value",
    "lid": "lid_value"
  },
  "status": "CREATED"
}
```

1. 空の値を関連する情報に置き換えます。


| **フィールド** | **説明** |
|  --- | --- |
| `guid_value` | ワークフローからのGUID |
| `x-api-key` | ワークフローシークレットの設定に使用したx-API-key文字列。（APIキーについてはTDにお問い合わせください） |
| `brandguid_value` |  |
| `vendorGuid_value` |  |
| `entityId_value` |  |
| `uidKey_value` |  |
| `p_value` |  |
| `lid_value` |  |


HTTP結果として`"status":"ACTIVATED"`を受け取った場合、プロセスはYahoo! JAPAN Adsで正常に完了しています。ステータスが"CREATED"、"UPLOADED"、または"PROCESSING"の場合、Yahoo! JAPAN Adsでのプロセスはまだ完了していません。