Mutate

注: より完全な例については、付属のサンプルの Mutates セクションをご覧ください。

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

たとえば、キャンペーンのリソース名は次の形式になります。

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

キャンペーンの変更に使用する URL を導出するには、末尾のリソース ID を省略して :mutate を追加します。

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

Mutate メッセージには、多くの operation オブジェクトを含む operations 配列を持つ最上位の JSON オブジェクトが含まれています。各オペレーションは、create、update、remove のいずれかです。これらは、可能なミューテーション オペレーションのみです。

POST /v19/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 呼び出しで数千のオペレーションをサポートしています。システムの上限ガイドでは、リクエスト サイズの上限について説明しています。

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

作成

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

キーポイント: 作成オペレーションでは、resourceName または ID を指定しません。API 呼び出しが成功すると、レスポンスには新しく作成されたオブジェクト用に生成された resourceName が含まれます。

POST /v19/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 オブジェクト全体を送信できます。

重要なポイント: update_mask は、特定のリソースの部分更新を容易にするために Google API 全体で使用される標準フィールドです。詳細については、FieldMask リファレンス ドキュメントをご覧ください。

次の例では、指定された resourceName を持つ既存のキャンペーンの name と status を変更します。

POST /v19/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 /v19/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"
    }
  ]
}