APIを使ってAmazon Marketing Cloudに1Pデータをアップロードしてみた

Last updated at 2025-02-20Posted at 2025-02-05

　本記事では、Amazon Marketing Cloud (AMC)で高度なカスタム分析を実施したい広告主や広告代理店向けに、1Pデータ（ファーストパーティーデータ）のアップロード手順をご説明します。PostmanツールでAmazon Ads APIを活用し、AMCへのデータアップロードを効率的に行う方法を解説します。

　なお、本ガイドはAmazon Ads Advanced tools centerのレファレンスを基に作成しています。内容に相違がある場合はAmazon Ads公式の情報が優先されます。Amazon Ads APIとAMCの詳細については、Amazon Adsのホームページをご確認ください。

　1Pデータのアップロードは一見複雑に感じるかもしれませんが、実際に試してみると意外とシンプルです。この記事を作成する際のテスト作業では2時間もかからずにデータのアップロードを完了することができました。ぜひ最後までご覧ください。

はじめに

AMC 1Pデータ分析とは

　AMCは、Amazon Adsのシグナルと広告主の1Pデータを組み合わせた高度な分析が可能なグリーンルームソリューションです。主な活用例は以下の通りです：

1. クロスチャネル分析

Amazon Adsの広告露出と実店舗での購買データの関連性分析
オフラインコンバージョンとデジタル広告の効果測定

2. カスタマージャーニー分析

広告接触から購入までの詳細な行動分析
各タッチポイントの貢献度測定
最適な広告頻度の特定

3. オーディエンス分析

高価値顧客セグメントの特定
商品カテゴリー別の顧客行動分析
ターゲティング戦略の最適化

　1Pデータを活用した高度な分析に興味があるものの、データのアップロード方法がわからないという方に、本記事が参考になれば幸いです。

使用ツールの説明

Postman

　APIの開発やテストを行うためのツールです。本ガイドではAMC APIのコールに使用します。

主な機能：

直感的なGUIでのAPIリクエスト作成
APIコレクションの保存と共有
リクエスト履歴の管理

AWS S3

　AWSが提供するクラウドストレージサービスで、AMCへのデータアップロード時の一時保管場所として使用します。

主な特徴：

高い耐久性（99.999999999%）
強力なセキュリティ機能
柔軟なアクセス制御
効率的なデータ管理

実装手順

事前準備

Postmanアプリケーション（公式サイトからダウンロード）
AWS S3バケット
Amazon Ads API認証情報（Client ID、Client Secret）
アップロード用データファイル

※Amazon Ads APIを初めて利用する方は、Amazon Ads APIのPostmanコレクションを使ってみたをご参照ください。

1. アップロード用のデータ準備

　AMCのデータアップロードは、1ファイルあたり最大1GBまでサポートしています。1GBを超える場合は、複数のファイルに分割する必要があります。ファイル形式は以下をサポートしています：

ファイル形式：CSV、JSON、Parquet
圧縮形式（推奨）：BZIP、GZIP、ZIP、SNAPPY

　本記事では、テスト用に非圧縮のUTF-8形式CSVファイルを使用します。

　以下、テスト用サンプルCSVファイルの内容です：

email,product_name,sku,quantity,purchase_time
04fd97dc12ae0e4a38cae86eb36d2238704eb5e8826f5cf0091378fbc7204562,Product A,11352987,2,2024-06-23T19:53:58Z
76f5fee04acd74ca097e09b0ac895d353f4f91fc6ee5a2e720e0158a081c9636,Product B,18467234,2,2024-06-24T19:53:58Z
5004afc9cedb5ce8d91efd1595417d04cef99f0e23efcd1fadef294a2986098c,Product C,27264393,2,2024-06-25T19:53:58Z
87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674,Product A,48572094,2,2024-06-25T19:53:58Z
2e42df16bbadf1373787f7c8bd80e204a49b68c89abbf0ed68b04f418b3374cc,Product B,18278476,1,2024-06-24T19:53:58Z

　注目すべき点として、emailカラムの値は通常のメールアドレス形式（xxx@xxx.xxx）ではなく、ハッシュ化された文字列になっています。AMCでは個人を特定するための情報（PII）をアップロードする際、セキュリティ上の理由から、必ずSHA-256でハッシュ化する必要があります。

　ハッシュ化は非可逆的な暗号化処理で、変換後の値から元の値を復元することはできません。これにより、データの安全性を確保しています。ハッシュについての詳細はこちらのwikiをご参照ください。

2. AWS S3バケットの設定

1. バケット作成

AWSコンソールでS3サービスに移動
「バケットを作成」をクリック
バケット名とリージョンを設定
その他はデフォルト設定で作成

2. バケットポリシー設定

　以下のポリシーをS3バケットに適用します：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::{Data upload AWS account ID}:root"
      },
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:ListBucket",
        "s3:GetObjectTagging",
        "s3:GetBucketTagging"
      ],
      "Resource": [
        "arn:aws:s3:::{bucket_name}/*",
        "arn:aws:s3:::{bucket_name}"
      ]
    }
  ]
}

　置き換えが必要な項目：

{Data upload AWS account ID}: AMCインスタンスのInstance info画面に表示されるData upload AWS account IDの値
{bucket_name}: 作成したS3バケットの名前

AMC Instance info画面

　以下、今回テスト用に作成した新しいS3バケットのポリシーになります。

3. タグ設定

　S3バケットのプロパティ画面で、以下のタグを設定します：

キー: instanceId（固定値）
値: データをアップロードするAMCインスタンスのID

　タグ設定のイメージ：

4. データのアップロード

　今回はテスト用として、AWS管理画面から手動でデータファイルをアップロードします。実運用では、AWS APIやSDKを利用した自動アップロードの仕組みを構築することをお勧めします。

　アップロード完了画面：

3. PostmanでのAPI実行

　事前にAmazon Ads APIのアクセス権限申請とAMC AccountでのAPI client IDへの権限付与が必要です。詳細はAmazon Ads APIのPostmanコレクションを使ってみたをご参照ください。

1. データセット作成

データセット作成APIの詳細仕様については、こちらのリンクにてご確認ください。

リクエストURL例：

POST https://advertising-api-fe.amazon.com/amc/advertiserData/amcxxxxl6/dataSets

リクエストヘッダー例：

Amazon-Advertising-API-ClientId:{client_id}
Authorization:Bearer {access_token}
Amazon-Advertising-API-AdvertiserId:{AMC_Account_ID}
Amazon-Advertising-API-MarketplaceId:{Marketplace_ID}

{client_id}:　API Client ID
{access_token}:　API シークレット
{AMC_Account_ID}:　AMCアカウントのEntity ID
{Marketplace_ID}:　日本の場合は、固定値A1VC38T7YXB528

リクエストボデイ例：

{
    "dataSet": {
        "dataSetId": "first_party_data_test",
        "description": "First party data upload test",
        "columns": [
            {
                "name": "email",
                "description": "Hashed customer email",
                "dataType": "STRING",
                "columnType": "DIMENSION",
                "nullable": true,
                "externalUserIdType": {
                    "hashedPii": "EMAIL"
                }
            },
            {
                "name": "product_name",
                "description": "Product name",
                "dataType": "STRING",
                "columnType": "DIMENSION"
            },
            {
                "name": "sku",
                "description": "Product SKU",
                "dataType": "STRING",
                "columnType": "DIMENSION"
            },
            {
                "name": "quantity",
                "description": "Purchase quantity",
                "dataType": "INTEGER",
                "columnType": "METRIC"
            },
            {
                "name": "purchase_time",
                "description": "Purchase timestamp",
                "dataType": "TIMESTAMP",
                "columnType": "DIMENSION",
                "isMainEventTime": true
            }
        ],
        "countryCode": "JP"
    }
}

※countryCodeは、API仕様上、必須項目ではないが、PIIデータをアップロードしてAmazonユーザーとマッチする際に指定しないと、Amazonユーザーとマッチできません。

レスポンス例：

{"dataSetId":"first_party_data_test","instanceId":"amcxxxxl6"}

　データセットの作成が完了すると、AMC画面のQuery editor ⇒ Advertiser uploadedセクションに新しいデータセットが表示されます。

2. データアップロード

データアップロードAPIの詳細仕様については、こちらのリンクにてご確認ください。

リクエストURL例：

POST https://advertising-api-fe.amazon.com/amc/advertiserData/amcxxxxl6/uploads/first_party_data_test

リクエストボデイ例：

{
  "updateStrategy": "ADDITIVE",
  "compressionFormat": "NONE",
  "dataSource": {
    "sourceFileS3Key": "AMC1PDataUplaodTestFile.csv",
    "sourceS3Bucket": "amc1pdatauploadbucket"
  },
  "fileFormat": {
    "csvDataFormat": {
      "recordDelimiter": "\r",
      "fieldDelimiter": ","
    }
  }
}

レスポンス例：

{"status":"SUBMITTED","uploadId":"52fc5xxxxxxxxxxxxx418c"}

3. アップロードステータス確認

アップロードステータス確認APIの詳細仕様については、こちらのリンクにてご確認ください。

リクエストURL例：

GET https://advertising-api-fe.amazon.com/amc/advertiserData/amcxxxxl6/uploads/first_party_data_test/52fc5xxxxxxxxxxxxx418c

レスポンス例：

{
    "upload": {
        "createdAt": "2025-02-04T08:03:59Z",
        "dataSetId": "first_party_data_test",
        "dataSource": {
            "sourceFileS3Key": "AMC1PDataUplaodTestFile.csv",
            "sourceS3Bucket": "amc1pdatauploadbucket"
        },
        "instanceId": "amcjamsgil6",
        "metrics": {
            "DistinctHashedIdentities": 5.0,
            "DistinctProvidedIdentities": 5.0,
            "NumberOfRowsDroppedForBeingBeyondRetention": 0.0,
            "RecordsAccepted": 5.0,
            "RecordsProvided": 5.0,
            "RecordsWithProvidedIdentity": 5.0,
            "RecordsWithRecognizedHashedIdentity": 4.0
        },
        "status": "SUCCESS",
        "updatedAt": "2025-02-04T08:08:01Z",
        "uploadId": "52fc5xxxxxxxxxxxxx418c"
    }
}

　アップロードステータスについて：

SUCCESS: アップロード成功
IN_PROGRESS/SUBMITTED: 処理中
FAILED: アップロード失敗（失敗理由が記載されます）

　AMC管理画面でもレコード数を確認できます：

　今回のテストでは、データのアップロードは成功しましたが、レコード数が0となりました。これは、アップロードしたemailハッシュ値とAMCインスタンス内のAmazonユーザーデータとマッチしなかったためです。AMCの仕様としては、アップロードされたPIIデータとAmazonユーザーデータがマッチした場合、内部のuser_idとuser_typeが自動的に割り当てられます

　本番の1Pデータをアップロードしてマッチングが成功すれば、冒頭で説明したような様々な分析が可能になります。分析の開始には：

カスタムSQLの作成
AMC管理画面のInstructional queriesの活用

のいずれかの方法が選択できます。

　AMCの管理画面でAdvertiser data uploadの条件で検索すれば、サンプルの分析クエリが参照できます。

まとめ

　本記事では、Amazon Marketing Cloud (AMC)を活用して、1Pデータのアップロードを効率的に行う方法を解説しました。具体的には、Postmanツールを使用してAmazon Ads APIを活用し、データをAmazon S3にアップロードする手順を説明しました。また、アップロードするデータはハッシュ化する必要があり、そのセキュリティやプライバシーを守る方法にも触れました。

　AMCにデータをアップロードすることで、広告主や代理店はAmazonのシグナルと自社のデータを組み合わせた高度な分析が可能となります。クロスチャネル分析やカスタマージャーニーの理解を深め、オーディエンスターゲティングを最適化するための強力なツールとなるでしょう。

　これにより、データ分析の幅が広がり、広告キャンペーンの効果をより詳細に把握できるようになります。さらに、AMCに蓄積されたデータを使って、カスタムSQLを駆使した分析や、Instructional queriesを活用することで、迅速にインサイトを得ることができます。これからのデータ分析業務において、AMCの活用はますます重要になっていくことでしょう。

　本記事では、PostmanとAWSを使用した手動でのデータアップロード手順を紹介しました。これは検証やテスト目的には適していますが、実際の分析業務ではより効率的なアプローチが必要となります。

　実務においては、定期的なデータ更新や複数の広告アカウントの同時管理、大量データの自動処理といったニーズが発生することが一般的です。これらの要件に効率的に対応するためには、AWSのSDKやAPIを活用した自動処理システムの構築が有効です。Amazon Ads APIとの連携やバッチ処理による定期的なデータ更新の仕組みを整備することで、より安定的で効率的な運用が可能になります。

　このようなスケーラブルなソリューションの構築には初期の開発コストが必要となりますが、長期的な視点で見ると大きな価値があります。運用効率の大幅な向上や人的エラーの削減、データ処理の高速化、そしてリソースの効率的な活用といった多くのメリットが得られ、結果として投資に見合う十分な価値を生み出すことが期待できます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up