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

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

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

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

• عمليات تغيير الموارد (جميع الإصدارات المتوافقة): يمكن لكل إدخال تحديد عملية create أو update أو remove واحدة لنوع مورد واحد.
• عمليات الإجراءات (الإصدار 23 والإصدارات الأحدث): يمكن لكل إدخال أيضًا تحديد عملية إجراء، مثل book_campaigns_operation أو quote_campaigns_operation (في الإصدار 22، لا تتيح MutateOperation سوى عمليات تعديل الموارد).

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