ほとんどのリソースは、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"
}
]
}