ほとんどのリソースは、Mutate
メソッドを使用して変更(作成、更新、削除)されます。Mutate
メソッドは、リソース名のパターンと一致するリソース固有の URL に対して、末尾のリソース ID のないリソース固有の URL への HTTP POST
として呼び出されます。変更されるリソースの ID は、代わりに JSON リクエストの本文で送信されます。これにより、異なるリソースに対する複数のオペレーションを含む 1 つの API 呼び出しを送信できます。
たとえば、キャンペーンのリソース名は次の形式になります。
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
キャンペーンの変更に使用する URL を導出するには、末尾のリソース ID を省略して :mutate
を追加します。
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/campaigns:mutate
Mutate
メッセージには、多数の operation
オブジェクトを格納できる operations
配列を持つ最上位の JSON オブジェクトが含まれます。各オペレーションは、create
、update
、remove
のいずれかになります。これが唯一の変換オペレーションです。
POST /v17/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 表現を含める必要があります。
POST /v17/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 /v17/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 /v17/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" } ] }