广告组

警告

这些接口将于 2023 年 6 月 30 日弃用。请在此日期之后使用商品推广（版本 3）广告组。如需进一步了解，请参阅“功能弃用”页面。

用于创建、读取、更新或删除广告组。下表说明了有关 URL 空间和支持的 HTTP 方法的服务行为，它们由服务管理资源提供支持。

方法	URL	适用场景
GET	`/adGroups/{adGroupId}`	按 ID 检索广告组
GET	`/adGroups/extended/{adGroupId}`	按 ID 检索广告组以及其他属性
POST	`/adGroups`	创建一个或多个广告组
PUT	`/adGroups`	更新一个或多个广告组
删除	`/adGroups/{adGroupId}`	存档单个广告组。存档的实体无法再启用。如需进一步了解，请参阅开发人员备注。
GET	`/adGroups?startIndex={startIndex}&count={count}&campaignType={campaignType}&stateFilter={stateFilter}&campaignIdFilter={campaignIdFilter}&adGroupIdFilter={adGroupIdFilter}&name={name}`	根据指定条件返回广告组列表
GET	`/adGroups/extended?startIndex={startIndex}&count={count}&campaignType={campaignType}&stateFilter={stateFilter}&campaignIdFilter={campaignIdFilter}&adGroupIdFilter={adGroupIdFilter}&name={name}`	根据指定条件返回广告组列表，其中包含更多属性

操作

getAdGroup

GET /adGroups/{adGroupId}

OriginalPhrasev1

按 ID 检索广告组。请注意，此调用将返回广告组字段的最小集合，但比 getAdGroupEx 更高效。

参数

参数名称	类型	说明
`adGroupId`	string	请求的广告组的 ID

响应

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

getAdGroupEx

GET /adGroups/extended/{adGroupId}

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

参数

参数名称	类型	指定位置	说明
`adGroupId`	string	URL 路径	请求的广告组的 ID

响应

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

createAdGroups

POST /adGroups

创建一个或多个广告组。成功创建的广告组将获得一个唯一的 adGroupId。

参数

类型	指定位置	说明
`广告组`的列表	体（body）	最多可创建 100 个广告组的列表。创建广告组的必填字段为：`campaignId`、`name`、`state` 和 `defaultBid`

响应

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

updateAdGroups

PUT /adGroups

更新一个或多个广告组。广告组使用其 adGroupId 进行识别。

参数

类型	指定位置	说明
`广告组`的列表	体（body）	包含最多 100 个更新的列表，其中包含 `adGroupId` 和要修改的可变字段。可变字段包括：`name`、 `defaultBid` 和状态 `state`

响应

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

archiveAdGroup

DELETE /adGroups/{adGroupId}

将广告组状态设置为 archived（已存档）。同样的操作可通过更新来执行，但为了完整起见，应包括在内。已存档实体（entity）无法再启用。如需进一步了解，请参阅开发人员备注。

参数

参数名称	类型	指定位置	说明
`adGroupId`	`string`	URL 路径	要存档的广告组的 ID。

响应

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

listAdGroups

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

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

参数

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

响应

状态代码	响应对象
`200 - success`	`广告组`的列表
`401 - unauthorized`	`Error`

listAdGroupsEx

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

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

参数

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

响应

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

资源表示（resource representation）

广告组

{
    "title": "AdGroup",
    "type": "object",
    "properties": {
       "adGroupId": {
           "description": "The ID of the ad group",
           "type": "number"
       },
       "name": {
           "description": "The name of the ad group",
           "type": "string"
       },
       "campaignId": {
           "description": "The ID of the campaign to which this ad group belongs",
           "type": "number"
       },
       "defaultBid": {
           "description": "The bid used when keywords belonging to this ad group don't specify a bid",
           "type": "number",
           "minimum": 0.02
       },
       "state": {
           "description": "Advertiser-specified state of the ad group",
           "type": "string",
           "oneOf": ["enabled", "paused", "archived"]
       }
   }
}

AdGroupEx

{
    "title": "AdGroupEx",
    "type": "object",
    "properties": {
       "adGroupId": {
           "description": "The ID of the ad group",
           "type": "number"
       },
       "name": {
           "description": "The name of the ad group",
           "type": "string"
       },
       "campaignId": {
           "description": "The ID of the campaign to which this ad group belongs",
           "type": "number"
       },
       "defaultBid": {
           "description": "The bid used when keywords belonging to this ad group don't specify a bid",
           "type": "number",
           "minimum": 0.02     
       },
       "state": {
           "description": "Advertiser-specified state of the ad group",
           "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_GROUP_ARCHIVED", "AD_GROUP_PAUSED", "AD_GROUP_STATUS_ENABLED", "AD_POLICING_SUSPENDED", "CAMPAIGN_OUT_OF_BUDGET", "CAMPAIGN_PAUSED", "CAMPAIGN_ARCHIVED", "CAMPAIGN_INCOMPLETE", "ACCOUNT_OUT_OF_BUDGET"]
       }
   }
}

AdGroupResponse

{
    "title": "AdGroupResponse",
    "type": "object",
    "properties": {
       "adGroupId": {
           "description": "The ID of the ad group 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 概览

广告组

警告

操作