開発者ガイドの概要

Amazon Ads APIの概要

クリエイティブAPI開発者ガイド

スポンサーディスプレイ広告では、広告主様が、広告配信時に使用するキャンペーン用の動画、カスタム見出し、ロゴ、カスタム画像をアップロードできます。広告主様は、見出し、ロゴ、カスタム画像を使用してブランドイメージを強化し、広告対象商品の体験をアピールすることができます。

今回のリリースでは、見出し、ロゴ、類似のカスタム画像をアップロードし、そのクリエイティブをさまざまな広告グループに関連付けることができるクリエイティブAPIが提供されています。このAPIを使用する前に、クリエイティブアセット内にロゴまたはカスタム画像を用意しておく必要があります。すでに画像をアップロード済みで、アセットIDがわかっている場合は、「クリエイティブAPI」のセクションに進んでください。

このクリエイティブ開発者ガイドの手順に従うには、スポンサーディスプレイ広告のクリエイティブPostmanコレクションをダウンロードして参照してください。

エンティティ情報を取得する

有効なOAuthトークンを用意します。クリエイティブPostmanコレクションを使用して、oauthフォルダーを展開し、新しいアクセストークンを取得するリクエストを実行します。たとえば、OAuth Refresh Tokenリクエストを使用して新しいアクセストークンを取得します。

oauthフォルダーを展開し、Gets profile informationリクエストを実行します。環境内で設定されたアクセストークンを使用します。

レスポンスは以下を返します。

[
    {
        "profileId": 1234567890,
        "countryCode": "US",
        "currencyCode": "USD",
        "dailyBudget": 9.99999999E8,
        "timezone": "America/Los_Angeles",
        "accountInfo": {
            "marketplaceStringId": "ATVPDKIKX0DER",
            "id": "A123567900",
            "type": "seller",
            "name": "Ad Expresso"
        }
    }
]

エンティティIDは、「accountInfo」の「id」フィールドに基づくものになります。これを以下の手順3で使用します。

クリエイティブアセットAPI

このセクションでは、クリエイティブアセットAPIを使用して、キャンペーンのクリエイティブを作成する際に使用できる新しいロゴ（画像）をアップロードします。

クリエイティブアセットAPIを使用するには以下の手順が必要です。

  1. 新しいアセットのアップロード場所を作成する→この手順により、画像のアップロードに使用するURLが返されます。
  2. 手順1で取得したURLを使用して画像をアップロードする。
  3. アカウントにアセットを登録して、新しくアップロードしたアセットにアクセスできるようにする。

assetsフォルダーを展開して、クリエイティブアセットのリクエストを確認してください。アセットを作成するには、次の3つの手順がすべて必要です。

  1. アセットをアップロードするためのアップロード場所を作成する。（POSTリクエスト）
  2. 画像をアップロードする。（PUTリクエスト）
  3. アップロードしたアセットを、オプションのコンテキスト情報とタグ情報を指定してクリエイティブアセットに登録する。（POSTリクエスト）

手順1

リクエスト本文で、アップロードするファイルの名前を指定します。実際のファイル名と一致している必要があります。ファイル名のサフィックス（例：png）が必要です。サポートされている画像タイプは「JPEG」、「JPG」、「PNG」のみです（大文字、小文字は区別されません）

POST /assets/upload
{
    "fileName": "test_creative.png"
}

このリクエストのレスポンスは、以下を返します。

{
    "url": "https://al-na-9d5791cf-3faf.s3.amazonaws.com/511ca929-566a-4082-89b8-4128eca97cb6.png?x-amz-meta-fileName=test_creative.png&X-Amz-Security-Token=1234567890&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210415T161206Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=ASIA3NCY4QOMVRSXBSPM%2F20210415%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=1234567890"
}

手順2では、このURLを使用します。このURLは、upload_url変数によって、PostmanリクエストのURLフィールドに自動的に取り込まれます。URLの有効期間は通常15分であるため、有効期限が切れた場合は新しいURLを取得する必要があります。

手順2

「binary」オプションを選択し、ペイロードとしてファイルを選択して、ロゴとして使用する画像をPostmanからアップロードします。ファイル名は、前の手順で指定したファイル名と完全に一致している必要があります。*アセット画像の高さは100px以上、幅は600px以上にする必要があり、画像サイズは1MBを超えないようにします。*png、jpg、jpeg形式の画像を使用可能です。

PUT {{upload_url}}
{
    "Select File "
}

手順3

リクエスト本文では、以下を指定できます。

POST /assets/register
{
    "name": "{{fileName}}",
    "url": "{{upload_url}}",
    "assetType": "IMAGE",
    "assetSubTypeList": [
        "LOGO"
    ],
    "tags": [
        "SD"
    ]
}

このリクエストのレスポンスは、以下を返します。

{
    "assetId": "amzn1.assetlibrary.asset1.becf0adee0b0dc4e8ab96f3db46bxxxx",
    "versionId": "version_v1"
}

オプションで、次のいずれかを使用してアセットを検索できます。

クリエイティブAPI

クリエイティブAPIでは、見出し、ロゴ、またはカスタム画像を使用してクリエイティブを作成できます。ロゴとカスタム画像は、前のセクションで作成したassetIdを使用して参照します。

クリエイティブAPIを呼び出す前に、キャンペーン、広告グループ、プロダクト広告、ターゲットを作成しておいてください。プロダクト広告を作成するときは、使用するASIN/SKUが有効で入手可能であることを確認してください。以下の手順を実行してクリエイティブを広告グループに追加するために、新しいadGroupIdを用意しておく必要があります。

*「sd」→「creatives」*フォルダーを展開してリクエストを確認してください。

手順1

クリエイティブアセットAPIの手順3で取得したassetIdとversionIdを使用します。Postmanスクリプトでは、前のセクションのリクエストの実行に基づいて、これらのIDが変数として渡されます。アセット画像の高さは100px以上、幅は600px以上でなければなりません。

Amazon Ads APIで、ブランドロゴを作成する例

POST /sd/creatives
[
    {
        "adGroupId": 1234567890,
        "properties": {
            "headline": "Test Headline (input custom headline)",
            "brandLogo": {
                "assetId": "{{assetId}}",
                "assetVersion": "{{versionId}}",
                "croppingCoordinates": {
                    "top": 0,
                    "left": 0,
                    "width": 600,
                    "height": 100
                }
            }
        }
    }
]

このリクエストのレスポンスは、以下を返します。

[
    {
        "code": "SUCCESS",
        "creativeId": 1234567890111213,
    }
]

Amazon Ads APIで、カスタム画像を作成する例

POST /sd/creatives
[
    {
        "adGroupId": 1234567890,
        "properties": {
            "contentType": "CUSTOM_IMAGE",
            "rectCustomImage": {
                "assetId": "{{assetId}}",
                "assetVersion": "{{versionId}}",
                "croppingCoordinates": {
                    "top": 0,
                    "left": 0,
                    "width": 1200,
                    "height": 628
                }
            },
            "squareCustomImage": {
                "assetId": "{{assetId}}",
                "assetVersion": "{{versionId}}",
                "croppingCoordinates": {
                    "top": 0,
                    "left": 0,
                    "width": 628,
                    "height": 628
                }
            }
        }
    }
]

このリクエストのレスポンスは、以下を返します。

[
    {
        "code": "SUCCESS",
        "creativeId": 1234567890111213,
    }
]

手順2

PUT呼び出しを使用して、指定したadGroupIdのクリエイティブに関連するassetId、headline、croppingCoordinatesなどのクリエイティブ変数を編集できます。

PENDING_REVIEWステータスのクリエイティブは更新できません。クリエイティブが承認または却下されるまで待つ必要があります。クリエイティブが承認または却下されたら、クリエイティブを更新できます。更新時に、headlineとbrandLogoセクションを何も変更しなかった場合、クリエイティブ更新APIは直接「200 OK」を返し、クリエイティブの審査の状況は以前と同じままになります。見出しとロゴに変更を加えてクリエイティブを更新した場合にのみ、審査の状況がPENDING_REVIEWにリセットされ、変更したクリエイティブの審査プロセスが開始されます。

PUT /sd/creatives
[
    {
        "properties": {
            "headline": "Test_Headline",
            "brandLogo": {
                "assetId": "{{assetId}}",
                "assetVersion": "{{versionId}}",
                "croppingCoordinates": {
                    "top": 0,
                    "left": 0,
                    "width": 600,
                    "height": 100
                }
            }
        },
        "creativeId": 1234567890111213
    }
]

このリクエストのレスポンスは、以下を返します。

[
    {
        "code": "SUCCESS",
        "creativeId": 1234567890111213
    }
]

手順3

この呼び出しを使用して、新しく追加したロゴやヘッドラインなど、新しいカスタムクリエイティブの画像を生成するために使用するHTMLをプレビューできます。

POST /sd/creatives/preview
{
    "creative": {
        "properties": {
            "headline": "Test Headline (input custom headline)",
            "brandLogo": {
                "assetId": "{{assetId}}",
                "assetVersion": "{{versionId}}",
                "croppingCoordinates": {
                    "top": 0,
                    "left": 0,
                    "width": 600,
                    "height": 100

                }
            }
        }
    },
    "previewConfiguration": {
        "size": {
            "width": 300,
            "height": 250
        },
        "products": [
            {
                "asin": "B08KWGHYQH"
            }
        ],
        "isMobile": false,
        "isOnAmazon": true
    }
}

このリクエストのレスポンスは、以下を返します。

{
    "previewHtml": "html string that you need to unescape"
}

カスタマイズせずにクリエイティブをプレビューする場合は、以下のペイロードを使用できます。"properties"も省略可能です。"creative": {}と指定することもできます。

POST /sd/creatives/preview
{
    "creative": {
        "properties": {}
    },
    "previewConfiguration": {
        "size": {
            "width": 300,
            "height": 250
        },
        "products": [
            {
                "asin": "B08KWGHYQH"
            }
        ],
        "isMobile": false,
        "isOnAmazon": true
    }
}

カスタマイズせずにクリエイティブをプレビューする場合は、以下のペイロードを使用できます。

このリクエストのレスポンスは、以下を返します。

{
    "previewHtml": "html string that you need to unescape without customization"
}

プレビュー設定でsize、isMobile、isOnAmazonを指定する場合は、クリエイティブのプレビューで次の値を使用できることに留意してください。 （「IsMobile」と「IsOnAmazon」の列の値はすべて小文字でなければなりません）。

サイズ（幅x高さ） isMobile isOnAmazon
245x250 FALSE TRUE
650x130 FALSE TRUE
414x125 TRUE TRUE
320x50 FALSE TRUE
160x600 FALSE TRUE
300x250 FALSE TRUE
728x90 FALSE TRUE
970x250 FALSE TRUE
300x600 FALSE TRUE
980x55 FALSE TRUE
300x600 FALSE TRUE
270x150 未定 未定

プレビューのクリエイティブAPIのレスポンスでは、エスケープされたHTMLが返されます。HTMLのエスケープを取り除き、ファイル（例：PreviewCreative.html）に保存する必要があります。iframeを使用してクリエイティブと同じサイズの別のHTMLファイルを作成する必要があります。その後、ブラウザーでiframe HTMLを開くと、クリエイティブが表示されます。

サイズが414x125のiframeファイルコードの例：

<html>
<body>
<iframe src="./PreviewCreative.html" style="border:none; position:absolute;"  width="414px" height="125px" />
</body>
</html>

この呼び出しを使用して、各adGroupIdのクリエイティブのリストを取得できます。これには、そのadGroupIdに関連付けられているカスタマイズされた見出しとassetIdが含まれます。

GET sd/creatives?adGroupIdFilter={{adGroupId}}

たとえば、このリクエストからのレスポンスは、以下を返します。

[
    {
        "creativeId": 1234567890111213,
        "properties": {
            "headline": "Raptors 2019 Champions",
            "brandLogo": {
                "assetId": "amzn1.assetlibrary.asset1.becf0adee0b0dc4e8ab96xxxxxxx",
                "assetVersion": "version_v1",
                "croppingCoordinates": {
                    "top": 0,
                    "left": 0,
                    "width": 600,
                    "height": 100
                }
            }
        },
        "moderationStatus": "PENDING_REVIEW"
    }
]

手順5

この呼び出しを使用すると、CreativeIdFilterを使用して、指定したcreativeIdのmoderationStatusを取得できます。

GET sd/moderation/creatives?creativeIdFilter={{creativeId}}&language=en_U

たとえば、このリクエストからのレスポンスは、以下を返します。 「contentType」には「CUSTOM_IMAGE」も指定できることに留意してください。

 [
    {
        "creativeId": 1234567890111213,
        "moderationStatus": "PENDING_REVIEW",
        "policyViolations": []
        "contentType": "HL"
    }
]

そのほかの知っておきたいこと

プロダクト広告

キャンペーンでプロダクト広告を作成するときは、有効で入手可能なASIN/SKUを必ず使用してください。無効なASIN/SKUではクリエイティブをレンダリングできません。

TPSの制限事項

現在、クリエイティブAPIでは、POST、GET、PUTリクエストに許可されるTPSは1のみです。これより多いTPSは制限されます。

見出し

ロゴまたはカスタム画像

アセットを登録する際、適切な値を指定して、以下の検証基準が満たされていることを確認できます。

Amazon Advertising logo