批量转变

如需在单个请求中变更多种资源类型，或将所有变更发送到统一的端点，请使用 GoogleAdsService.Mutate。如需查看支持的操作的完整列表，请参阅 MutateOperation 参考文档。

Mutate 操作

每个 MutateGoogleAdsRequest 都接受 mutate_operations 字段中的重复 MutateOperation：

  • 资源突变操作（所有受支持的版本）：每个条目都可以为一种资源类型指定单个 create、update 或 remove 操作。
  • 操作操作（v23 及更高版本）：每个条目还可以指定操作操作，例如 book_campaigns_operation 或 quote_campaigns_operation（在 v22 中，MutateOperation 仅支持资源 mutate 操作）。

如需在单个 GoogleAdsService.Mutate 调用中创建相关实体（例如广告系列和广告组），请创建两个 MutateOperation 条目（一个包含 CampaignOperation，另一个包含 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)：检查操作是否存在错误，但不会将更改提交到账号：
    • 资源 mutate 操作：仅返回验证错误，并省略结果。
    • 操作操作（v23 及更高版本）：如果验证成功，则返回操作结果（例如 quote_campaigns_result 或 book_campaigns_result）；如果发生验证错误，则从 MutateOperationResponse 中省略操作结果（不过可能仍会在 ErrorDetails.reservation_error_details 中返回报价）。请注意，quote_campaigns_operation 需要 validate_only = true 和 partial_failure = false。
上一页
资源转变
下一页
最佳实践