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

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

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

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

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

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

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

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

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

يوضّح حِمل JSON التالي لخدمة REST طلبًا إلى 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.