開発者ガイドの概要

Amazon Ads APIの概要

アセットの作成

アセットライブラリは現在、動画と画像のクリエイティブに対応しています。

クリエイティブの種類にかかわらず、以下3つの呼び出しを行う必要があります。

  1. アセットのアップロードURLを生成する。
  2. 指定されたURLにアセットをアップロードする。
  3. アセットを登録する。

手順

手順1： アップロードURLを作成する

POST /assets/uploadを使用してアップロードURLを取得します。アップロードするアセットの正しいファイル名とサポートされているディメンションを使用していることを確認してください。サポートされていない拡張子を使用した場合、この手順ではエラーになりませんが、後でエラーが発生します。

例： 画像

curl --location --request POST 'https://advertising-api.amazon.com/assets/upload' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxx' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "filename": "logo.png"
}
'

レスポンスに、手順2でファイルをアップロードするために使用可能なカスタムURLが含まれます。

{
 "url": "https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxxxxxxx"
 }

例： 動画

curl --location --request POST 'https://advertising-api.amazon.com/assets/upload' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxx' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "filename": "product_video.mov"
}
'

{
 "url": "https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxxx"
}

手順2： アセットをアップロードする

アセットをアップロードするには、手順1で返されたURLに対してPUTを使用します。

警告

アセットのタイプに基づいて、正しいContent-Typeを渡すようにしてください。

例： 画像

curl --location -g --request PUT 'https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxxxxxxx' \
--header 'Content-Type: image/png' \
--data-binary '@/Users/xxxxxx/desktop/logo.png'

例： 動画

curl --location --request PUT 'https://al-na-9d5791cf-3faf.s3.amazonaws.com/xxxxxxxx' \
--header 'Content-Type: video/quicktime' \
--data-binary '@/Users/xxxxxxxxxx/Downloads/brand_video.mov'

アセットが正しくアップロードされると、レスポンス200が返されます。

手順3： アセットを登録する

POST /assets/registerを使用してアセットを登録します。

パラメーター

| パラメーター | 必須？ | 説明 | |--- |--- |--- | | url | はい | 手順1で生成したアセットのアップロードURL。 | | name | はい | アセットの名前。 | | asinList | いいえ | 検索や分類に使用する、アセットに関連するASINのリスト（省略可）。 | | assetType | はい | アセットのタイプ。現在、「IMAGE」（画像）と「VIDEO」（動画）を指定可能です。 | | assetSubTypeList | はい | アセットのサブタイプ。 | | versionInfo | いいえ | 既存のアセットの新しいバージョンをアップロードする場合は、versionInfoにアセットIDを指定します。 | | tags | いいえ | 検索や分類に使用する、関連するタグをアセットに追加するためのパラメーター（省略可）。 | | registrationContext | はい、DSPアセット用 | DSPキャンペーンで使用するアセットの場合のみ、必須となります。アセットをスポンサー広告またはストアに使用する場合、このパラメーターを含める必要はありません。 | | associatedSubEntityList | はい、 Amazonの出品者様用 | Amazonの出品者様はブランドのエンティティIDを指定する必要があります。これはGET /brandsエンドポイントを使用して確認できます。他の広告主様には、ブランドのエンティティIDを指定することをおすすめしますが、必須ではありません。 | | skipAssetSubTypesDetection | いいえ | デフォルトでは、システムが自動的に画像をサブタイプに分類しようとします。システムにこの分類を実行させない場合は、これをTRUEに設定してください。 |

例： 画像

curl --location --request POST 'https://advertising-api.amazon.com/assets/register' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "url": "https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxx",
  "name": "logo",
  "asinList": [
    "B07XXXXXX1",
    "B07XXXXXX2",
    "B07XXXXXX3"
  ],
  "assetType": "IMAGE",
  "assetSubTypeList": [
    "LOGO"
  ],
  "associatedSubEntityList": [
    {
      "brandEntityId": "ENTITYXXXXXXXXXX"
    }
  ]
}

'

レスポンスでは、キャンペーンの作成または編集に使用可能なassetIdを含む200が返されます。

{
 "assetId": "amzn1.assetlibrary.asset1.xxxxx",
 "failedSpecChecks": [],
 "programPolicyValidationsList": null,
 "versionId": "version_v1"
}

注

アセットライブラリでは、画像の適性検査は実行されません。審査プロセスを最適化するために、キャンペーンと画像のタイプごとに設定されている要件に必ず従ってください。

例： 動画

curl --location --request POST 'https://advertising-api.amazon.com/assets/register' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--data-raw '{
  "url": "https://al-na-9d5791cf-3faf.s3.amazonaws.com/xxxxxxxxx",
  "name": "SB video asset",
  "asinList": [
    "B0XXXXXX1",
    "B0XXXXXX2",
    "B0XXXXXX3"
  ],
  "assetType": "VIDEO",
  "assetSubTypeList": [
    "BACKGROUND_VIDEO"
  ],
  "associatedSubEntityList": [
    {
      "brandEntityId": "ENTITYXXXXXXXXXX"
    }
  ]
}
'

成功すると、キャンペーンの管理に使用可能なassetIdを含む200が返されます。レスポンスでは、動画アセットの検証チェックに失敗したプログラムタイプのリストが返されます。

この例では、登録された動画アセットはDSP OLV、DSP OTT、またはストアのイントロスプラッシュには利用できません。この動画はスポンサーブランド広告キャンペーン用ですが、FailedSpecChecksには、スポンサーブランド広告についての記載がないことがわかります。

注

クリエイティブアセットライブラリの処理は、審査プロセスの一部ではありません。広告プログラムのクリエイティブポリシーに違反しているために、クリエイティブが表示されない場合があります。クリエイティブの新しいバージョンをアップロードする必要がある場合は、アセットの管理をご覧ください。

{
    "assetId": "amzn1.assetlibrary.asset1.xxxxxxxxxxx",
    "failedSpecChecks": [
        {
            "Program": "AMAZON_DSP",
            "specProgramName": "DEMAND_SIDE_PLATFORM_OLV",
            "specifications": [
                {
                    "actualValue": "30.0",
                    "arguments": [
                        "23.98",
                        "24.0",
                        "25.0",
                        "29.97"
                    ],
                    "failureReason": "Frame rate is not one of 23.98, 24.0, 25.0, 29.97.",
                    "isPassed": false,
                    "stringId": "al-spec-video-frame-rate"
                },
                {
                    "actualValue": "0",
                    "arguments": [
                        "2"
                    ],
                    "failureReason": "Total number of audio channels across all audio streams is less than 2.",
                    "isPassed": false,
                    "stringId": "al-spec-min-audio-channel-count"
                }
            ]
        },
        {
            "Program": "AMAZON_DSP",
            "specProgramName": "DEMAND_SIDE_PLATFORM_OTT",
            "specifications": [
                {
                    "actualValue": "30.0",
                    "arguments": [
                        "23.98",
                        "24.0",
                        "25.0",
                        "29.97"
                    ],
                    "failureReason": "Frame rate is not one of 23.98, 24.0, 25.0, 29.97.",
                    "isPassed": false,
                    "stringId": "al-spec-video-frame-rate"
                },
                {
                    "actualValue": "9.966667",
                    "arguments": [
                        "15.0",
                        "30.0"
                    ],
                    "failureReason": "Duration is not one of 15.0, 30.0 seconds.",
                    "isPassed": false,
                    "stringId": "al-spec-video-duration"
                },
                {
                    "actualValue": "0",
                    "arguments": [
                        "2"
                    ],
                    "failureReason": "Total number of audio channels across all audio streams is less than 2.",
                    "isPassed": false,
                    "stringId": "al-spec-min-audio-channel-count"
                }
            ]
        },
        {
            "Program": "STORES",
            "specProgramName": "STORES_INTRO_SPLASH",
            "specifications": [
                {
                    "actualValue": "16:9",
                    "arguments": [
                        "9:16"
                    ],
                    "failureReason": "Aspect ratio is not 9:16.",
                    "isPassed": false,
                    "stringId": "al-spec-video-aspect-ratio"
                }
            ]
        }
    ],
    "programPolicyValidationsList": null,
    "versionId": "version_v1"
}

次のステップ

アセットを登録すると、そのアセットはPROCESSINGステータスに設定されます。アセットがACTIVEステータスになったら、キャンペーンで使用できます。

ヒント

アップロードするファイルのサイズによっては、アセットがPROCESSINGステータスのまま最大30分間変わらないことがあります。キャンペーンでアセットを使用する前に、GET /assets エンドポイントをポーリングして、ステータスがACTIVEに設定されていることをご確認ください。処理期間には動画のトランスコード処理が含まれるため、動画アセットは一般に、PROCESSINGステータスが長くなります。トランスコード処理が失敗すると、アセットのステータスは INACTIVEに変わります。

アセットの検証に失敗した場合は、修正を加えて新しいバージョンのアセットをアップロードできます。詳しくは、アセットの管理をご覧ください。

Amazon Advertising logo