استخدام معرّفات مؤقتة

أسماء الموارد المؤقتة

تتيح BatchJobService استخدام أسماء الموارد المؤقتة التي يمكن الإشارة إليها في العمليات اللاحقة ضمن مهمة مجمّعة واحدة، بما في ذلك في طلبات AddBatchJobOperations المتسلسلة المتعددة التي يتم تحميلها باستخدام sequence_token. يتيح لك ذلك إنشاء حملة ومجموعاتها الإعلانية وإعلاناتها ومعاييرها التابعة لها في مهمة مجمّعة واحدة قبل تعيين أرقام التعريف من جهة الخادم. في القواعد العامة والمثال التاليَين، يشير الطلب الواحد إلى BatchJob كامل في جميع عمليات تحميل AddBatchJobOperations.

للإشارة إلى مورد تم إنشاؤه حديثًا ضمن طلب التغيير أو مهمة الدفعة نفسهما، حدِّد رقم تعريف صحيحًا سالبًا (مثل -1 أو -2، باستثناء 0) في حقل resource_name للمورد الجديد. على سبيل المثال، عند إنشاء حملة في طلب مجمّع، اضبط اسم المورد على customers/CUSTOMER_ID/campaigns/-1. عند إنشاء مجموعة إعلانية في عملية لاحقة ضمن الطلب نفسه، يجب الإشارة إلى customers/CUSTOMER_ID/campaigns/-1 كالحملة الرئيسية. تستبدل واجهة برمجة التطبيقات -1 تلقائيًا برقم تعريف الحملة الفعلي الذي تم إنشاؤه عند الإنشاء.

قيود الاستخدام

يُرجى مراعاة القواعد التالية عند استخدام أسماء الموارد المؤقتة:

• الترتيب مهم: لا يمكنك الإشارة إلى اسم مورد مؤقت إلا بعد تحديده. في قائمة العمليات، يجب أن تظهر العملية التابعة (مثل إنشاء مجموعة إعلانية) بعد العملية التي تنشئ موردها الرئيسي (مثل إنشاء حملة).
• نطاق الطلب الواحد أو وظيفة الدفعة: لا تظل أسماء الموارد المؤقتة محفوظة في الوظائف المنفصلة أو طلبات التغيير. للإشارة إلى مورد تم إنشاؤه في مهمة سابقة أو طلب تغيير، استخدِم اسم المورد الفعلي الذي أنشأه النظام.
• التفرّد العام: ضمن طلب تغيير أو مهمة واحدة، يجب أن يستخدم كل اسم مورد مؤقت عددًا صحيحًا سالبًا فريدًا في جميع أنواع الموارد. على سبيل المثال، لا يمكنك تعيين -1 لكل من حملة ومجموعة إعلانية في الطلب نفسه. تؤدي إعادة استخدام معرّف مؤقت ضمن الطلب نفسه أو وظيفة مجمّعة إلى ظهور الخطأ NewResourceCreationError.DUPLICATE_TEMP_IDS.

مثال على الحمولة

لنفترض أنّك تريد إضافة حملة ومجموعة إعلانية وإعلان في طلب بيانات واحد من واجهة برمجة التطبيقات أو وظيفة مجمّعة. يمكنك تنظيم مصفوفة mutateOperations في حمولة طلب GoogleAdsService.Mutate أو BatchJobService.AddBatchJobOperations كما هو موضّح في مثال REST JSON التالي (مع حذف حقول الموارد الأخرى المطلوبة للإيجاز):

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

يوضّح هذا المثال التفاصيل الرئيسية التالية:

• تستخدم المجموعة الإعلانية معرّفًا مؤقتًا جديدًا (-2) لأنّ المعرّف -1 سبق أن تم تعيينه للحملة.
• تشير المجموعة الإعلانية إلى customers/CUSTOMER_ID/campaigns/-1 لربط نفسها بالحملة التي تم إنشاؤها في العملية السابقة.
• يشير adGroupAdOperation إلى customers/CUSTOMER_ID/adGroups/-2 ويحذف resourceName لأنّه ما مِن عملية لاحقة في الطلب تشير إلى الإعلان الجديد.

معالجة الأخطاء في المهام المجمّعة

بما أنّ العمليات العادية في وظيفة مجمّعة يتم تنفيذها مع تفعيل ميزة الإخفاق الجزئي (باستثناء الدفعات الفرعية الذرية)، إذا تعذّر التحقّق من صحة مورد رئيسي يتضمّن معرّفًا مؤقتًا، ستخفق أي عمليات فرعية تابعة تشير إلى ذلك المعرّف المؤقت مع ظهور الخطأ NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. تؤدي إعادة استخدام رقم التعريف السلبي نفسه في عمليات create متعددة ضمن مهمة الدفعة نفسها إلى عرض الخطأ NewResourceCreationError.DUPLICATE_TEMP_IDS. تكون المعرّفات المؤقتة صالحة فقط عند إنشاء الموارد (create) أو الإشارة إلى الموارد الرئيسية التي تم إنشاؤها حديثًا، على سبيل المثال، يؤدي تمرير معرّف مؤقت سالب في AdGroupCriterionOperation.remove عند استدعاء AddBatchJobOperations إلى عرض RequestError.RESOURCE_NAME_MALFORMED.