# Amazon Ads Conversion Export Integration

Amazon Ads Conversion API（CAPI）により、広告主はTreasure DataからAmazon Advertisingに直接コンバージョンイベントと顧客アクションを送信し、アトリビューションと測定の目的で使用できます。このサーバー間統合は、ブラウザの制限を回避し、より信頼性の高いコンバージョントラッキングを提供します。

Amazon Ads Conversion Export integrationは、Treasure Dataユーザーがプライバシーコンプライアンスを強化し、Amazon DSPおよびSponsored Adsキャンペーンのアトリビューション精度を向上させたコンバージョンイベントの送信をサポートします。

## 前提条件

- Treasure Dataの基本知識
- Amazon Adsキャンペーン管理とコンバージョントラッキングの基本知識
- Conversion APIの権限を持つAmazon Adsアカウントへのアクセス
- コンバージョンイベントとアトリビューションモデルの理解


## 要件と制限事項

- イベントごとに少なくとも1つの顧客識別子を提供する必要があります
- 最大バッチサイズ：リクエストあたり500イベント
- 最適なアトリビューションのため、イベントはできるだけリアルタイムに近い形で送信する必要があります
- PIIフィールドはAmazonの要件に従って正規化し、SHA-256でハッシュ化する必要があります。非PII識別子はAmazonのフィールド固有の要件に従います


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

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

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

## Data Workbenchを使用して接続を作成する

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

### 新しい認証を作成する

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

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


![Integrations Hub Catalog](/assets/integrations-hub-catalog.8df5b5674fa8f3c15ebfcca865f1058fb541866c61483999cd59ddb6d527cf95.d34bb0cc.png)

1. Catalogで**Amazon Ads Conversion**を検索し、アイコンにマウスを合わせて**Create Authentication**を選択します。


![Create Authentication](/assets/create-authentication.088df45cd7f66e73005fd2e9436ac7f52071fda1d7e65e11c9ce900bbf46867e.d34bb0cc.png)

New Authenticationモーダルが表示されます。

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


### 認証IDの取得

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

認証IDを取得するには：

1. **Integrations Hub > Authentications**に移動します。
2. 使用したい統合を選択します。Edit Authenticationモーダルが表示されます。
3. ブラウザのアドレスバーで、URLの末尾にある認証IDを確認します。


## クエリを定義する

1. **Data Workbench > Queries**に移動します。
2. **New Query**を選択します。
3. テーブルドロップダウンメニューから、クエリしたいデータベースを選択します。
4. クエリを入力します。


サンプルクエリは以下の通りです：


```sql
SELECT   
  'Product Purchase'                AS event_name,              -- 必須
  'OFF_AMAZON_PURCHASES'            AS conversion_type,         -- 必須
  'WEBSITE'                         AS event_source,            -- 必須
  'US'                              AS country_code,            -- 必須
  purchase_time                     AS event_time,              -- 必須
  customer_email                    AS email,                   -- 条件付き（ハッシュ化）
  customer_phone                    AS phone,                   -- 条件付き（ハッシュ化）
  customer_first_name               AS first_name,              -- 条件付き（ハッシュ化）
  customer_last_name                AS last_name,               -- 条件付き（ハッシュ化）
  quantity                          AS units_sold,              -- 条件付き
  purchase_value                    AS value,                   -- オプション
  'USD'                             AS currency_code,           -- オプション
  order_id                          AS event_id,                -- オプション
  product_category                  AS custom_field_1,          -- オプションのカスタムデータ
  customer_segment                  AS custom_field_2           -- オプションのカスタムデータ
FROM   
  conversion_events
WHERE
  TD_INTERVAL(purchase_time, '-1d', 'JST')
```

クエリの必須フィールドと条件付きフィールドは以下の通りです：

| フィールド | 必須 | データタイプ | ハッシュ化必須 | 説明 |
|  --- | --- | --- | --- | --- |
| event_name | はい | STRING | いいえ | コンバージョンイベントの名前 |
| conversion_type | はい | STRING | いいえ | 次のいずれかである必要があります：OFF_AMAZON_PURCHASES、ADD_TO_SHOPPING_CART、APPLICATION、CHECKOUT、CONTACT、LEAD、MOBILE_APP_FIRST_START、PAGE_VIEW、SEARCH、SIGN_UP、SUBSCRIBE、OTHER |
| event_source | はい | STRING | いいえ | 次のいずれかである必要があります：ANDROID、FIRE_TV、IOS、OFFLINE、WEBSITE、MEASUREMENT_ATTRIBUTION_PARTNER |
| country_code | はい | STRING | いいえ | ISO 3166-1 alpha-2国コード（US、CA、JPなど） |
| event_time | はい | STRING/LONG | いいえ | ISO形式（YYYY-MM-DDThh:mm:ssTZD）またはUnixタイムスタンプ |
| email | 条件付き | STRING | はい | 顧客のメールアドレス（SHA-256ハッシュ化） |
| phone | 条件付き | STRING | はい | 国コード付きの顧客電話番号（SHA-256ハッシュ化） |
| first_name | 条件付き | STRING | はい | 顧客の名（SHA-256ハッシュ化） |
| last_name | 条件付き | STRING | はい | 顧客の姓（SHA-256ハッシュ化） |
| address | 条件付き | STRING | はい | 住所（SHA-256ハッシュ化） |
| city | 条件付き | STRING | はい | 市区町村名（SHA-256ハッシュ化） |
| state | 条件付き | STRING | はい | 州/都道府県（SHA-256ハッシュ化） |
| postal | 条件付き | STRING | はい | 郵便番号（SHA-256ハッシュ化） |
| maid | 条件付き | STRING | いいえ | モバイル広告ID |
| match_id | 条件付き | STRING | いいえ | カスタムマッチ識別子 |
| units_sold | 条件付き | LONG | いいえ | conversion_typeがOFF_AMAZON_PURCHASESの場合のみ |
| value | いいえ | STRING/LONG/DOUBLE | いいえ | コンバージョン値（数値） |
| currency_code | いいえ | STRING | いいえ | conversion_typeがOFF_AMAZON_PURCHASESの場合のみ。次のいずれかである必要があります：AED、AUD、BRL、CAD、CNY、DKK、EUR、GBP、INR、JPY、MXN、NOK、NZD、SAR、SEK、SGD、TRY、USD |
| event_id | いいえ | STRING | いいえ | 重複排除のための一意識別子 |
| partner | 条件付き | STRING | いいえ | event_sourceがMEASUREMENT_ATTRIBUTION_PARTNERの場合は必須 |
| amazon_ad_event_key | 条件付き | STRING | いいえ | event_sourceがMEASUREMENT_ATTRIBUTION_PARTNERの場合は必須 |


顧客識別子の要件
少なくとも1つの顧客識別子フィールド（email、phone、first_name、last_name、address、city、state、postal、maid、またはmatch_id）を提供する必要があります。最適なマッチング精度のためには、メールアドレスまたは電話番号が推奨されます。

## Result Exportターゲットを指定する

Amazon Adsにイベントを送信するためのコンバージョンエクスポート設定を構成します。

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


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

![Export Results Model Part 1](/assets/export-results-modal-1.a3f175f17f8d00d064e6443a2d926b61b058fc24ec6cc0dee0a92cb277b70e9c.d34bb0cc.png)

![Export Results Model Part 2](/assets/export-results-modal-2.5cee48b92b0260b172d582a23aef1a67169623a3435502015fe4ee95e92bb20c.d34bb0cc.png)

1. フィールドに情報を入力します：


| フィールド | 説明 | 備考 |
|  --- | --- | --- |
| Region | アカウントのAmazon Ads APIリージョン | 必須。オプション：North America（NA）、Europe（EU）、Far East（FE） |
| Advertiser ID | Amazon DSP Advertiserアカウント ID | 必須。Amazon Adsアカウント設定で確認できます |
| Dataset Name | Amazonデータセット識別子（オプション） | オプション。Amazonシステムでのコンバージョンデータの整理に使用されます |
| Custom Data | カスタムイベントデータのフィールドマッピング | オプション。形式：field_name: DATA_TYPE（STRING、INTEGER、TIMESTAMP） |
| Consent Type | 使用するプライバシー同意フレームワーク | オプション。オプション：TCF、GPP、ACS |
| Skip Invalid Records | 無効なデータに遭遇した場合の処理継続 | オプション。無効にすると、無効なレコードでジョブが停止します |
| Skip Error Batches | バッチが失敗した場合の処理継続 | オプション。無効にすると、バッチエラーでジョブが停止します |


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


## 結果例


```
************* REPORT *************
2026-04-14 04:34:30.320 +0000 [INFO] (0017:task-0000): ************* REPORT *************
2026-04-14 04:34:30.320 +0000 [INFO] (0017:task-0000): Total records: 1, total skip records: 0, total batches: 1, total skip batches: 0
```

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

## （オプション）ワークフローでのExport Results設定

Treasure ワークフロー内で、この統合を使用してコンバージョンデータをエクスポートするように指定できます。


```yaml
_export:
  td:
    database: td.database
   
+ amazon_ads_conversion_export_task:
  td>: export_conversions.sql
  database: ${td.database}
  result_connection: amazon_ads_conversion_auth
  result_settings:
    type: amazon_ads_conversion
    td_authentication_id: td_authentication_id
    region: NA
    advertiser_id: advertiser_id
    dataset_name: conversion_dataset
    custom_data: product_category:STRING,customer_segment:INTEGER
    consent_type: ACS
    amzn_ad_storage: GRANTED
    amzn_user_data: GRANTED
    limited_data_use: false
    skip_invalid_record: true
    skip_error_batch: false
```

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

[TD Toolbelt](/tools/cli-and-sdks/quickstart)を使用して、td queryコマンドの--resultオプションでAmazon Adsにコンバージョンイベントをエクスポートすることもできます。

--resultオプションで指定するデータはJSON形式です：


```json
{
  "type": "amazon_ads_conversion",
  "td_authentication_id": "${authentication_id_from_td_console}",
  "region": "NA",
  "advertiser_id": "your_advertiser_id",
  "dataset_name": "conversion_dataset",
  "custom_data": "product_category:STRING,customer_segment:INTEGER",
  "consent_type": "ACS",
  "amzn_ad_storage": "GRANTED",
  "amzn_user_data": "GRANTED",
  "limited_data_use": false,
  "skip_invalid_record": true,
  "skip_error_batch": false
}
```

### パラメータ

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | エクスポートの宛先 | "amazon_ads_conversion" |  | はい |
| td_authentication_id | Treasure コンソールでのAmazon Ads認証の認証ID |  |  | はい |
| region | Amazon Ads APIリージョン | "NA"、"EU"、"FE" | "NA" | はい |
| advertiser_id | Amazon DSP AdvertiserアカウントID |  |  | はい |
| dataset_name | Amazonデータセット識別子 |  |  | いいえ |
| custom_data | カスタムフィールドマッピング | "field_name:DATA_TYPE,field_name2:DATA_TYPE" |  | いいえ |
| consent_type | プライバシー同意フレームワーク | "TCF"、"GPP"、"ACS" | 空 | いいえ |
| tcf | TCF同意値 |  |  | consent_typeが"TCF"の場合は必須 |
| gpp | GPP同意値 |  |  | consent_typeが"GPP"の場合は必須 |
| amzn_ad_storage | Amazon広告ストレージ同意 | "GRANTED"、"DENIED" |  | consent_typeが"ACS"の場合は必須 |
| amzn_user_data | Amazonユーザーデータ同意 | "GRANTED"、"DENIED" |  | consent_typeが"ACS"の場合は必須 |
| limited_data_use | 制限付きデータ使用処理の有効化 | true、false | false | いいえ |
| skip_invalid_record | 無効なレコードの処理継続 | true、false | false | いいえ |
| skip_error_batch | エラーバッチの処理継続 | true、false | false | いいえ |


### 使用例

手動エクスポート：


```bash
td query \
--database ${database_name} \
--wait "SELECT * FROM ${conversion_table}" \
--type presto \
--result '{"type":"amazon_ads_conversion","td_authentication_id":"${auth_id}","region":"NA","advertiser_id":"${advertiser_id}","dataset_name":"conversions","skip_invalid_record":true}'
```

スケジュールされたエクスポート：


```bash
td sched:create \
conversions_to_amazon_ads '0 2 * * *' \
--database ${database_name} 'SELECT * FROM ${conversion_table}' \
--result '{"type":"amazon_ads_conversion","td_authentication_id":"${auth_id}","region":"NA","advertiser_id":"${advertiser_id}"}'
```

## トラブルシューティング

### よくある問題

- **認証エラー**: OAuthの権限にコンバージョンAPI アクセスが含まれていることを確認してください
- **データ検証エラー**: すべての必須フィールドが存在し、少なくとも1つの顧客識別子が提供されていることを確認してください
- **ハッシュ形式エラー**: 顧客PIIは適切に正規化され、Amazonのガイドラインに従ってSHA-256でハッシュ化されている必要があります
- **レート制限**: AmazonはAPIレート制限を実施しています。バッチアップロード間に適切な遅延を実装してください
- **顧客識別子の欠如**: イベントごとにメール、電話、またはその他のPIIフィールドのうち少なくとも1つを提供する必要があります


### エラーハンドリング

| エラータイプ | アクション | 再試行 |
|  --- | --- | --- |
| 必須パラメータの欠如 | 設定を修正、ジョブが失敗 | なし |
| 無効なデータタイプ | クエリを修正、ジョブが失敗 | なし |
| HTTP 4xxエラー | API ドキュメントを確認、ジョブが失敗 | なし |
| HTTP 429/5xxエラー | ジョブが自動的に再試行 | あり |


## 外部参考資料

- [Amazon Ads Conversion API Overview](https://advertising.amazon.com/API/docs/en-us/guides/conversions/01-overview)
- [Amazon Ads Events API Documentation](https://advertising.amazon.com/API/docs/en-us/guides/events/events#send-events)
- [Pass Customer Information through Conversions API](https://advertising.amazon.com/help/GH2LNLGJUCECRCK2)
- [Amazon Ads API Onboarding Guide](https://advertising.amazon.com/API/docs/en-us/guides/overview)