产品广告

警告

这些接口将于 2023 年 6 月 30 日弃用。请在此日期之后使用商品推广（版本 3）产品广告。有关更多信息，请参阅“功能弃用”页面。

用于为商品推广创建、读取、更新或删除产品广告。下表描述了有关 URL 空间和支持的 HTTP 方法的服务行为，这些行为由服务管理资源提供支持。

方法	URL	使用案例
GET	`/productAds/{adId}`	按编号检索产品广告
GET	`/productAds/extended/{adId}`	按编号检索产品广告以及其他属性
POST	`/productAds`	创建一个或多个产品广告
PUT	`/productAds`	更新一个或多个产品广告
DELETE	`/productAds/{adId}`	存档单个产品广告。存档的实体无法再启用。有关更多信息，请参阅开发人员备注。
GET	`/productAds?startIndex={startIndex}&count={count}&campaignType={campaignType}&adGroupId={adGroupId}&sku={sku}&asin={asin}&stateFilter={stateFilter}&campaignIdFilter={campaignIdFilter}&adGroupIdFilter={adGroupIdFilter}`	根据指定条件返回产品广告列表
GET	/productAds/extended?startIndex={startIndex}&count={count}&campaignType={campaignType}&adGroupId={adGroupId}&sku={sku}&asin={asin}&stateFilter={stateFilter}&campaignIdFilter={campaignIdFilter}&adGroupIdFilter={adGroupIdFilter}	根据指定条件返回产品广告列表，其中包含更多属性

操作

getProductAd

GET /productAds/{adId}

按编号检索产品广告。请注意，此调用将返回产品广告字段的最小集合，但比 getProductAdEx更高效。

参数

参数名称	类型	描述
`adId`	string	请求的产品广告的编号

响应

状态码	响应对象
`200 - success`	ProductAdEx
`401 - unauthorized`	错误
`404 - ad not found`	错误

getProductAdEx

GET /productAds/extended/{adId}

按编号检索产品广告及其扩展字段。请注意，此调用将返回完整的产品广告字段集合（包括服务状态和其他只读字段），但效率不及 getProductAd。

参数

参数名称	类型	指定位置	描述
`adId`	string	URL 路径	请求的产品广告的编号

响应

状态码	响应对象
`200 - success`	`ProductAd`
`401 - unauthorized`	`Error`
`404 - ad not found`	`Error`

createProductAds

POST /productAds

创建一个或多个产品广告。成功创建的产品广告将获得分配的唯一 adId。

参数

类型	指定位置	描述
`ProductAd`的列表	体	最多可创建 1000 个产品广告的列表。创建产品广告所需的必填字段为：`campaignId`、`adGroupId`、`SKU` 和 `state`

响应

状态码	响应对象
`207 multi-status`	`AdResponse` 列表反应与输入顺序相同
`401 - unauthorized`	`Error`

updateProductAds

PUT /productAds

更新一个或多个产品广告。产品广告使用其 adId 进行标识。

参数

类型	指定位置	描述
`ProductAd`的列表	体	包含最多 1000 个更新的列表，其中包含 `adId` 和要修改的可变字段。可变字段：`state`。

响应

状态码	响应对象
`207 – multi-status`	`AdResponse` 列表反应与输入顺序相同
`401 - unauthorized`	`Error`

archiveProductAd

DELETE /productAds/{adId}

将产品广告状态设置为 archived。同样的操作可通过更新来执行，但为了完整起见，应包括在内。已存档实体无法再启用。有关更多信息，请参阅开发人员备注信息。

参数

参数名称	类型	指定位置	描述
`adId`	string	URL 路径	要存档的产品广告的编号。

响应

状态码	响应对象
`200 - success`	`AdResponse`
`401 - unauthorized`	`Error`
`404 - ad not found`	`Error`

listProductAds

GET /productAds/                                                           
  ?startIndex={startIndex}              
  &count={count}                        
  &campaignType={campaignType}                                   
  &stateFilter={stateFilter}            
  &campaignIdFilter={campaignIdFilter}  
  &adGroupIdFilter={adGroupIdFilter}

检索满足可选条件的产品广告列表。

参数

参数名称	类型	指定位置	描述
`startIndex`	integer	URL 查询	可选。结果集的 0 索引记录偏移量。默认为 0。
`count`	integer	URL 查询	可选。分页响应中要包含的记录数。默认为最大页面大小。
`campaignType`	string	URL 查询	可选。将结果限制为属于指定类型的广告活动的广告。必须为：`sponsoredProducts`

`adGroupId`	string	URL 查询	可选。将结果限制为包含指定 `adGroupId` 的产品广告。
`stateFilter`	string	URL 查询	可选。将结果限制为指定逗号分隔列表中包含状态的广告。必须是以下值之一：`enabled`、`paused`、`archived`。默认行为是设置为“全部包括”。
`campaignIdFilter`	string	URL 查询	可选。将结果限制为逗号分隔列表中指定的广告活动包含的广告。
`adGroupIdFilter`	string	URL 查询	可选。将结果限制为逗号分隔列表中指定的广告组包含的广告。
`adIdFilter`	string	URL 查询	可选。将结果限制为包含逗号分隔列表中指定的产品`广告编号`的广告。

响应

状态码	响应对象
`200 - success`	`ProductAd`的列表
`401 - unauthorized`	`Error`

listProductAdsEx

  GET /adGroups/extended               
    ?startIndex={startIndex}              
    &count={count}                        
    &campaignType={campaignType}
    &adGroupId={adGroupId}          
    &stateFilter={stateFilter}            
    &campaignIdFilter={campaignIdFilter}  
    &adGroupIdFilter={adGroupIdFilter}

检索满足可选筛选条件且包含扩展字段的产品广告列表。

参数

参数名称	类型	指定位置	描述
`startIndex`	integer	URL 查询	可选。结果集的 0 索引记录偏移量。默认为 0。
`count`	integer	URL 查询	可选。分页响应中要包含的记录数。默认为最大页面大小。
`campaignType`	string	URL 查询	可选。将结果限制为属于指定类型的广告活动的广告。必须为：`sponsoredProducts`
`adGroupId`	string	URL 查询	可选。将结果限制为包含指定 `adGroupId` 的产品广告。
`stateFilter`	string	URL 查询	可选。将结果限制为指定逗号分隔列表中包含状态的广告。必须是以下值之一：`enabled`、`paused`、`archived`。默认行为是设置为“全部包括”。
`campaignIdFilter`	string	URL 查询	可选。将结果限制为逗号分隔列表中指定的广告活动包含的广告。
`adGroupIdFilter`	string	URL 查询	可选。将结果限制为逗号分隔列表中指定的广告组包含的广告。
`adIdFilter`	string	URL 查询	可选。将结果限制为包含逗号分隔列表中指定的产品广告编号的广告。

响应

状态码	响应对象
`200 - success`	`ProductAdEx` 的列表
`401 - unauthorized`	`Error`

资源表现

ProductAd

{
    "title": "ProductAd",
    "type": "object",
    "properties": {
       "adId": {
           "description": "The ID of the product ad",
           "type": "number"
       },
       "campaignId": {
           "description": "The ID of the campaign to which this product ad belongs",
           "type": "number"
       },
       "adGroupId": {
           "description": "The ID of the ad group to which this product ad belongs",
           "type": "number"
       },      
       "sku": {
           "description": "The SKU for the listed product to be advertised.Either this or the asin must be present.",
           "type": "string"
       },    
       "asin": {
           "description": "The ASIN for the listed product to be advertised",
           "type": "string"
       },       
       "state": {
           "description": "Advertiser-specified state of the product ad",
           "type": "string",
           "oneOf": ["enabled", "paused", "archived"]
       }
    }
}

ProductAdEx

{
    "title": "ProductAdEx",
    "type": "object",
    "properties": {
       "adId": {
           "description": "The ID of the product ad",
           "type": "number"
       },
       "campaignId": {
           "description": "The ID of the campaign to which this product ad belongs",
           "type": "number"
       },
       "adGroupId": {
           "description": "The ID of the ad group to which this product ad belongs",
           "type": "number"
       },
       "sku": {
           "description": "The SKU for the listed product to be advertised.Either this or the asin must be present.",
           "type": "string"
       },    
       "asin": {
           "description": "The ASIN for the listed product to be advertised",
           "type": "string"
       },       
       "state": {
           "description": "Advertiser-specified state of the product ad",
           "type": "string",
           "oneOf": ["enabled", "paused", "archived"]
       },
       "creationDate": {
           "description": "The date the ad group was created as epoch time in milliseconds",
           "type": "number"
       },
       "lastUpdatedDate": {
           "description": "The date the ad group was last updated as epoch time in milliseconds",
           "type": "number"
       },
       "servingStatus": {
           "description": "The computed status, accounting for out of budget, policy violations, etc.See developer notes for more information.",
           "type": "string",
           "oneOf": ["AD_ARCHIVED", "AD_PAUSED", "AD_STATUS_LIVE", "AD_POLICING_SUSPENDED", "CAMPAIGN_OUT_OF_BUDGET", "AD_GROUP_PAUSED", "AD_GROUP_ARCHIVED", "CAMPAIGN_PAUSED", "CAMPAIGN_ARCHIVED", "ACCOUNT_OUT_OF_BUDGET", "MISSING_DECORATION"]
       }
    }
}

广告响应

{
    "title": "AdResponse",
    "type": "object",
    "properties": {
       "adId": {
           "description": "The ID of the ad that was created/updated, if successful",
           "type": "number"
       },
       "code": {
           "description": "An enumerated success or error code for machine use.",
           "type": "string"
       },
       "details": {
           "description": "A human-readable description of the error, if unsuccessful",
           "type": "string"
       }
    }
}

开发人员指南概述

亚马逊广告 API 概览