# 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の担当者またはテクニカルサポートにお問い合わせください。

## Treasure コンソール経由で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. Treasure コンソールを開きます。
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)

### Data Preview

インポートを実行する前に、Generate Preview を選択してデータの[プレビュー](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data)を表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。

1. **Next** を選択します。Data Preview ページが開きます。
2. データをプレビューする場合は、**Generate Preview** を選択します。
3. データを確認します。


### Data Placement

データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。

1. **Next** を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。
2. **Database** を選択 > **Select an existing** または **Create New Database** を選択します。
3. オプションで、database 名を入力します。
4. **Table** を選択 > **Select an existing** または **Create New Table** を選択します。
5. オプションで、table 名を入力します。
6. データをインポートする方法を選択します。
  - **Append** (デフォルト) - データインポートの結果は table に追加されます。
table が存在しない場合は作成されます。
  - **Always Replace** - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。
  - **Replace on New Data** - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。
7. **Timestamp-based Partition Key** 列を選択します。
デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。
8. データストレージの **Timezone** を選択します。
9. **Schedule** の下で、このクエリを実行するタイミングと頻度を選択できます。


#### 一度だけ実行

1. **Off** を選択します。
2. **Scheduling Timezone** を選択します。
3. **Create & Run Now** を選択します。


#### 定期的に繰り返す

1. **On** を選択します。
2. **Schedule** を選択します。UI では、*@hourly*、*@daily*、*@monthly*、またはカスタム *cron* の 4 つのオプションが提供されます。
3. **Delay Transfer** を選択して、実行時間の遅延を追加することもできます。
4. **Scheduling Timezone** を選択します。
5. **Create & Run Now** を選択します。


転送が実行された後、**Data Workbench** > **Databases** で転送の結果を確認できます。

## 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: <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 | Treasure コンソールの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: <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)