广告组关键词

警告

这些接口将于 2023 年 6 月 30 日弃用。请在此日期之后使用商品推广（版本 3）关键词。如果您希望了解更多信息，请参阅“功能弃用”页面。

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

方法	URL	用例
GET	`/keywords/{keywordId}`	按 ID 检索广告组级别的可竞价关键词
GET	`/keywords/extended/{keywordId}`	按 ID 检索广告组级别的可竞价关键词以及其他属性
POST	`/keywords`	创建一个或多个广告组级别的可竞价关键词
PUT	`/keywords`	更新一个或多个广告组级别的可竞价关键词
DELETE	`/keywords/{keywordId}`	将单个广告组级别的可竞价关键词存档。存档的实体无法再启用。如果您希望了解更多信息，请参阅开发人员备注。
GET	`/keywords?startIndex={startIndex}&count={count}&campaignType={campaignType}&matchTypeFilter={matchTypeFilter}&keywordText={keywordText}&state={stateFilter}&campaignIdFilter={campaignIdFilter}&adGroupIdFilter={adGroupIdFilter}`	根据指定条件返回广告组级别的可竞价关键词列表
GET	`/keywords/extended?startIndex={startIndex}&count={count}&campaignType={campaignType}&matchTypeFilter={matchTypeFilter}&keywordText={keywordText}&state={stateFilter}&campaignIdFilter={campaignIdFilter}&adGroupIdFilter={adGroupIdFilter}`	根据指定条件返回广告组级别的可竞价关键词列表，其中包含更多属性

操作

getBiddableKeyword

GET /keywords/{keywordId}

按 ID 检索关键词。请注意，此调用将返回关键词字段的最小集合，但比 getBiddableKeywordEx 更有效。

参数

参数名称	类型	描述
`keywordId`	string	请求的关键词编号

响应

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

getBiddableKeywordEx

GET /keywords/extended/{keywordId}

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

参数

参数名称	类型	指定位置	描述
`keywordId`	string	URL 路径	请求的关键词编号

响应

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

createBiddableKeywords

POST /keywords

创建一个或多个关键词。成功创建的关键词将获得分配的唯一 keywordId。

参数

类型	指定位置	描述
`Keyword`列表	body（体）	可创建多达 1000 个关键词的列表。创建关键词时的必填字段包括：`campaignId`、`adGroupId`、`keywordText`、`matchType` 和 `state`

响应

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

updateBiddableKeywords

PUT /keywords

更新一个或多个关键词。关键词需使用 keywordId 进行识别。

参数

类型	指定位置	描述
`Keyword`列表	body（体）	包含多达 1000 项更新的列表，其中包含了 `keywordId` 和要修改的可变字段。可变字段包括：`state` 和 `bid`。

响应

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

archiveBiddableKeyword

DELETE /keywords/{keywordId}

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

参数

参数名称	类型	指定位置	描述
`keywordId`	string	URL 路径	要存档的`keyword`的编号。

响应

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

listBiddableKeywords

GET /keywords/                       
  ?startIndex={startIndex}              
  &count={count}
  &campaignType={campaignType}          
  &matchTypeFilter={matchTypeFilter}    
  &keywordText={keywordText}            
  &stateFilter={stateFilter}            
  &campaignIdFilter={campaignIdFilter}  
  &adGroupIdFilter={adGroupIdFilter}
  &keywordIdFilter={keywordIdFilter}

检索满足可选条件的关键词列表。

参数

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

响应

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

listBiddableKeywordsEx

GET /keywords/extended                       
  ?startIndex={startIndex}              
  &count={count}
  &campaignType={campaignType}          
  &matchTypeFilter={matchTypeFilter}    
  &keywordText={keywordText}            
  &stateFilter={stateFilter}            
  &campaignIdFilter={campaignIdFilter}  
  &adGroupIdFilter={adGroupIdFilter}
  &keywordIdFilter={keywordIdFilter}

检索满足可选条件且包含扩展字段的关键词列表。

参数

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

响应

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

资源表现

Keyword（关键词）

{
    "title": "Keyword",
    "type": "object",
    "properties": {
       "keywordId": {
           "description": "The ID of the keyword",
           "type": "number"
       },
       "campaignId": {
           "description": "The ID of the campaign to which this keyword belongs",
           "type": "number"
       },
       "adGroupId": {
           "description": "The ID of the campaign to which this keyword belongs.Specified for ad group-level keywords",
           "type": "number"
       },
       "state": {
           "description": "Advertiser-specified state of the keyword",
           "type": "string",
           "oneOf": ["enabled", "paused", "archived"]
       },
       "keywordText": {
           "description": "The expression to match against search queries",
           "type": "string"
       },
       "matchType": {
           "description": "The match type used to match the keyword to search query",
           "type": "string",
           "oneOf": ["exact", "phrase", "broad"]
       },
       "bid": {
           "description": "Bid used when ads are sourced using this keyword.Only compatible with biddable match types.",
           "type": "number",
           "minimum": 0.02
       }
   }
}

KeywordEx

{
    "title": "KeywordEx",
    "type": "object",
    "properties": {
       "keywordId": {
           "description": "The ID of the keyword",
           "type": "number"
       },
       "campaignId": {
           "description": "The ID of the campaign to which this keyword belongs",
           "type": "number"
       },
       "adGroupId": {
           "description": "The ID of the ad group to which this keyword belongs. ",
           "type": "number"
       },
       "state": {
           "description": "Advertiser-specified state of the keyword",
           "type": "string",
           "oneOf": ["enabled", "paused", "archived"]
       },
       "keywordText": {
           "description": "The expression to match against search queries",
           "type": "string"
       },
       "matchType": {
           "description": "The match type used to match the keyword to search query",
           "type": "string",
           "oneOf": ["exact", "phrase", "broad"]
       },
       "bid": {
           "description": "Bid used when ads are sourced using this keyword",
           "type": "number",
           "minimum": 0.02           
       },
       "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": ["TARGETING_CLAUSE_ARCHIVED", "TARGETING_CLAUSE_PAUSED", "TARGETING_CLAUSE_STATUS_LIVE", "TARGETING_CLAUSE_POLICING_SUSPENDED", "CAMPAIGN_OUT_OF_BUDGET", "AD_GROUP_PAUSED", "AD_GROUP_ARCHIVED", "CAMPAIGN_PAUSED", "CAMPAIGN_ARCHIVED", "ACCOUNT_OUT_OF_BUDGET"]
       }
   }
}

KeywordResponse

{
    "title": "KeywordResponse",
    "type": "object",
    "properties": {
       "keywordId": {
           "description": "The ID of the keyword 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 概览