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

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

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 كما هو موضّح في مثال JSON بتنسيق REST التالي (مع حذف حقول الموارد المطلوبة الأخرى للإيجاز):

{
  "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.