一括変更

1 回のリクエストで複数のリソースタイプを変更する場合や、すべての変更を統合エンドポイントに送信する場合は、GoogleAdsService.Mutate を使用します。サポートされているオペレーションの完全なリストについては、MutateOperation リファレンスをご覧ください。

mutate オペレーション

各 MutateGoogleAdsRequest は、mutate_operations フィールドで繰り返し MutateOperation を受け入れます。

  • リソース変更オペレーション(サポートされているすべてのバージョン): 各エントリでは、1 つのリソースタイプに対して 1 つの create、update、または remove オペレーションを指定できます。
  • アクション オペレーション(v23 以降): 各エントリで、book_campaigns_operation や quote_campaigns_operation などのアクション オペレーションを指定することもできます(v22 では、MutateOperation はリソースの変更オペレーションのみをサポートしています)。

1 回の GoogleAdsService.Mutate 呼び出しで依存エンティティ(キャンペーンや広告グループなど)を作成するには、2 つの MutateOperation エントリ(1 つは CampaignOperation を含み、もう 1 つは AdGroupOperation を含む)を作成します。広告グループ オペレーションが同じリクエストで参照できるように、負の ID(customers/CUSTOMER_ID/campaigns/-1 など)を持つ一時リソース名をキャンペーンに割り当てます。

Python

import uuid

campaign_budget_service = client.get_service("CampaignBudgetService")
campaign_service = client.get_service("CampaignService")
googleads_service = client.get_service("GoogleAdsService")

campaign_budget_resource_name = campaign_budget_service.campaign_budget_path(
    customer_id, budget_id
)
temp_campaign_resource_name = campaign_service.campaign_path(customer_id, "-1")

mutate_operation1 = client.get_type("MutateOperation")
campaign = mutate_operation1.campaign_operation.create
campaign.resource_name = temp_campaign_resource_name
campaign.name = f"Bulk Mutate Campaign #{uuid.uuid4()}"
campaign.advertising_channel_type = (
    client.enums.AdvertisingChannelTypeEnum.SEARCH
)
campaign.status = client.enums.CampaignStatusEnum.PAUSED
campaign.manual_cpc = client.get_type("ManualCpc")
campaign.campaign_budget = campaign_budget_resource_name
campaign.contains_eu_political_advertising = (
    client.enums.EuPoliticalAdvertisingStatusEnum.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING
)

mutate_operation2 = client.get_type("MutateOperation")
ad_group = mutate_operation2.ad_group_operation.create
ad_group.name = "Bulk Mutate Ad Group"
ad_group.campaign = temp_campaign_resource_name
ad_group.status = client.enums.AdGroupStatusEnum.ENABLED

response = googleads_service.mutate(
    customer_id=customer_id,
    mutate_operations=[mutate_operation1, mutate_operation2],
)

for op_response in response.mutate_operation_responses:
    result_type = op_response._pb.WhichOneof("response")
    result = getattr(op_response, result_type)
    print(f"Created {result_type}: {result.resource_name}")

Ruby

campaign_budget_resource_name =
  client.path.campaign_budget(customer_id, budget_id)
temp_campaign_resource_name =
  client.path.campaign(customer_id, -1)

mutate_operation1 = client.operation.mutate do |m|
  m.campaign_operation = client.operation.create_resource.campaign do |c|
    c.resource_name = temp_campaign_resource_name
    c.name = "Bulk Mutate Campaign #{(Time.new.to_f * 1000).to_i}"
    c.advertising_channel_type = :SEARCH
    c.status = :PAUSED
    c.manual_cpc = client.resource.manual_cpc
    c.campaign_budget = campaign_budget_resource_name
    c.contains_eu_political_advertising = :DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING
  end
end

mutate_operation2 = client.operation.mutate do |m|
  m.ad_group_operation = client.operation.create_resource.ad_group do |ag|
    ag.name = "Bulk Mutate Ad Group"
    ag.campaign = temp_campaign_resource_name
    ag.status = :ENABLED
  end
end

response = client.service.google_ads.mutate(
  customer_id: customer_id,
  mutate_operations: [mutate_operation1, mutate_operation2]
)

response.mutate_operation_responses.each do |op_response|
  result = op_response.send(op_response.response)
  puts "Created #{op_response.response}: #{result.resource_name}"
end

原子性と部分的な障害

デフォルトでは、GoogleAdsService.Mutate リクエストのオペレーションはアトミックに実行されます。すべてのオペレーションが同時に成功するか、いずれかのオペレーションにエラーが含まれている場合はリクエスト全体が失敗します。

個々のリソース サービスと同様に、このエンドポイントは次のオプションをサポートしています。

  • 部分的な失敗 (partial_failure = true): 有効なオペレーションをコミットし、失敗したオペレーションのエラーを partial_failure_error で返します。
  • 検証モード(validate_only = true): アカウントに変更をコミットせずに、オペレーションのエラーを確認します。
    • リソースの変更オペレーション: 検証エラーのみを返し、結果は省略します。
    • アクション オペレーション(v23 以降): 検証が成功した場合はアクション結果(quote_campaigns_result や book_campaigns_result など)を返します。検証エラーが発生した場合は、MutateOperationResponse からアクション結果が省略されます(ただし、ErrorDetails.reservation_error_details で見積もりは返される可能性があります)。quote_campaigns_operation には validate_only = true と partial_failure = false が必要です。