创意素材 API 开发人员指南

展示型推广使广告主能够为其广告活动上传视频、自定义标题、徽标或自定义图片，以便在投放广告时使用。广告主可以使用标题、徽标或自定义图片来强化其品牌形象，并突显推广的商品的体验。

在这一版本中，我们提供了一个创意素材 API，让您能够上传类似的标题、徽标和自定义图片，并将该创意素材与不同的广告组关联。在使用该 API 之前，您需要在“创意素材”中添加徽标或自定义图片。如果您已经上传了图片并且知道素材编号，则可以跳过此步骤并前往“创意素材 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"
        }
    }
]

实体编号将基于 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 使用 Postman 请求 URL 字段中的 upload_url 变量自动填充。该 URL 通常在 15 分钟后过期，因此如果 URL 已过期，则需要重新获取。

第 2 步

选择“二进制”选项，然后选择一个文件作为有效负载，通过 Postman 上传您希望用作徽标的图片。文件名必须与我们在上一步中指定的文件名完全匹配。*素材图片的高度不应小于 100 像素，宽度不应小于 600 像素，且图片的大小不应超过 1MB。*图片可以采用 png、jpg、jpeg 格式。

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

第 3 步

在请求体中，您可以指定以下字段的值：

• 变量 entity_id 提取自准备步骤 (Step 0) ，文件名和 upload_url 提取自第 1 步。
• assetType 必须是为 IMAGE，且 assetSubTypeList 必须包含单个值，即 LOGO/PRODUCT_IMAGE/AUTHOR_IMAGE/LIFESTYLE_IMAGE/OTHER_IMAGE 中的一个。
• 您可以添加任意标签以启用素材搜索。
• 账户字段允许您指定一个或多个将使用素材的实体编号 (entityId)。如果您希望稍后将该图片用于其他实体编号，只需再次上传徽标图片，然后使用新的实体编号注册素材，不要添加以前已使用过的实体编号。在来自 Postman 集合的请求中，它将使用您在获取配置文件信息的准备步骤 (Step 0) 中的实体。

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

此请求的响应返回以下内容：

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

或者，您可以使用以下其中一种方法来搜索素材：

• 检索素材与元数据：根据素材编号 (assetId) 返回素材详细信息。
• 搜索素材：根据搜索条件返回一个或多个素材

创意素材 API

创意素材 API 让您能够使用标题、徽标或自定义图片创建创意素材，其中徽标和自定义图片是使用上一节中创建的素材编号 (assetId) 进行引用的。

在调用创意素材 API 之前，请确保您已创建广告活动、广告组、产品广告、投放内容。在创建产品广告时，请确保您使用的 ASIN/SKU 有效且可供使用。您需要确保有新的广告组编号 (adGroupId) 可用，以通过执行以下步骤来向广告组添加创意素材。

展开 sd → creatives 文件夹以查看请求。

第 1 步

您将使用从创意素材 API 的第 3 步中获得的素材编号 (assetId) 和版本编号 (versionId)。Postman 脚本根据上一节中请求的执行情况将这两个值以变量形式提供。素材图片高度不应小于 100 像素，宽度不应小于 600 像素。

在亚马逊广告 API 中创建 brandLogo 的示例

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,
    }
]

在亚马逊广告 API 中创建 customImage 的示例

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
728 x 90	FALSE	TRUE
970x250	FALSE	TRUE
300x600	FALSE	TRUE
980x55	FALSE	TRUE
300x600	FALSE	TRUE
270x150	TBD	TBD

您将在创意素材 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"
    }
]

其他注意事项

产品广告 (ProductAd)

在广告活动中创建产品广告时，请确保使用有效且可用的 ASIN/SKU。使用无效的 ASIN/SKU 将无法呈现创意素材。

TPS 限制

目前，对于创意 API，亚马逊仅允许分别对 POST、GET 和 PUT 请求使用 1 TPS。更高的 TPS 将受到限制。

标题

• 不能为空字符串
• 长度不能超过 50 个字符
• 不能包含非法字符：< > # ^ ! ...
• 大写字符不能超过 50%，但如果标题长度在 10 个字符以内，则无法启用此验证
• 不能包含表情符号，例如 \uD83D \uDE41

徽标或自定义图片

注册素材时，您可以指定适当的值来确保满足以下验证条件：

• 素材图片高度不应小于 628 像素，宽度不应小于 1200 像素
  • assetType 应为 IMAGE
  • assetStatus 应为 ACTIVE
  • assetContentType 应为以下值之一：
    • "jpeg",
    • "jpg",
    • "png",
    • "gif",
    • "image/jpeg",
    • "image/jpg",
    • "image/png",
    • "image/gif"
  • assetExtension 应为以下值之一：
    • "JPEG",
    • "JPG",
    • "PNG",
    • "GIF"
  • assetFileSize 不应大于 5MB
  • 裁剪坐标的裁剪位置不应超出图片（如果您在“创意素材”中上传的图片的宽度只有 1200 像素，请勿将其裁剪为 1300 像素）
  • 对于方形自定义图片，裁剪坐标不应小于 628x628 像素。