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

يُعدّ استخدام الخدمة المخصّصة لأحد الموارد الطريقة الأكثر مباشرةً لإنشاء عناصر من نوع مورد واحد أو تعديلها أو إزالتها في 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 عملية لكل طلب) لنوع المورد هذا. يتم تلقائيًا تنفيذ جميع العمليات في الطلب بشكل ذري ما لم تضبط partial_failure على true.

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

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

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

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

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

• خدمات أهداف مراحل النشاط: في الإصدار 25 والإصدارات الأحدث، يتم تعديل جميع أهداف مراحل النشاط، بما في ذلك اكتساب عملاء جدد (new_customer_acquisition_goal_settings) والاحتفاظ بالعملاء (retention_goal_settings) والاحتفاظ بالعملاء الأوفياء (loyalty_retention_goal_settings)، من خلال GoalService.MutateGoals وCampaignGoalConfigService.MutateCampaignGoalConfigs باستخدام حقل operations متكرّر عادي. يحلّ هذا المعيار محلّ CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals وCampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (اللذين يُستخدَمان لاكتساب العملاء الجدد في الإصدار 24 والإصدارات الأقدم ويقبلان الحقل الفردي operation).
• حقول التاريخ والوقت في الحملة: عند إنشاء Campaign أو تعديله، يستخدم الإصدار 23 والإصدارات الأحدث start_date_time وend_date_time (yyyy-MM-dd HH:mm:ss)، ما يحلّ محلّ الحقلَين start_date وend_date اللذين يتضمّنان التاريخ فقط والمستخدَمَين في الإصدار 22.
• تغيير بيانات صحة شهادة المحتوى الاصطناعي: على الرغم من أنّ Asset.synthetic_content_info وAd.synthetic_content_info يظهران في مخطط الإصدار 22 والإصدارات الأحدث، لا يمكن تغيير قيم الحقلَين synthetic_content_info.advertiser_attestation.status وsynthetic_content_info.advertiser_attestation.source إلا في الإصدار 23 والإصدارات الأحدث (تكون قيمة system_attestation دائمًا OUTPUT_ONLY). عند محاولة تغيير قيم الحقول الفرعية advertiser_attestation في الإصدار 22، سيظهر خطأ في الحقل غير القابل للتغيير ("The field attempted to be mutated is immutable" أو "Field cannot be set").