広告グループのキーワード

警告

これらのエンドポイントは、2023年6月30日に廃止されます。今後は、スポンサープロダクト広告バージョン3のキーワードをご利用ください。詳細については、廃止予定のページをご覧ください。

広告グループレベルの入札可能なキーワードの作成、読み取り、更新、削除に使用されます。次の表は、サービスの管理対象リソースによってサポートされる、 URL空間とHTTPメソッドに関するサービスの動作を示しています。

メソッド	URL	ユースケース
GET	`/keywords/{keywordId}`	IDを指定して、広告グループレベルの入札可能なキーワードを取得します
GET	`/keywords/extended/{keywordId}`	IDを指定して、広告グループレベルの入札可能なキーワードとその他のプロパティを取得します
POST	`/keywords`	広告グループレベルの入札可能なキーワードを1つ以上作成します
PUT	`/keywords`	広告グループレベルの入札可能なキーワードを1つ以上更新します
DELETE	`/keywords/{keywordId}`	広告グループレベルの入札可能なキーワードを1つだけ非表示にします。非表示にされたエンティティを再度アクティブにすることはできません。詳細については、開発者メモをご覧ください。
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	リクエストされたキーワードのID

レスポンス

ステータスコード	レスポンスオブジェクト
`200 - success`	`Keyword`
`401 - unauthorized`	`Error`
`404 - keyword not found`	`Error`

getBiddableKeywordEx

GET /keywords/extended/{keywordId}

IDを指定して、キーワードとその拡張フィールドを取得します。この呼び出しは、キーワードフィールドをすべて（配信ステータスおよびその他の読み取り専用フィールドを含む）返しますが、getBiddableKeywordよりも非効率であることにご注意ください。

パラメーター

パラメーター名	タイプ	指定対象	説明
`keywordId`	string	URLパス	リクエストされたキーワードのID

レスポンス

ステータスコード	レスポンスオブジェクト
`200 - success`	`KeywordEx`
`401 - unauthorized`	`Error`
`404 - keyword not found`	`Error`

createBiddableKeywords

POST /keywords

1つ以上のキーワードを作成します。正常に作成されたキーワードには、固有のkeywordIdが割り当てられます。

パラメーター

タイプ	指定対象	説明
`Keyword`のリスト	本文	作成する最大1000個のキーワードのリスト。キーワードの作成に必要なフィールドは、`campaignId`、`adGroupId`、`keywordText`、`matchType`、`state`です。

レスポンス

ステータスコード	レスポンスオブジェクト
`207 - multi-status`	入力順に示される`KeywordResponse`のリスト
`401 - unauthorized`	`Error`

updateBiddableKeywords

PUT /keywords

1つ以上のキーワードを更新します。キーワードは、 keywordIdを使用して指定されます。

パラメーター

タイプ	指定対象	説明
`Keyword`のリスト	本文	`keywordId`および変更される変更可能フィールドを含む、更新項目最大1000件のリスト。変更可能フィールドは`state`と`bid`です。

レスポンス

ステータスコード	レスポンスオブジェクト
`207 – multi-status`	入力順に示される`KeywordResponse`のリスト
`401 - unauthorized`	`Error`

archiveBiddableKeyword

DELETE /keywords/{keywordId}

キーワードのステータスをarchivedに設定します。更新によってもこの同じ操作を実行できますが、完全を期すために含めています。非表示のエンティティを再度アクティブにすることはできません。詳細については、開発者メモをご覧ください。

パラメーター

パラメーター名	タイプ	指定対象	説明
`keywordId`	string	URLパス	非表示にする`keyword`のID。

レスポンス

ステータスコード	レスポンスオブジェクト
`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"
       }
    }
}

エラー

開発者メモで解説されているエラーオブジェクトの戻り値形式をご覧ください。

開発者ガイドの概要

Amazon Ads APIの概要

広告グループのキーワード

警告

操作

getBiddableKeyword

パラメーター

レスポンス

getBiddableKeywordEx

パラメーター

レスポンス

createBiddableKeywords

パラメーター

レスポンス

updateBiddableKeywords

パラメーター

レスポンス

archiveBiddableKeyword

パラメーター

レスポンス

listBiddableKeywords

パラメーター

レスポンス

listBiddableKeywordsEx

パラメーター

レスポンス

リソースの表現

Keyword

KeywordEx

KeywordResponse

エラー