ほとんどのリソースは、Mutate メソッドを使用して変更（作成、更新、削除）されます。Mutate メソッドは、リソース名パターンに一致するリソース固有の URL への HTTP POST として呼び出されます。末尾にリソース ID はありません。変更するリソースの ID は、JSON リクエストの本文で送信されます。これにより、異なるリソースに対する複数のオペレーションを含む単一の API 呼び出しを送信できます。
たとえば、キャンペーンのリソース名は次の形式になります。
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
キャンペーンの変更に使用する URL を取得するには、末尾のリソース ID を省略して :mutate を追加します。
https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/campaigns:mutate
Mutate メッセージには、多くの operation オブジェクトを含む operations 配列を含む最上位の JSON オブジェクトが含まれています。各オペレーションは、create、update、remove のいずれかになります。これらの操作のみが可能です。
POST /v21/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 つのアクション セットとして実行されます。つまり、すべてのオペレーションが同時に成功するか、いずれかのオペレーションが失敗するとバッチ全体が失敗します。一部のサービスは、この動作を変更する partialFailure 属性をサポートしています。ミューテート オペレーションのセマンティクスの詳細については、リソースの変更をご覧ください。
作成
作成オペレーションは新しいエンティティを生成するため、作成するリソースの完全な JSON 表現を含める必要があります。
POST /v21/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 を持つ既存のキャンペーンの name と status を変更します。
POST /v21/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 /v21/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" } ] }