Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

変更

ほとんどのリソースは、Mutate メソッドを使用して変更(作成、更新、削除)されます。Mutate メソッドは、リソース名のパターンに一致するリソース固有の URL に対して、末尾のリソース ID なしで HTTP POST として呼び出されます。変更されるリソースの ID は、代わりに JSON リクエスト本文で送信されます。これにより、異なるリソースに対する複数のオペレーションを含む単一の API 呼び出しを送信できます。

たとえば、キャンペーン名は以下の形式になります。

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

ミューテーションに使用される URL を導出するには、末尾のリソース ID を省略し、:mutate を追加します。

https://googleads.googleapis.com/v11/customers/CUSTOMER_ID/campaigns:mutate

Mutate メッセージには、多数の operation オブジェクトを含めることができる operations 配列を持つトップレベルの JSON オブジェクトが含まれます。一方、各オペレーションは createupdateremove のいずれかになります。これが唯一の変更オペレーションです。

POST /v11/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    ...
  ]
}

ほとんどのサービスでは、1 回の API 呼び出しで数千のオペレーションをサポートできます。システム制限ガイドに、リクエスト サイズの制限が記載されています。

1 つの API リクエスト内のオペレーションは、デフォルトで 1 つのアクション セットとして実行されます。つまり、すべてが一緒に成功するか、1 つのオペレーションが失敗した場合にバッチ全体が失敗します。一部のサービスでは、partialFailure 属性を使用して、この動作を変更できます。変更オペレーションのセマンティクスの詳細については、リソースの変更をご覧ください。

作成

作成オペレーションでは新しいエンティティが生成され、作成するリソースの完全な JSON 表現を含める必要があります。

POST /v11/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
    "create": {
        "name": "An example campaign",
        "status": "PAUSED",
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID",
        "advertisingChannelType": "SEARCH",
        "networkSettings": {
          "targetGoogleSearch": true,
          "targetSearchNetwork": true,
          "targetContentNetwork": true,
          "targetPartnerSearchNetwork": false
        },
        "target_spend": {}
      }
    }
  ]
}

更新

更新オペレーションは、既存のリソースに対してスパース アップデートを実行します。変更するフィールドを指定するだけでかまいません。

更新するフィールドを指定するには、updateMask 属性をフィールド名のカンマ区切りリストに設定します。これは、すでに完全な JSON 表現でオブジェクトを表現済み(前の API 呼び出しで返されたものなど)があり、特定のフィールドのみを変更する場合に特に便利です。JSON オブジェクトをプルーニングする代わりに、updateMask で変更するフィールド名を一覧表示し、JSON オブジェクト全体を送信できます。

以下の例では、特定の resourceName を持つ既存のキャンペーンの namestatus を変更しています。

POST /v11/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

削除

削除オペレーションでは、オブジェクトを効果的に削除し、Google 広告のステータスを REMOVED に設定します。削除する必要があるのは、resourceName のみです。

POST /v11/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}