Amazon Ads APIを使ってみた

　この記事では、最近よく耳にするAmazon Ads APIのコールまでの手順を紹介したいと思います。Amazon Ads APIを使うと、いろいろ便利な機能が実現できそうなので、ぜひ使ってみてください。なお、Amazon Ads APIの利用には、料金が発生しませんので、APIを使っての開発経験があれば、手軽にテストできます。
### Amazon Ads APIとは
　[Amazon Ads APIの詳細](https://advertising.amazon.com/about-api)については、Amazon Ads公式サイトで紹介しています。簡単にまとめますと、Amazon Ads APIは、Amazon Ads管理画面で実施するキャンペーン運用やレポートダウンロードなどの操作を自動化させるために使うものです。例えば、広告キャンペーンの自動作成、キーワードの自動追加、入札・予算の自動調整などの機能開発が考えられます。API開発者は、Amazon Ads APIを利用して、カスタマイズされた広告運用ツールを開発することで、広告運用者の作業時間を節約し、人的ミスを減らし、効率よく多数の広告キャンペーンを最適化することができます。
　[英語のAmazon Ads API公式レファレンス](https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview)では、Amazon Ads APIのオンボーディング手順を紹介しております。今回は、その手順に従って、Amazon Ads APIを叩いてみたいと思います。操作自体は難しくありませんが、手順は少し複雑であって、内容がちょっと長くなります。最後までご覧ください。なお、全体の流れとしては、以下のような感じになります。
1. 事前準備
1-1. Amazon開発者の登録
1-2. LwA(Login with Amazon)アプリケーションの作成
1-3. Amazon Ads APIアクセス権限の申請
1-4. リダイレクトURLの設定
2. アクセストークンの取得
2-1. 認証コードの取得
2-2. トークンの取得
3. APIコール
### 1. 事前準備
##### 1-1. Amazon開発者の登録
　まず、Amazon開発者の登録をする必要があります。既にAmazon開発者登録済みの場合は、このステップをスキップできます。Amazon開発者の登録は、[Amazon開発者コンソール画面](https://developer.amazon.com/)で行います。必要な情報を入力するだけで、比較的にスムーズに登録できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/9265e1b2-6a82-c4f4-e305-357b9c9f7f2c.png)
##### 1-2. LwA(Login with Amazon)アプリケーションの作成
　Amazon開発者の登録が終わりましたら、以下の図のように、[開発者コンソール画面](https://developer.amazon.com/dashboard)で必要な情報を入力し、LwAセキュリティプロファイルを作成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/fb9e4baf-86ad-dfe5-49e0-44c4af25139a.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/0cac3b52-409e-6183-870a-a708ada46173.png)
　セキュリティプロファイルを作成できたら、「クライアントIDおよびクライアントシークレットを表示」のボタンをクリックして、Amazon Ads APIコールに使うクライアントIDとシークレットの情報を確認できます。後ほどのAPIコールテストは、この情報を使うので、メモしておいたほうが便利です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/e3b2be72-d534-242e-7c6e-c82ebb476ffb.png)
##### 1-3. Amazon Ads APIアクセス権限の申請
　まず、ロールとしては、Amazon Adsパートナーとダイレクト広告主の2種類があります。ロールの違いによって、APIアクセス権限の申請ルートも異なります。Amazon Adsパートナーは、広告代理店やツールプロバイダーとなりますので、今回のAPIテストは、ダイレクト広告主として権限を申請します。
　[こちらのリンク](https://advertising.amazon.com/partner-network/register-api?ref_=a20m_us_api_drctad)にアクセスして、必要な情報を入力したうえ、審査の申請を出します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/73558092-4d95-11d2-a47d-2b833e7d9632.png)
　成功に申請を出した場合は、以下のように、「Success」メッセージが表示されます。なお、基本72時間内に審査結果がわかります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/822ea359-b7ef-1c64-1cd7-b5882a4327f1.png)
　無事に審査が通過した場合は、Amazon Ads <no-reply@amazon.com>から以下のようなメールが届きます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/887e6e30-dccf-a501-8aaf-55464bcf50d8.png)
　`this link`をクリックし、Amazon開発者アカウントでログインし、以下の画面が表示できたら、Amazon Ads APIへのアクセスが可能になります。なお、リンクをクリックする前に、ブラウザ上に他のAmazonアカウントがログインしていないかを確認してください。Amazon開発者でない、他のAmazonアカウントがログインしている状態ですと、自動的にそのアカウントに切り替えてしまい、リンクが失効になる可能性があります。そのため、直接に`this link`をクリックするのではなく、右クリックしてリンクをコピーして、ブラウザーのシークレットモードでこのリンクを開いてログインしたほうが安全です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/4fba298f-dd38-71af-b416-5f0723244282.png)
##### 1-4. リダイレクトURLの設定
　Amazon開発者コンソール画面にて、セキュリティプロファイル管理のところで、リダイレクトURLの設定ができます。「許可された送信URL」は、ユーザーがAPIアクセスを許可した後のリダイレクト先になります。「許可されたオリジン」は、一旦設定なしで問題ないです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/e137cd88-00f8-d561-624a-a57b7d37d59b.png)
　これで事前準備が完了し、次にAmazon Ads APIのユーザー認証とエンドポイントをテストします。
### 2. アクセストークンの取得
##### 2-1. 認証コードの取得
　まず、URLプレフィックスを決める必要があります。以下の表のように、リージョンごとにURLが異なります。
| リージョン | URLプレフィックス |
|:-----------|:------------|
|North America(NA)|https://www.amazon.com/ap/oa| 
|Europe(EU)|https://eu.account.amazon.com/ap/oa| 
|Far East(FE)|https://apac.account.amazon.com/ap/oa| 

　日本の広告アカウントデータを取得したい場合は、3行目のFar East(FE)のURLプレフィックスを使います。今回のテストは、こちらのFar EastのURLを使用します。
　次に、認証コードを取得するためのURLとパラメーターを組みます。4つのパラメーターをURLに追加する必要があります。
| パラメーター | 説明 |
|:-----------|:------------|
|client_id|上記申請したLwAに紐づいているClient ID。Amazon開発者コンソール画面から確認できます。| 
|scope|アクセスのスコープ。スポンサー広告、DSP広告の操作をしたい場合は、`advertising::campaign_management`に設定します。データプロバイダーAPIを使用したい場合は、`advertising::audiences`に設定します。一般にDSP広告、スポンサー広告の操作を行うため、ここは`advertising::campaign_management`にすることが多いです。| 
|response_type|`code`に固定| 
|redirect_uri|Amazon開発者コンソール画面で指定した「許可された送信URL」に設定します。| 

　以下のURLは、上記4つのパラメーターを加えたサンプルURLになります。URL内の大文字の部分は、ご自身が持っている値に置き換えてください。
`https://apac.account.amazon.com/ap/oa?client_id=YOUR_LWA_CLIENT_ID&scope=advertising::campaign_management&response_type=code&redirect_uri=YOUR_RETURN_URL`
　URLを作成できましたら、このURLをブラウザーのアドレスバーに入力して、アクセスします。なお、この操作も、キャッシュのないブラウザーのシークレットモードを使うことをおすすめします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/5619f19f-a3b4-e42a-04a0-05ea4eb80b91.png)
　このURLにアクセスできたら、まずAmazonアカウントのログイン画面が表示されます。APIのアクセス権限を付与したい広告アカウントの管理権限を持つユーザーのアカウント情報を使って、ログインします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/57d525e8-cb5c-68a2-e98c-626f1491e247.png)
　ログインできたら、許可画面が表示されます。「Allow」ボタンをクリックすると、広告アカウントへのAPIアクセス権限が付与されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/38d1460f-6411-2ac1-68c6-1ba0852a0142.png)
　権限付与の承認ができたら、パラメーターに設定されたリダイレクトURLのページに遷移できます。また、ブラウザーのアドレスバーのURLも自動的に変わります。URLのパラメーターには、`code`というものがありまして、この`code`の値をコピーして、後にトークンの取得に使います。なお、この`code`の有効期限は5分しかないので、なるべく早く次のステップに進んでください。`code`の有効期限が切れてしまうと、新しいものを取得する必要があります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/47385d27-6a46-c39e-5667-7f78ecab2147.png)

:::note info
補足
今回はPostmanを使って手動でテストをやるので、ブラウザのURLから`code`をコピペしているのですが、本格的に自動化システムを作りたい場合は、自社サーバー側でこの`code`を受け取る仕組みを実装する必要があります。
:::
##### 2-2. トークンの取得
　これから、Postmanを使って、アクセストークンとリフレッシュトークンを取得します。まずは、広告アカウントのリージョンを参照して、トークン取得のURLを決めます。
| リージョン | URL |
|:-----------|:------------|
|North America(NA)|https://api.amazon.com/auth/o2/token| 
|Europe(EU)|https://api.amazon.co.uk/auth/o2/token| 
|Far East(FE)|https://api.amazon.co.jp/auth/o2/token| 

　日本の広告アカウントデータを取得したいため、ここも3行目のFar East(FE)のURLを使用します。
　次に、パラメーターを決めます。以下の5つのパラメーターが必要です。
| パラメーター | 説明 |
|:-----------|:------------|
|grant_type|`authorizationcode`に固定| 
|code|上記取得した`code`の値| 
|redirect_uri|Amazon開発者コンソール画面で指定した「許可された送信URL」に設定します。| 
|client_id|Amazon開発者アカウントに紐づいているClient ID| 
|client_secret|Client IDに該当するClient Secret| 

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/bc01544c-8715-4bbf-876f-ecde96a5ca8a.png)
　以下は、実際に取得できたトークンのレスポンスの例になります。
```json:example_response.json
{
    "access_token": "Atza|IwEBxxxxxxx",
    "refresh_token": "Atzr|IwEByyyyyy",
    "token_type": "bearer",
    "expires_in": 3600
}
```
　後ほどレスポンス内の`access_token`を使って、実際にAPIのコールをします。なお、`access_token`の有効期限は60分しかないので、期限が切れる前に、`refresh_token`を使って、`access_token`を更新する必要があります。`refresh_token`は、特に有効期限が設けられておらず、使い続けることができます。
##### 3. APIコール
　ここで、実際にAmazon Ads APIのエンドポイントを呼んでみたいと思います。一番最初は、広告アカウント情報を取得してみます。APIをコールする前に、リージョンごとにURLプレフィックスを決める必要があります。
| URL |リージョン|マーケットプレイス|
|:-----------|:------------|:------------|
|https://advertising-api.amazon.com|North America (NA)|米国、カナダ、メキシコ、ブラジル| 
|https://advertising-api-eu.amazon.com|Europe (EU)| イギリス、フランス、イタリア、スペイン、ドイツ、オランダ、アラブ首長国連邦、ポーランド、トルコ、エジプト、サウジアラビア、スウェーデン、ベルギー、インド| 
|https://advertising-api-fe.amazon.com|Far East (FE)|日本、オーストラリア、シンガポール| 

　今回は、日本の広告アカウントの情報を取得したいので、同じく3行目のURLを使います。
　広告アカウントの情報を取得するエンドポイントは、`/v2/profiles`となります。リクエストヘッダーに、以下の情報を入れてコールしてみます。
| キー | 説明 |
|:-----------|:------------|
|Amazon-Advertising-API-ClientId|LwAアプリケーションのClient ID| 
|Authorization|`Bearer` + 上記取得した`access_token`の値| 

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3119752/2eb37741-e0c5-9a69-0824-b31faaad31a8.png)
　以下は、実際のレスポンス例になります。ここで、複数の広告アカウント情報を取得できました。レスポンス内の`profileId`は、広告アカウントごとに発行され、APIコールする際に使う "広告アカウントID" みたいなものです。以降は、特定の広告アカウントのデータを取得したい場合は、その広告アカウントに該当する`profileId`をリクエストヘッダに入れる必要があります。
　また、広告アカウントに紐づいているセーリングパートナーアカウントの種類(sellerかvendorか)の情報も入っています。なお、ここでテストに使ったユーザーは、複数の広告アカウントを管理しているため、そのユーザーが管理する全ての広告アカウント情報を取得できました。
```json:example_response.json
[
    {
        "profileId": 0000000000,
        "countryCode": "JP",
        "currencyCode": "JPY",
        "dailyBudget": 9.99999999E8,
        "timezone": "Asia/Tokyo",
        "accountInfo": {
            "marketplaceStringId": "A1VC38T7YXB528",
            "id": "AXXXXXXXXXXX",
            "type": "seller",
            "name": "xxxxxxxxxxx",
            "validPaymentMethod": true
        }
    },
    {
        "profileId": 0000000000,
        "countryCode": "JP",
        "currencyCode": "JPY",
        "timezone": "Asia/Tokyo",
        "accountInfo": {
            "marketplaceStringId": "A1VC38T7YXB528",
            "id": "ENTITYAAAAAAAA",
            "type": "vendor",
            "name": "aaaaaaaa",
            "validPaymentMethod": true
        }
    },
    {
        "profileId": 0000000000,
        "countryCode": "JP",
        "currencyCode": "JPY",
        "timezone": "Asia/Tokyo",
        "accountInfo": {
            "marketplaceStringId": "A1VC38T7YXB528",
            "id": "ENTITYBBBBBBBB",
            "type": "vendor",
            "name": "bbbbbbbb",
            "validPaymentMethod": true
        }
    },
    {
        "profileId": 0000000000,
        "countryCode": "JP",
        "currencyCode": "JPY",
        "timezone": "Asia/Tokyo",
        "accountInfo": {
            "marketplaceStringId": "A1VC38T7YXB528",
            "id": "ENTITYCCCCCCCC",
            "type": "vendor",
            "name": "cccccccc",
            "validPaymentMethod": true
        }
    }
]
```
### まとめ
　今回は、Amazon Ads APIのアクセス権限を申請し、実際に広告アカウント情報を取得するAPI `/v2/profiles`をコールしてみました。Amazon Ads APIの権限申請が承認されるまで、少し時間がかかったのですが、ユーザーの認証やAPIコール自体は、比較的に簡単に実施できると感じています。Amazon広告アカウントの運用をより効率化にしたい方は、ぜひAmazon Ads APIを使ってみてください。
　次回は、広告アカウント情報の取得だけではなく、実施のレポートデータをダウンロードしてみたいと思います。