# Amazon Ads Import Integration DSP Report このインテグレーションにより、Amazon Adsレポートの設定が可能になり、これらのレポートのコンテンツをTreasure Dataに直接取り込むことができます。 ## 前提条件 - Treasure Dataの基本的な知識 - Amazon Adsの基本的な知識 ## 要件と制限事項 - Amazon Adsのレポートメトリクスとデータは、Amazon Adsによって制御されています。 - このインテグレーションは、Amazon Adsで既に設定されているレポートをトリガーするだけです。 ## Treasure DataのStatic IPアドレス Treasure DataのStatic IPアドレスは、このインテグレーションのアクセスポイントであり、リンケージのソースです。Static IPアドレスを確認するには、Customer Successの担当者またはテクニカルサポートにお問い合わせください。 ## TD Console経由でAmazon Adsレポートをインポート ### Authenticationの作成 最初のステップは、認証情報のセットを使用して新しい認証を作成することです。 1. **Integrations Hub**を選択します。 2. **Catalog**を選択します。 ![](/assets/integrationshub-catalog2.e33c0a4c7d81c40cc83dd056c2143b97b1406220e213cab14ef349d69412ffef.eedebb45.png) 3. CatalogでAmazon Adsを検索し、アイコンの上にマウスを置いて**Create Authentication**を選択します。 ![](/assets/amazonadsreports.47e35c37addff2c44770ce8d6cba7ff45bff6e86a1aca99db90913b4d340c61e.eedebb45.png) 4. **Credentials**タブが選択されていることを確認し、インテグレーションのOAuth接続認証情報を入力します。 5. **Continue**を選択します。 6. 認証の名前を入力し、**Done**を選択します。 ### Sourceの作成 認証がコンソールで使用可能になったら、インポートジョブを設定します。 1. TD Consoleを開きます。 2. **Integrations** **Hub > Authentications**に移動します。 3. Amazon Ads認証を見つけて、**New Source**を選択します。 #### Connection Details | Parameter | Description | | --- | --- | | Data Transfer Name | 転送の名前を入力します。 | | Authentication | 転送に使用される認証の名前。 | #### Source Table | Parameter | Description | | --- | --- | | Data Type | DSP Reportを選択します。 将来的には追加のタイプが利用可能になる場合があります。 | | Profile Marketplace | 広告主マーケットプレイスの2文字の国コードを入力します。 | | Advertiser ID(s) | データをリクエストする広告主のAdvertiser IDをカンマ区切りで入力します。少なくとも1つのIDを指定する必要があります。 | | Report Type | ドロップダウンメニューからReport Typeを選択します。レポートタイプの説明については、[Amazon Ads Report Types](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/overview)を参照してください。 | | Group By | レポートをグループ化するディメンションをカンマ区切りで入力します。少なくとも1つのディメンションを指定する必要があります。 現在サポートされているディメンションは次のとおりです:- [campaign](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#group-by-campaign-5) - [ad](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#group-by-ad) - [creative](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#group-by-creative) | | Report Period | 事前定義されたReport Periodを選択するか、**Custom**を選択してレポートの開始日と終了日を入力します。開始日は90日より古くすることはできず、終了日は開始日から31日を超えることはできません。レポート期間の制限については、Amazon Adsの[Campaign Reports Configurations Table](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#configurations)のAmazon DSP列を参照してください。 | | Time Unit | Report Typeに応じて、**Daily**または**Summary**を選択します。 Dailyオプションは、レポートタイプCampaignを選択した場合にのみ使用できます。 | | Base Metric | 選択したレポートタイプのすべてのベースメトリクスを含めるには、チェックボックスをオンにします。 ベースメトリクスのリストは、Amazon Adsによって変更される可能性があります。TDはリストを最新の状態に保つよう努めていますが、TDは最新のメトリクスセットが含まれることを保証できません。ベースメトリクスでエラーが発生した場合は、Custom Metricsを使用してください。 | | Custom Metrics | [Amazon](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5)から直接コピーできるカンマ区切りの値のリスト。Amazonが新しいメトリクスを公開した場合、ソフトウェアの更新を行わずにここでそれらのメトリクスを指定できます。詳細については、Amazon DSP [Base Metrics](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5)を参照してください。 このフィールドは、すべてのベースメトリクスが必要ない場合で、特定のメトリクスのみを指定したい場合にも使用できます。 | 1. **Next**を選択します。 ![](/assets/screen-shot-2024-08-20-at-10.14.20.2165eb1e00483ed20dcc78b9765afbb080d06671dc87f7780534e2dd85d115d1.eedebb45.png) ## Workflow経由でAmazon Adsレポートからインポート td_load>: src_idを使用して、Workflow経由でAmazon Adsレポートからデータをインポートできます。既にSourceを作成している場合は実行できます。Sourceを作成したくない場合は、.ymlファイルを使用してインポートできます。 ### SourceまたはYMLファイルの使用 #### Sourceの使用 1. **Integrations Hub > Sources**を選択します。 2. FiltersペインのIntegration Typeドロップダウンメニューから**Amazon Ads**を選択します。 3. •••アイコンを選択し、**Copy Unique ID**を選択します。 ![](/assets/26617502.09d9b84b0f1f752c7c95b0bc1c2d8e8b7302e5b91c6a3cb5f01309dadf53a604.25ec5a77.png) 1. td_load>: sourceIdを使用してWorkflowタスクを定義します ```yaml +load: td_load>: unique_id_of_your_source database: ${td.dest_db} table: ${td.dest_table} ``` 1. Workflowを実行します。 #### yml/yamlファイルの使用 1. ymlファイルを特定します。 yml/yamlファイルを作成する必要がある場合は、参考として[Create Seed Config File (seed.yml)](/ja/int/amazon-s3-import-integration-v2#AmazonS3ImportIntegrationv2-CreateSeedConfigFile(seed.yml))の手順を使用してください。 2. td_load>: <.yml file>を使用してWorkflowタスクを定義します ```yaml +load: td_load>: config/daily_load.yml database: ${td.dest_db} table: ${td.dest_table} ``` 1. Workflowを実行します。 ### サンプルWorkflowコード サンプルWorkflowコードについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/s3)を参照してください。 ### CLI (Toolbelt)経由でAmazon Adsからインポート インテグレーションを設定する前に、最新バージョンの[TD Toolbelt](https://toolbelt.treasuredata.com/)をインストールしてください。 #### Seed Configuration File (seed.yml)の作成 ```yaml in: type: "amazon_ads" td_authentication_id: data_type: "DSP_REPORT" profile_marketplace: "US" advertiser_ids: "advertiser_id_comma_separated_values" report_type: "CAMPAIGN" group_by: "campaign, ad, creative" time_unit: "SUMMARY" report_period: CUSTOM start_date: "2024-05-05" end_date: "2024-05-31" base_metrics: true out: mode: append ``` #### パラメータリファレンス | 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 | | profile_marketplace | ISO 3166-1 alpha-2形式で指定された広告主マーケットプレイスの2文字の国コード。 | | | No | | advertiser_ids | データをリクエストする広告主のAdvertiser IDをカンマ区切りにしたリスト。 | | | Yes | | report_type | 生成するレポートタイプ。 | enums ["CAMPAIGN", "INVENTORY", "AUDIENCE", "PRODUCT", "TECHNOLOGY", "GEOGRAPHY", "AUDIO_AND_VIDEO"] | CAMPAIGN | Yes | | group_by | レポートをグループ化するメトリクスのリスト。許可される値はレポートタイプによって異なります。 | | | Yes | | time_unit | レポートタイプが「CAMPAIGN」の場合に使用される時間単位。 | enums ["DAILY", "SUMMARY"] | DAILY | Yes, report_typeが「CAMPAIGN」の場合 | | time_unit_summary | レポートタイプが「CAMPAIGN」でない場合に使用されるレポート時間単位。 | enums ["SUMMARY"] SUMMARY | SUMMARY | Yes, report_typeが「CAMPAIGN」でない場合 | | report_period | レポートの時間枠。 | enums ["PREVIOUS_DAY", "PREVIOUS_7_DAYS", "CURRENT_WEEK", "PREVIOUS_WEEK", "PREVIOUS_30_DAYS", "CURRENT_MONTH", "PREVIOUS_MONTH", "CUSTOM"] | PREVIOUS DAY | Yes | | start_date | レポートの開始日。 | String. 形式: yyyy-MM-dd | | Yes, report_typeが「CUSTOM」の場合。 | | end_date | レポートの終了日。 | String. 形式: yyyy-MM-dd | | Yes, report_typeが「CUSTOM」の場合。 | | base_metrics | 各report_typeの[base metrics](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5)を含めるかどうかを指定します。 | TRUE/FALSE | TRUE | Yes | | custom_metrics | Custom metricsはカンマ区切りの値としてリストされます。[Amazon](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5)から直接コピーできます。Amazonが新しいメトリクスを公開した場合、ソフトウェアの更新を行わずにここでそれらのメトリクスを指定できます。 | | | | #### load.ymlの生成 connector:guessを使用してload.ymlファイルを生成します。このコマンドは、ソースファイルを自動的に読み取り、ファイル形式とそのフィールドおよび列を最良の推測で判断します。 ``` $ td connector:guess seed.yml -o load.yml ``` load.ymlを開いて、ファイル形式、エンコーディング、列名、タイプを含むファイル形式定義を確認できます。 #### load.ymlの例 ```yaml in: type: amazon_ads data_type: DSP_REPORT profile_marketplace: US advertiser_ids: '123123123123123' report_type: CAMPAIGN group_by: campaign, ad, creative time_unit: SUMMARY report_period: CUSTOM start_date: '2024-07-05' end_date: '2024-07-31' base_metrics: true td_authentication_id: out: {mode: append} exec: {}filters: - rules: - {rule: upper_to_lower} - pass_types: - a-z - 0-9 pass_characters: _ replace: _ rule: character_types - pass_types: - a-z pass_characters: _ prefix: _ rule: first_character_types - {rule: unique_number_suffix, max_length: 128} type: rename - from_value: {mode: upload_time} to_column: {name: time} type: add_time ``` データをプレビューするには、`td connector:preview`コマンドを使用します。 ```bash td connector:preview ``` ### Load Jobの実行 データのサイズによっては、数時間かかる場合があります。データを保存するTreasure Dataのデータベースとテーブルを必ず指定してください。 Treasure Dataのストレージは時間でパーティション分割されているため、Treasure Dataでは--time-columnオプションを指定することをお勧めします([data partitioning](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)を参照)。このオプションが指定されていない場合、データコネクタは最初のlongまたはtimestamp列をパーティション分割時間として選択します。--time-columnで指定される列のタイプは、longまたはtimestampタイプのいずれかである必要があります。 データに時間列がない場合は、*add_time*フィルタオプションを使用して時間列を追加できます。詳細については、[add_time Filter Function](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function)のドキュメントを参照してください。 ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table \--time-column created_at ``` connector:issueコマンドは、データベース(td_sample_db)とテーブル(td_sample_table)を既に作成していることを前提としています。TDにデータベースまたはテーブルが存在しない場合、このコマンドは失敗します。データベースとテーブルを手動で作成するか、td connector:issueコマンドで--auto-create-tableオプションを使用してデータベースとテーブルを自動作成してください。 ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table--time-column created_at --auto-create-table ``` データコネクタはサーバー側でレコードをソートしません。時間ベースのパーティション分割を効果的に使用するには、事前にファイル内のレコードをソートしてください。 timeというフィールドがある場合は、--time-columnオプションを指定する必要はありません。 ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table ``` ### Import Modes load.ymlファイルのout:セクションでファイルインポートモードを指定します。out:セクションは、データがTreasure Dataテーブルにどのようにインポートされるかを制御します。たとえば、既存のテーブルにデータを追加するか、データを置き換えるかを選択できます。 | **Mode** | **Description** | **Examples** | | --- | --- | --- | | Append | レコードがターゲットテーブルに追加されます。 | in: ... out: mode: append | | Always Replace | ターゲットテーブル内のデータを置き換えます。 ターゲットテーブルに加えられた手動スキーマ変更はそのまま残ります。 | in: ... out: mode: replace | | Replace on new data | インポートする新しいデータがある場合にのみ、ターゲットテーブル内のデータを置き換えます。 | in: ... out: mode: replace_on_new_data | ## 関連項目 Amazon Ads Report V3の詳細については、次のAmazonドキュメントを参照してください: - [Amazon Ads Report Types](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/overview) - [Amazon Ads API Reference Creating a Report Request](https://advertising.amazon.com/API/docs/en-us/offline-report-prod-3p#tag/Asynchronous-Reports/operation/createAsyncReport)