開発者ガイドの概要

Amazon Ads APIの概要

プロフィール

Amazon Ads APIのプロフィールは、特定のマーケットプレイスにおける広告主様のアカウントを表します。広告主様は、1つのマーケットプレイスでしか広告を掲載しない場合は1つのプロフィールを使用し、地域またはグローバルに広告を掲載する場合はマーケットプレイスごとに別個のプロフィールを使用することができます。

プロフィール、アカウント、ID

Amazon Ads APIのプロフィールは、Amazon Adsコンソールの_アカウント_に相当します。マーケットプレイスごとに個別の_アカウント_を設定します。コンソールでもAPIでも、1人の_ユーザー_（広告主様）が、同じAmazonログイン認証情報を使用して複数のアカウントを管理することができます。

Amazon Ads APIでは、プロフィールは、特定の呼び出しの管理範囲を決定する重要な役割を果たします。プロフィールIDは、特定のマーケットプレイスで広告主様のデータやサービスにアクセスするために必須の認証情報です。

認可

Amazon Ads APIを呼び出すには、OAuth 2.0に基づく認可が必要です。呼び出しを正常に実行するためには、リクエストヘッダーに以下を指定する必要があります。

さらに、Amazon Ads APIで利用可能なほとんどのリソースは、リクエストヘッダーで特定のプロフィールIDを渡すことを必要とします。この値は、Amazon-Advertising-API-Scopeパラメーターとして渡します。

プロフィールが1つしかない広告主様の場合でも、このヘッダーは必須です。Amazon-Advertising-API-Scopeヘッダーが含まれていないか正しくない場合には、401 Unauthorizedまたは400 Bad Requestレスポンスが返されます。

プロフィールの取得

特定の広告主様のプロフィールのリストは、/v2/profilesエンドポイントにGETリクエストを使用することで取得できます。この呼び出しには、Amazon-Advertising-API-Scopeヘッダーは必要ありません。

取得したリストには、アクセストークンで表される許可を持つ広告主様に紐づけられたプロフィールが含まれています。取得したリストに含まれているプロフィールはそれぞれ、特定のマーケットプレイスにおける広告主様のアカウントを表しています。

後続のAPI呼び出しでは、特定のプロフィールのprofileIdを渡すことで、そのプロフィールのマーケットプレイスにある広告主様のリソースへのアクセス権を提供します。

注

GET /v2/profilesからのレスポンスには、最大で5000アイテムが含まれます。

地域

プロフィールリソースで返されるのは、呼び出し先のAPIサーバーでカバーされている地域にマーケットプレイスがあるプロフィールのみです。

たとえば、JPおよびSGマーケットプレイスにのみアカウントを持つ広告主様の場合は、https://advertising-api.amazon.com/v2/profilesを使用して北米サーバーにGETリクエストを実行すると、レスポンス本文として[ ]を受け取ります。この広告主様が対象地域のプロフィールを取得するには、https://advertising-api-fe.amazon.com/v2/profilesを使用して極東サーバーを呼び出す必要があります。

特定のサーバーでカバーされている地域にないマーケットプレイスのプロフィールのprofileIdをAmazon-Advertising-API-Scopeヘッダーとして渡しても、そのサーバーにおける他の操作に関する認可は提供されません。4XX - Unauthorizedレスポンスが返されます。

権限

デフォルトでは、GET /profilesエンドポイントで表示されるのは、キャンペーンを閲覧および編集する権限を持っているプロフィールのみです。これは、リクエストのapiProgramおよびaccessLevelクエリパラメーターを使用して調整できます。

たとえば、次のリクエストの場合、許可を付与したアカウントがレポートを閲覧する権限を持っている、北米のプロフィールリストが返されます。

https://advertising-api.amazon.com/v2/profiles?accessLevel=view&apiProgram=report

プロフィールタイプ

プロフィールリソースには、そのプロフィールに紐づけられたアカウントに関するメタデータを含むaccountInfoオブジェクトが含まれます。typeプロパティは、アカウントタイプを表しています。現在、次の3つのタイプがあります。

Typeプロパティの値 アカウントタイプ 説明
vendor 取引会社 このアカウントは、お取引会社様のアカウントです。お取引会社様のアカウントは、スポンサープロダクト広告、スポンサーブランド広告、スポンサーディスプレイ広告でのみ使用されます。
seller 出品者 このアカウントは、出品者様のアカウントです。出品者様のアカウントは、スポンサープロダクト広告、スポンサーブランド広告、スポンサーディスプレイ広告でのみ使用されます。スポンサーブランド広告とスポンサーディスプレイ広告の場合、アカウントはブランド登録されている必要があります。
agency 代理店 このアカウントは、代理店様のアカウントです。代理店アカウントは DSP APIとデータプロバイダーAPIでのみ使用されます。

ヒント

profileTypeFilterパラメーターを使用して、特定のプロフィールタイプのみを含むようにレスポンスをフィルタリングすることができます。

例

プロフィールの取得

この例では、ある広告主様がCA、MX、USのマーケットプレイスでアカウントを運用しています。この広告主様は、IDがamzn1.application-oa2-client.XXXのクライアントに対して、広告主様のデータとサービスにアクセスする許可を付与し、クライアントはアクセストークンAtza|zZzZzZzZを取得済みです。

北米サーバーでAPIに対する次の呼び出しを行うと、3つのプロフィールが含まれるリストが取得できます。

GET /v2/profiles HTTP/1.1
Host: advertising-api.amazon.com
Content-Type: 'application/json'
Authorization: 'Bearer Atza|zZzZzZzZ'
Amazon-Advertising-API-ClientId: 'amzn1.application-oa2-client.XXX'

レスポンス本文：

[
  {
    "profileId": 777777777,
    "countryCode": "CA",
    "currencyCode": "CAD",
    "timezone": "America/Los_Angeles",
    "accountInfo": {
      "marketplaceStringId": "A2EUQ1WTGCTBG2",
      "id": "ENTITY2Plqweuieorf",
      "type": "vendor",
      "name": "Name of the Account",
      "validPaymentMethod": false
    }
  },
  {
    "profileId": 888888888,
    "countryCode": "MX",
    "currencyCode": "MXN",
    "timezone": "America/Los_Angeles",
    "accountInfo": {
      "marketplaceStringId": "A1AM78C64UM0Y8",
      "id": "ENTITY2Ihjasdjkeru",
      "type": "vendor",
      "name": "Name of the Account",
      "validPaymentMethod": false
    }
  },
  {
    "profileId": 999999999,
    "countryCode": "US",
    "currencyCode": "USD",
    "timezone": "America/Los_Angeles",
    "accountInfo": {
      "marketplaceStringId": "ATVPDKIKX0DER",
      "id": "ENTITYZIbbbbbrrr",
      "type": "vendor",
      "name": "Name of the Account",
      "validPaymentMethod": true
    }
  }
]

プロフィールIDの使用

この広告主様は、APIを追加で呼び出す毎に、上記のプロフィールのいずれかに関連するリソースにアクセスできます。

たとえば、この広告主様のMXにあるアカウントのスポンサープロダクト広告キャンペーンリソースにアクセスする場合は、上記の2番目のプロフィールのprofileIdをAmazon-Advertising-API-Scopeヘッダーとして指定します。

GET /v2/sp/campaigns HTTP/1.1
Host: advertising-api.amazon.com
Content-Type: 'application/json'
Authorization: 'Bearer Atza|zZzZzZzZ'
Amazon-Advertising-API-ClientId: 'amzn1.application-oa2-client.XXX'
Amazon-Advertising-API-Scope: 888888888

USまたはCAのアカウントにアクセスする場合には、対応するprofileIdをAmazon-Advertising-API-Scopeヘッダーとして渡して、それぞれのプロフィールで追加のリクエストを実行する必要があります。

プロフィールの概念

詳細はこちら

次のガイドで詳細をご覧ください。

詳しいガイドに従ってAmazon Ads APIで認可を設定するには、オンボーディングのウォークスルーをご覧ください。

Amazon Advertising logo