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

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

تتيح 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.