Thay đổi hàng loạt

Để thay đổi nhiều loại tài nguyên trong một yêu cầu hoặc gửi tất cả các thay đổi đến một điểm cuối hợp nhất, hãy sử dụng GoogleAdsService.Mutate. Để biết danh sách đầy đủ các thao tác được hỗ trợ, hãy xem tài liệu tham khảo về MutateOperation.

Thao tác thay đổi

Mỗi MutateGoogleAdsRequest chấp nhận một MutateOperation lặp lại trong trường mutate_operations:

  • Các thao tác biến đổi tài nguyên (tất cả các phiên bản được hỗ trợ): Mỗi mục có thể chỉ định một thao tác create, update hoặc remove duy nhất cho một loại tài nguyên.
  • Thao tác hành động (phiên bản 23 trở lên): Mỗi mục nhập cũng có thể chỉ định một thao tác hành động, chẳng hạn như book_campaigns_operation hoặc quote_campaigns_operation (trong phiên bản 22, MutateOperation chỉ hỗ trợ các thao tác biến đổi tài nguyên).

Để tạo các thực thể phụ thuộc (chẳng hạn như chiến dịch và nhóm quảng cáo) trong một lệnh gọi GoogleAdsService.Mutate duy nhất, hãy tạo 2 mục MutateOperation (một mục chứa CampaignOperation và một mục khác chứa AdGroupOperation). Chỉ định một tên tài nguyên tạm thời có mã nhận dạng âm (chẳng hạn như customers/CUSTOMER_ID/campaigns/-1) cho chiến dịch để thao tác nhóm quảng cáo có thể tham chiếu đến chiến dịch đó trong cùng một yêu cầu:

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

Tính nguyên tử và lỗi một phần

Theo mặc định, các thao tác trong yêu cầu GoogleAdsService.Mutate sẽ thực thi theo cách thức nguyên tử: tất cả các thao tác đều thành công cùng nhau hoặc toàn bộ yêu cầu sẽ thất bại nếu có bất kỳ thao tác nào chứa lỗi.

Giống như các dịch vụ tài nguyên riêng lẻ, điểm cuối này hỗ trợ các lựa chọn sau:

  • Thất bại một phần (partial_failure = true): Xác nhận các thao tác hợp lệ và trả về lỗi cho các thao tác không thành công trong partial_failure_error.
  • Chế độ xác thực (validate_only = true): Kiểm tra các thao tác để tìm lỗi mà không cần thực hiện các thay đổi đối với tài khoản:
    • Các thao tác biến đổi tài nguyên: Chỉ trả về các lỗi xác thực và bỏ qua kết quả.
    • Thao tác hành động (phiên bản 23 trở lên): Trả về kết quả của hành động (chẳng hạn như quote_campaigns_result hoặc book_campaigns_result) khi quá trình xác thực thành công; nếu xảy ra lỗi xác thực, kết quả của hành động sẽ bị bỏ qua trong MutateOperationResponse (mặc dù một câu trích dẫn vẫn có thể được trả về trong ErrorDetails.reservation_error_details). Lưu ý rằng quote_campaigns_operation yêu cầu validate_only = true và partial_failure = false.