# Yahoo Audience Discovery Export Integration

Yahoo! JAPANは、2024年6月30日にYahoo! JAPAN Ads Export Integrationで使用されているAPIエンドポイントを廃止します。当該連携のCustom Segment Targeting機能を使用しているすべてのジョブは、その日までにこの連携に移行する必要があります。

Yahoo! JAPAN Audience Discovery（YAD）は、Yahoo! JAPANのデータと企業のデータを組み合わせて独自のユーザーセグメントを作成し、広告の追加とターゲット配信を可能にする包括的なサービスです。

このExport Integrationは、ユーザーのメールアドレスやIDFA/AAIDなどのユーザーIDと、提供された任意のユーザー属性を、YADに直接アップロードすることを可能にします。そこから、Yahoo! JAPAN AdsのDisplay ads配信にリンクして使用できます。

## 前提条件

- Treasure Data™の基礎知識
- [YAD](https://ads-help.yahoo-net.jp/s/article/H000045962)トピックの基礎知識
- Yahoo! JAPANが発行した有効なBrand IDとData Source ID。詳細については、Treasure Data Customer Successの担当者にお問い合わせください。


## 制限と制約

- Brand IDとData Source IDの発行には最大5営業日かかる場合があります
- ユーザーIDに加えて、APIは最大79個の追加のユーザー属性のアップロードをサポートします
- アップロードがYADで処理されるまで最大24時間かかる場合があります


## TD Consoleを使用する

### 新しいコネクションを作成する

TD Consoleでは、クエリを実行する前にデータコネクションを作成して設定する必要があります。データコネクションの一部として、以下の手順に従って連携にアクセスするための認証を提供します。

1. **TD Console**を開きます。
2. **Integration Hub > Catalog**に移動します。
3. **Yahoo! Audience Discovery**を検索して選択します。
4. **Create Authentication**を選択し、以下の説明に従って連携の認証情報を入力します。
5. **Continue**を選択し、Authenticationの名前を入力して、**Done**を選択します。


### 認証フィールド

| **フィールド** | **説明** |
|  --- | --- |
| **Brand ID** | Yahoo! JAPANが発行したBrand ID。Treasure Data Customer Successの担当者にお問い合わせください |


### クエリ結果のエクスポートを設定する

TD Consoleはデータをエクスポートする複数の方法をサポートしています。Data Workbenchからデータをエクスポートするには、以下の手順に従ってください。

1. **Data Workbench > Queries**に移動します。
2. **New Query**を選択し、クエリを定義します。
3. **Export Results**を選択してデータのエクスポートを設定します。


![](/assets/screenshot-2024-05-27-at-13.08.60.c660e2874c5efd5898076c87205c9c1c3579e1232c32206db66443388b0163ee.9c1a955f.png)

1. 既存のAuthenticationを選択するか、上記のセクションに従って新しいものを作成します。
2. 以下の[設定パラメータ](/ja/int/yahoo-audience-discovery-export-integration#h2_2111705584)の説明に従ってエクスポートパラメータを設定し、**Done**を選択します。


### クエリを定義する

クエリの最初のカラムには、選択した**User ID Type**と一致するユーザーIDを含める必要があります。他のカラムは追加のユーザー属性としてアップロードされます。連携の予期しない動作を引き起こす可能性があるため、ワイルドカードクエリは使用しないでください。

**データ要件:**

- 改行と制御文字: データはTSVファイル形式でアップロードされるため、データ値にはTSVファイルを破損する可能性のある改行や制御文字を含めないでください。


| **カラム** | **説明** | **必須 / オプション** |
|  --- | --- | --- |
| 最初のカラム | 選択した**User ID Type**と一致するユーザーID。任意のカラム名が使用できます | 必須 |
| 2番目以降のカラム | 追加のユーザー属性。カラム名、またはエイリアスは、そのままYADに送信されます | オプション |


**クエリ例:**

生のメールアドレスの場合、そのまま送信するか、エクスポート前にSQLでハッシュ化することができます。


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

利用可能な場合、2番目以降のカラムの値は、以下の例の`type`と`price`のように、追加の属性としてYADにアップロードされます。


```sql
SELECT
  'my@email.com' as uid,
  '012345' as type,
  '2000' as price
```

### 設定パラメータ

| フィールド | 説明 |
|  --- | --- |
| User ID Type | ユーザーIDのタイプ。以下のいずれかを選択します:- Email address
- IDFA
- AAID

 |
| Data Source ID | Yahoo! JAPANが発行したData Source ID |


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

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

TD Toolbeltは、CLIからクエリ結果のエクスポートをトリガーできます。エクスポートジョブのパラメータを`td query`コマンドの`--result`オプションとして指定する必要があります。詳細については、[こちらの記事](https://docs.treasuredata.com/articles/pd/querying-and-importing-data-to-treasure-data-from-the-command-line)を参照してください。

このオプションの形式はJSONで、一般的な構造は以下の通りです。


```
{  "type": "yahoo_audience_discovery",  "user_id_type": "MAIL_ADDRESS",  "brand_id": "1234",  "data_source_id": "56789",  "ignore_invalid_records": true}
```

### CLIパラメータ

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | エクスポート先のサービス名を記述します。 | yahoo_audience_discovery | N/A | はい |
| user_id_type | エクスポートするユーザーIDタイプ。 | サポートされる値:   - MAIL_ADDRESS - IDFA - AAID | MAIL_ADDRESS | はい |
| brand_id | Yahoo brand id。 | Yahoo brand id | N/A | はい |
| data_source_id | Yahoo data source id。 | Yahoo data source id | N/A | はい |
| ignore_invalid_records | trueに設定すると無効なレコードをスキップしてジョブを継続し、それ以外の場合はジョブを停止します。 | trueに設定すると無効なレコードをスキップしてジョブを継続し、それ以外の場合はジョブを停止します。 | false | いいえ |


### 使用例


```
$ td query --result '{"type": "yahoo_audience-discovery", "user_id_type": "MAIL_ADDRESS","brand_id": "1234", "data_source_id": "56789", "ignore_invalid_records": true}' -d sample_datasets "select * from sample_table" -T presto
```

# 

## その他

- [Scheduled Job](https://docs.treasuredata.com/articles/pd/scheduling-jobs-using-td-console)をResult Exportと併用して、ターゲット先に定期的にデータをアップロードすることができます
- より高度なデータパイプラインの一部として、[TD workflow](/ja/int/using-td-workflow-with-td-integrations)でこの連携を使用することができます


#