# Amazon Ads Export Integration

Amazon Adsは、ユーザーがAmazonのプラットフォーム上で製品やサービスを宣伝できる広告サービスです。

Amazon Ads Export integrationは、TDユーザーがAmazon Marketing Cloud (AMC)やAmazon Demand-Side Platform (DSP)などのAmazon Adsプラットフォーム上でオーディエンスとオーディエンスレコードを管理する際にサポートします。

## 前提条件

- Treasure Dataの基本的な知識
- Amazon AdプラットフォームAMCとDSPの基本的な知識


## 要件と制限事項

- Amazon Ads APIで使用されるAudience IDは、DSP Advertiserアカウントの下に表示されるAudience IDではありません。APIに必要なAudience IDは、新しいオーディエンスが作成されたときに表示され、安全な場所に保存する必要があります。


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

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

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

## Treasure コンソールを使用して接続を作成

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

### 新しいAuthenticationを作成

最初のステップは、認証情報のセットを使用して新しい認証を作成することです。

1. **Integrations Hub**を選択します。
2. **Catalog**を選択します。


![](/assets/integrationshub-catalog.c3be7f1ed3fba588b329d4c18138b8ab489a1adfb1441a6e5779c57feae8bb40.0cef941b.png)
3. Catalogで**Amazon Ads**を検索し、アイコンの上にマウスを置いて**Create Authentication**を選択します。

![](/assets/createauthen1.e22585a39d6a88c1e591fcbb07090ef6d4b188267a226d6efc11281d008a5abb.0cef941b.png)![](/assets/createauthen2.960db12d5f838980d3555d9d15b3e5d2d37872b6ceb5a984cf077a6c94c02831.0cef941b.png)

New Authenticationモーダルが表示されます。
4. OAuth接続フィールドの下にある**Click here**リンクを選択します。
5. AmazonアカウントにログインしてOAuthアクセスを承認します。
6. New Authenticationモーダルで、この情報を入力し、**Continue**を選択します。
7. 認証の名前を入力し、**Done**を選択します。

### Authentication IDの取得

この認証をTreasure APIやTD Toolbeltで使用したい場合は、Authentication IDを取得する必要があります。
Authentication IDを取得するには:

1. **Integrations Hub > Authentications**に移動します。
2. 使用したいインテグレーションを選択します。Edit Authenticationモーダルが表示されます。
3. ブラウザのアドレスバーで、URLの最後にあるAuthentication IDを確認します。この例では、IDは**2881**です。


![](/assets/authenid2.c86c15ecfac8e4ea43ba61de1deaf63a0d30db8e2463ccd3d2f20de70c5c4414.0cef941b.png)

## クエリの定義

1. **Data Workbench > Queries**に移動します。
![](/assets/dataworkbench-queries.c143f98f66aff75a445c5e2d1a74cffe0f989c4f78d4f0763a344c3006b91fe2.0cef941b.png)
2. **New Query**を選択します。
3. テーブルのドロップダウンメニューから、クエリを実行するデータベースを選択します。
4. クエリを入力します。


サンプルクエリは次のとおりです:


```SQL
SELECT
  usr_firstname  AS firstname,
  usr_address    AS address,
  usr_phone      AS phone,
  usr_city       AS city,
  usr_state      AS state,
  usr_postalcode AS postal,
  usr_email      AS email,          -- required
  usr_lastname   AS lastname,
  usr_country    AS countrycode,
  ext_id         AS externaluserid  -- required
FROM
  mytable
```

クエリに必要なフィールドは次のとおりです:

| Field | Required | Hash Required |
|  --- | --- | --- |
| firstname |  | Yes |
| address |  | Yes |
| phone |  | Yes |
| city |  | Yes |
| state |  | Yes |
| postal |  | Yes |
| email | Yes | Yes |
| lastname |  | Yes |
| countrycode |  |  |
| externalUserId | Yes |  |


## Result Exportターゲットの指定

Amazon Adsにデータをエクスポートする方法は2つあります:

- 新しいオーディエンスを作成
- 既存のオーディエンスを更新


## 新しいオーディエンスを作成してハッシュ化されたレコードをエクスポート

これは、AMCとDSPでオーディエンスを作成し、そのオーディエンスにユーザーを追加する方法の例です。

1. Treasure コンソールを使用して、上記の「クエリの定義」セクションのステップ1〜4を実行します。
2. **Export Results**を選択します。
3. Amazon Ads用に作成したインテグレーションを選択します。


Export Resultsモーダルが表示されます。

![](/assets/create.710a645967029d959ea8ec4ff78b47e34813b4d2289ced92e48c8be5ed83b77a.0cef941b.png)
4. Actionフィールドで、**Create**が選択されていることを確認します。
5. 残りのフィールドに情報を入力します。

| Field | Description | Note |
|  --- | --- | --- |
| Audience Fee | 通貨とインプレッション単価 (CPM)。必須。形式:    currrency:cpm in cents    例: USD:1 | 通貨は広告主のマーケットプレイスと一致させる必要があります。 |
| Time to live | オーディエンスの有効期間を秒単位で指定します。必須。 | 値は0より大きく、`34300800`未満である必要があります。デフォルト: 34300800 |
| Country code | オーディエンスデータが収集された国コードを指定します。必須。 | ISO 3166-2 [country codes](https://en.wikipedia.org/wiki/ISO_3166-2)の完全なリストを参照してください。 |
| Wait for next status | 「Wait for upload next status」チェックボックスを選択し、「Max waiting time」フィールドで、ジョブがAmazonサービスがアップロードステータスを通知するのを待つ時間を分単位で指定します。オプション。 |  |


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


**結果の例**


```
************* REPORT *************2024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): Total records: 382024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): Total batches: 12024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): Total skipped records: 02024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): ************* UPLOAD STATUS
*************2024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): Total completed batches: 1/12024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): Total uploaded records but invalid: 02024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): ************* AUDIENCE INFO *************
2024-05-29 04:40:12.080 +0000 [INFO] (0035:task-0000): Audience ID: 361054992504331xxx2024-05-29 04:40:12.081 +0000 [INFO] (0001:transaction): {done:  1 / 1, running: 0}2024-05-29 04:40:12.082 +0000 [INFO] (0001:transaction): Incremental job, setting last_path to [job_2167618832_result]2024-05-29 04:40:12.280 +0000 [INFO] (pool-10-thread-1): Saving all buffers2024-05-29 04:40:12.280 +0000 [INFO] (pool-10-thread-1): Closing buffers2024-05-29 04:40:14.281 +0000 [INFO] (main): Stopped sending metrics
```

AudienceIDはオーディエンス作成プロセス中にのみ返されるため、後で使用するためにIDを安全に保存する必要があります。Audience IDはジョブログの最後に見つけることができます。

ヒント: オーディエンスが「**AMC and DSP**」の下に作成され、そのオーディエンスに新しいレコードを継続的にアップロードしたい場合。このユースケースでは、ジョブを繰り返し実行するようにスケジュールできます。変更は不要です。それ以外の場合は、次のユースケースに従ってください。 |

## 既存のオーディエンスを更新

これは、AMCとDSPでオーディエンスを更新する方法の例です。

新しいクエリを作成するよりも、クエリをクローンして既存の設定に変更を加える方が簡単です。

1. Treasure コンソールを使用して、上記の「クエリの定義」セクションのステップ1〜4を実行します。
2. **Export Results**を選択します。
3. Amazon Ads用に作成したインテグレーションを選択します。


Export Resultsモーダルが表示されます。

![](/assets/update.8352111396d8e9179442cb3b690a622c87e1295e34af582d76f35ac5c2511cc2.0cef941b.png)
4. Actionフィールドで、**Update**が選択されていることを確認します。
5. 残りのフィールドに情報を入力します。

| Field | Description | Note |
|  --- | --- | --- |
| Upload Mode | 次のいずれかを選択:  - **Append**—既存のオーディエンスに新しいレコードを追加します。 - **Delete**—既存のオーディエンスの一致するレコードを削除します。 | 削除プロセスはAmazonによって処理されます。 |
| Target | ユーザーは次の中から選択できます: - **AMC**—AMCで作成されたオーディエンス、クエリレコードがAMCにアップロードされます。 - **AMC and DSP**— レコードがAMCにアップロードされ、その後DSPに同期されます。 |  |
| DSP Advertiser ID | ターゲットがDSP関連の場合に必須。 |  |
| Audience ID | 更新するオーディエンスを指定します。アクションがUpdateの場合に必須。 | これは、オーディエンスが作成されたときに返されたIDです。 |
| Audience Description | オーディエンスの説明を指定します。必須。 |  |
| Audience Fee | 通貨とインプレッション単価 (CPM)。必須。形式:    currrency:cpm in cents    例: USD:1 | 通貨は広告主のマーケットプレイスと一致させる必要があります。 |
| Time to live | オーディエンスの有効期間を秒単位で指定します。必須。 | 値は0より大きく、`34300800`未満である必要があります。   デフォルト: 34300800 |
| Country code | オーディエンスデータが収集された国コードを指定します。必須。 | ISO 3166-2 [country codes](https://en.wikipedia.org/wiki/ISO_3166-2)の完全なリストを参照してください。 |
| Wait for next status | 「Wait for upload next status」チェックボックスを選択し、「Max waiting time」フィールドで、ジョブがAmazonサービスがアップロードステータスを通知するのを待つ時間を分単位で指定します。オプション。 |  |


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


## 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) を参照してください。

### (オプション) 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 を有効にすることで、クエリの開始時刻を遅延させることができます。


### クエリを実行する

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

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

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

## (オプション) Workflowでエクスポート結果を設定

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


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

+amazon_ads_export_task:
  td>: export_amazon_ads.sql
  database: ${td.database}
  result_connection: new_amazon_ads_auth
  result_settings:
    type: amazon_ads
    td_authentication_id: td_authentication_id
    amc_instance_id: amc_instance_id
    amc_account_id: amc_account_id
    dsp_region: NA
    action: CREATE
    upload_mode: APPEND
    target: AMC_AND_DSP
    dsp_advertiser_id: dsp_advertiser_id
    external_audience_id: external_audience_id
    audience_name: audience_name
    time_to_live: 34300800
    country_code: US
    wait_until_finish: true
    max_wait_time: 5
```

## (オプション) CLIを使用したExport Integration

[TD Toolbelt](/tools/cli-and-sdks/quickstart)を使用して、--resultオプション付きのtd queryコマンドを使ってAmazon Adsに結果をエクスポートすることもできます。詳細については、[TD Query](/tools/cli-and-sdks/api#td-query)を参照してください。

--resultオプションで指定されるデータはJSON形式で、一般的な構造は次のとおりです。


```json
{
  "type": "amazon_ads",
  "td_authentication_id": ${authentication_id_from_td_console},
  "amc_instance_id": "amc_instance_id",
  "amc_account_id": "amc_account_id",
  "region": "NA",
  "action": "CREATE",
  "upload_mode": "APPEND",
  "target": "AMC_AND_DSP",
  "dsp_advertiser_id": "dsp_advertiser_id",
  "external_audience_id": "external_audience_id",
  "audience_name": "audience_name",
  "time_to_live": 34300800,
  "country_code": "US",
  "wait_until_finish": false,
  "max_wait_time": 1
}
```

### パラメータ

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| type | エクスポートの宛先。 | "amazon_ads" |  | Yes |
| td_authentication_id | Treasure コンソールのAmazon Ads認証のAuthentication ID。このIDの値を決定する方法については、[Getting the Authentication ID](/ja/int/amazon-ads-export-integration#h4_66958132)を参照してください。 |  |  | Yes |
| amc_instance_id | Amazon Marketing Cloud Instance ID |  |  | Yes |
| amc_account_id | AMC Account ID。このフィールドを空白のままにすると、インテグレーションが自動的に取得します。 |  |  | No |
| region | DSP Advertiserアカウントに対応するリージョン。 | enums ["NA", "EU", "FE"] | "NA" | Yes |
| action | 実行するアクション:  - Create - Update | enums ["CREATE", "UPDATE"] | "CREATE" | Yes |
| upload_mode | 実行するアップロードモード:   - Append - Delete | enums ["APPEND", "DELETE"] | "APPEND" | Yes |
| target | オーディエンスターゲット:   AMC AMC and DSP | enums ["AMC", "AMC_AND_DSP"] | "AMC" | Yes |
| dsp_advertiser_id | DSP Advertiser ID |  |  | Yes - targetが"AMC_AND_DSP"の場合 |
| external_audience_id | 新しいオーディエンスのユーザー指定外部ID |  |  | Yes - actionが"CREATE"の場合 |
| audience_id | Amazon Audience ID。オーディエンスが作成されたときに返されたID。 |  |  | Yes - actionが"UPDATE"の場合 |
| audience_name | オーディエンス名 |  |  | Yes - actionが"CREATE"の場合 |
| audience_description | オーディエンスの説明 | 英数字、非nullの文字列で、長さは0〜1000文字である必要があります。 |  | No |
| audience_fee | オーディエンスメタデータの料金 | 形式: currency:cpmCents |  | No |
| time_to_live | オーディエンスメタデータの有効期間(秒単位) | 0〜34300800の範囲である必要があります |  | No |
| country_code | Country Code [ISO 3166-1 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) |  |  | Yes |
| wait_until_finish | インテグレーションがすべてのエクスポートジョブが完了するまで待機するかどうか | true または false |  | No |
| max_wait_time | インテグレーションがすべてのエクスポートジョブが完了するまで待機する時間(分単位)。 | 1〜1380(23時間)の範囲である必要があります |  | Yes, wait_until_finishがTRUEの場合 |


### 使用例

この例では、単一の手動エクスポートを実行します。


```bash
td query \
--database ${database_name} \
--wait "SELECT * FROM ${table_name}" \
--type presto \
--result '{"type":"amazon_ads","td_authentication_id":"${authentication_id_from_td_console}","amc_instance_id":"amc_instance_id","amc_account_id":"amc_account_id","region":"NA","action":"CREATE","upload_mode":"APPEND","target":"AMC_AND_DSP","dsp_advertiser_id":"dsp_advertiser_id","external_audience_id":"external_audience_id","audience_name":"audience_name","time_to_live":34300800,"country_code":"US","wait_until_finish":false,"max_wait_time":1}'
```

この例では、スケジュールされた時間に実行します。


```bash
td sched:create \
result_to_amazon_ads '0 0 * * *' \
--database ${database_name} 'SELECT * FROM ${table_name}' \
--result '{"type":"amazon_ads","td_authentication_id":"${authentication_id_from_td_console}","amc_instance_id":"amc_instance_id","amc_account_id":"amc_account_id","region":"NA","action":"CREATE","upload_mode":"APPEND","target":"AMC_AND_DSP","dsp_advertiser_id":"dsp_advertiser_id","external_audience_id":"external_audience_id","audience_name":"audience_name","time_to_live":34300800,"country_code":"US","wait_until_finish":false,"max_wait_time":1}'
```

## 外部参照

詳細については、[Amazon Advertiser Audience APIs](https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-cloud/audiences/audience-management-service)を参照してください。