تعديل خدمة الموارد

إنّ استخدام الخدمة المخصّصة لأحد الموارد هو الطريقة الأكثر مباشرةً لإنشاء عناصر من نوع مورد واحد أو تعديلها أو إزالتها في Google Ads API.

نقاط نهاية التغيير

لكل مورد قابل للتغيير خدمة ونوع عملية مقابلَين. لتغيير مورد باستخدام الخدمة المخصّصة له، املأ أحد الحقول التالية في العملية وأرسِله إلى نقطة نهاية التغيير في الخدمة:

• Create (create): عنصر مورد جديد لإنشائه.
• التعديل (update): كائن المورد المعدَّل، مصحوبًا بـ update_mask يحدّد الحقول التي تم تغييرها
• ‫Remove (remove): سلسلة resource_name للمورد المستهدف المطلوب إزالته

على سبيل المثال، لإنشاء Campaign جديد، أكمِل الخطوات التالية:

1. أنشِئ عنصر Campaign بالسمات التي تختارها.
2. عيِّنها إلى الحقل create في CampaignOperation.
3. أرسِل العملية في MutateCampaignsRequest إلى CampaignService.MutateCampaigns.

ينطبق هذا النمط نفسه على جميع الخدمات المتعلّقة بمورد معيّن في Google Ads API:

• ‫AdGroup: مرِّر AdGroupOperation إلى AdGroupService.MutateAdGroups.
• ‫CampaignCriterion: مرِّر CampaignCriterionOperation إلى CampaignCriterionService.MutateCampaignCriteria.

توضّح حمولة REST JSON التالية طلبًا إلى CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

العمليات المتعددة والقيود

تقبل معظم طلبات التغيير الخاصة بمورد معيّن حقل operations متكررًا، لذا يمكن أن يحتوي طلب واحد على عمليات متعددة لنوع المورد هذا (ما يصل إلى 10,000 عملية لكل طلب، أو 20,000 عملية لـ AdGroupCriterionService.MutateAdGroupCriteria، ويقبل CustomerService.MutateCustomer حقل operation مفردًا). يتم تنفيذ جميع العمليات في الطلب بشكل ذري تلقائيًا ما لم تكن الخدمة تتيح استخدام partial_failure وتم ضبطه على true.

ومع ذلك، فإنّ خدمات الموارد الفردية لها قيدان مهمان:

• نوع المورد الواحد: لا يمكن لطلب موجّه إلى خدمة موارد أن يغيّر سوى الموارد التي تديرها تلك الخدمة المحدّدة.
• عدم توفّر معرّفات مؤقتة على مستوى الموارد: بما أنّ طلب التعديل الخاص بمورد معيّن لا يقبل سوى نوع مورد واحد، لا يمكنك تخصيص معرّف سالب مؤقت لمورد رئيسي (مثل customers/CUSTOMER_ID/campaigns/-1) والإشارة إليه من مورد فرعي من نوع مختلف (مثل AdGroup) في الطلب نفسه. (تتوفّر المعرّفات المؤقتة ذات المرجع الذاتي ضمن نوع المورد نفسه للأشجار الهرمية، مثل مجموعات بيانات AdGroupCriterion وعُقد AssetGroupListingGroupFilter).

إذا كنت بحاجة إلى تغيير أنواع موارد متعددة في طلب واحد أو الإشارة إلى أسماء موارد مؤقتة في أنواع موارد مختلفة، استخدِم GoogleAdsService.Mutate بدلاً من ذلك.

الاختلافات الخاصة بالإصدارات

يُرجى مراعاة الاختلاف التالي في إصدارات Google Ads API المتوافقة عند تعديل الموارد:

• خدمات أهداف مراحل النشاط: يتم تعديل أهداف "الاحتفاظ بالعملاء" في جميع الإصدارات المتوافقة من خلال GoalService.MutateGoals (retention_goal_settings) وCampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) باستخدام حقل operations عادي متكرّر. في الإصدار 25 والإصدارات الأحدث، يتم أيضًا تعديل "اكتساب عملاء جدد" (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) و"الاحتفاظ بالعملاء الأوفياء" (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) من خلال GoalService.MutateGoals وCampaignGoalConfigService.MutateCampaignGoalConfigs. يحلّ هذا الحقل محلّ CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals وCampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals، اللذين يُستخدَمان لاكتساب العملاء الجدد في الإصدارَين 23 و24 ويقبلان حقل operation واحدًا.