التبديلات المجمّعة

لتغيير أنواع موارد متعددة في طلب واحد أو إرسال جميع التغييرات إلى نقطة نهاية موحّدة، استخدِم GoogleAdsService.Mutate. للاطّلاع على القائمة الكاملة للعمليات المتوافقة، يُرجى مراجعة مرجع MutateOperation.

عمليات التغيير

يقبل كل MutateGoogleAdsRequest MutateOperation متكررًا في حقل mutate_operations:

• عمليات تحويل الموارد: يمكن لكل إدخال تحديد عملية create أو update أو remove واحدة لنوع مورد واحد.
• عمليات الإجراءات: يمكن لكل إدخال أيضًا تحديد عملية إجراء، مثل book_campaigns_operation أو quote_campaigns_operation.

لإنشاء كيانات تابعة (مثل حملة ومجموعة إعلانية) في طلب واحد من النوع GoogleAdsService.Mutate، أنشئ إدخالَين من النوع MutateOperation (يحتوي أحدهما على CampaignOperation والآخر على AdGroupOperation). حدِّد اسم مورد مؤقتًا برقم تعريف سالب (مثل 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 (partial_failure = true): لتنفيذ العمليات الصالحة وعرض الأخطاء للعمليات التي تعذّر تنفيذها في partial_failure_error.
• وضع التحقّق (validate_only = true): يتحقّق من العمليات بحثًا عن أخطاء بدون تطبيق التغييرات على الحساب:
  • عمليات تحويل الموارد: تعرض أخطاء التحقّق فقط وتحذف النتائج.
  • عمليات الإجراءات: تعرض نتيجة الإجراء (مثل quote_campaigns_result أو book_campaigns_result) عندما تنجح عملية التحقّق من الصحة. في حال حدوث أخطاء في عملية التحقّق من الصحة، يتم حذف نتيجة الإجراء من MutateOperationResponse (على الرغم من أنّه قد يتم عرض عرض أسعار تقديري في ErrorDetails.reservation_error_details). يُرجى العِلم أنّ quote_campaigns_operation تتطلّب validate_only = true وpartial_failure = false.