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