# 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 アドレスの完全なリストは、次のリンクにあります: [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では、クエリを実行する前にデータ接続を作成して設定する必要があります。データ接続の一部として、インテグレーションにアクセスするための認証を提供します。 ### 新しい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の取得 この認証をTD 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. TD Consoleを使用して、上記の「クエリの定義」セクションのステップ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. TD Consoleを使用して、上記の「クエリの定義」セクションのステップ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) に実行することを要求するためです。後者の仕様が優先されます。 #### 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 を有効にすることで、クエリの開始時刻を遅延させることができます。 ## (オプション) Workflowでエクスポート結果を設定 Treasure Workflow内で、このインテグレーションを使用してデータをエクスポートするように指定できます。 ```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](https://api-docs.treasuredata.com/en/tools/cli/quickstart/)を使用して、--resultオプション付きのtd queryコマンドを使ってAmazon Adsに結果をエクスポートすることもできます。詳細については、[TD Query](https://api-docs.treasuredata.com/en/tools/cli/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 | TD Consoleの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)を参照してください。