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