広告グループ

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

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

メソッド	URL	ユースケース
GET	`/adGroups/{adGroupId}`	IDを指定して、広告グループを取得します
GET	`/adGroups/extended/{adGroupId}`	IDを指定して、広告グループおよびその他のプロパティを取得します
POST	`/adGroups`	広告グループを1件以上作成します
PUT	`/adGroups`	広告グループを1件以上更新します
DELETE	`/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

1つ以上の広告グループを作成します。正常に作成された広告グループには、固有のadGroupIdが割り当てられます。

パラメーター

タイプ	指定対象	説明
`AdGroup`のリスト	本文	作成される、最大100個の広告グループのリスト。広告グループの作成に必要なフィールドは、`campaignId`、`name`、`state`、`defaultBid`です。

レスポンス

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

updateAdGroups

PUT /adGroups

1つ以上の広告グループを更新します。広告グループは、 adGroupIdを使用して識別されます。

パラメーター

タイプ	指定対象	説明
`AdGroup`のリスト	本文	`adGroupId`および変更される変更可能フィールドを含む、最大100個の更新のリスト。変更可能なフィールドは、`name`、`defaultBid`、`state`です。

レスポンス

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

archiveAdGroup

DELETE /adGroups/{adGroupId}

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

パラメーター

パラメーター名	タイプ	指定対象	説明
`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`	`AdGroup`のリスト
`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`

リソースの表現

AdGroup

{
    "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"
       }
    }
}

エラー

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

開発者ガイドの概要

Amazon Ads APIの概要

広告グループ

操作

getAdGroup

パラメーター

レスポンス

getAdGroupEx

パラメーター

レスポンス

createAdGroups

パラメーター

レスポンス

updateAdGroups

パラメーター

レスポンス

archiveAdGroup

パラメーター

レスポンス

listAdGroups

パラメーター

レスポンス

listAdGroupsEx

パラメーター

レスポンス

リソースの表現

AdGroup

AdGroupEx

AdGroupResponse

エラー