أفضل الممارسات والقيود

يُرجى مراعاة هذه الإرشادات عند استخدام BatchJobService.

تحسين معدّل النقل

  • يُفضَّل استخدام عدد أقل من المهام الكبيرة بدلاً من عدد كبير من المهام الصغيرة.

  • ترتيب العمليات التي تم تحميلها حسب نوع العملية (باستثناء العمليات المترابطة التي يجب تجميعها على التوالي في دفعات فرعية ذرية). على سبيل المثال، إذا كانت مهمتك تحتوي على عمليات لإضافة حملات عادية ومجموعات إعلانية ومعايير مجموعات إعلانية، رتِّب العمليات في عملية التحميل بحيث تكون جميع عمليات الحملات أولاً، تليها جميع عمليات المجموعات الإعلانية، وأخيرًا جميع عمليات معايير المجموعات الإعلانية.

  • ضمن العمليات من النوع نفسه، يمكن تحسين الأداء من خلال تجميعها حسب المورد الرئيسي. على سبيل المثال، إذا كانت لديك سلسلة من عناصر AdGroupCriterionOperation، من الأفضل تجميع العمليات حسب المجموعة الإعلانية بدلاً من خلط العمليات التي تؤثر في معايير المجموعة الإعلانية في مجموعات إعلانية مختلفة.

الذرية في تقسيم الدفعات

تقسّم Google Ads API العمليات في مهمة مجمّعة تم إرسالها إلى دفعات فرعية أصغر حجمًا للمعالجة. على الرغم من أنّ الدفعات الفرعية العادية يتم تنفيذها مع تفعيل ميزة الفشل الجزئي، تتم معالجة الدفعات الفرعية لبعض العمليات المترابطة بشكل مستقل كمعاملة واحدة:

بالنسبة إلى كلّ من AssetGroup و"حملات الأداء الأفضل"، Campaign الدفعات الفرعية للإنشاء (ما يصل إلى 1,000 عملية إجمالاً لكل دفعة فرعية، وأي عمليات create فرعية تتجاوز 999 عملية يتم نقلها إلى الدفعة الفرعية غير الذرية التالية):

  • يجب أن تحدّد عملية create الرئيسية (resource_name على AssetGroup أو Campaign) وعمليات create الفرعية المتتالية (asset_group على AssetGroupAsset أو campaign على CampaignAsset) المعرّف المؤقت السالب نفسه.
  • ضَع أي عمليات AssetOperation (create) مطلوبة مسبقًا لموارد Asset الجديدة قبل المورد الرئيسي AssetGroupOperation أو CampaignOperation (create)، وليس بين المورد الرئيسي create وعمليات الربط الفرعية create (التي ستؤدي على الفور إلى إغلاق الدفعة الفرعية الذرية وفصل عملية إنشاء المورد الرئيسي عن مواد العرض المرتبطة به).

عند تعذُّر تنفيذ دفعة فرعية ذرية، يحتوي BatchJobResult.status للعملية المخالفة على خطأ التحقّق الأساسي، بينما يتم التراجع عن العمليات المتبقية في تلك الدفعة الفرعية مع ظهور خطأ المعاملة المقابل لتلك الدفعة الفرعية. افحص إدخالات BatchJobResult المجاورة التي تشارك معرّف AdGroup أو AssetGroup أو Campaign نفسه لتحديد السبب الأساسي للخطأ.

إذا لم تتم إضافة العمليات ذات الصلة في أي من هذه المجموعات بشكل متتالٍ، ستقسّمها Google Ads API إلى دفعات فرعية منفصلة، ما يؤدي إلى عدم استيفاء التعديل للحد الأدنى من متطلبات مواد العرض أو ترك أشجار مجموعات البيانات غير مكتملة. يُرجى الاطّلاع على استخدام فلاتر مجموعات البيانات في المهام المجمّعة ومعالجة على دفعات في "حملات الأداء الأفضل" لمزيد من التفاصيل.

التجميع المنطقي

عند تعديل تسلسل هرمي لاستهداف المنتجات (AssetGroupListingGroupFilterOperation في حملات الأداء الأفضل أو AdGroupCriterionOperation في حملات تسوّق) أو إنشاء AssetGroup جديد أو Campaign في الأداء الأفضل، عليك تجميع كل العمليات التي تستهدف المورد الرئيسي نفسه (AssetGroup أو AdGroup أو Campaign) على التوالي. يقلل هذا من تنازع القفل في الخلفية ويحافظ على الأشجار المترابطة معًا.

اتساق البيانات

بما أنّه يتم التحقّق من صحة أشجار فلاتر مجموعات البيانات ومتطلبات مواد العرض في "حملات الأداء الأفضل" في نهاية كل معاملة فرعية مجمّعة، تجنَّب تقسيم التعديلات على المورد الرئيسي نفسه على مستوى نطاقات غير متواصلة في مهمة معيّنة أو على مستوى مهام متزامنة.

تجنُّب مشاكل التزامن

  • عند إرسال وظائف متزامنة متعددة للحساب نفسه، يجب تقليل احتمالية عمل الوظائف على العناصر نفسها في الوقت نفسه مع الحفاظ على أحجام وظائف كبيرة. يمكن أن تؤدي العديد من المهام غير المكتملة التي تحمل الحالة RUNNING والتي تحاول تغيير مجموعة العناصر نفسها إلى حالات تشبه حالة التوقف التام، ما يؤدي إلى بطء شديد وحتى فشل المهام.

  • لا ترسِل عمليات متعددة تؤدي إلى تغيير العنصر نفسه في المهمة نفسها، لأنّ النتيجة قد تكون غير متوقعة.

استرداد النتائج على النحو الأمثل

  • لا تستطلِع حالة المهمة بشكل متكرر وإلا قد تظهر لك أخطاء تجاوز الحد الأقصى المسموح به.

  • يجب ترك page_size بدون ضبط (أو ضبطه على الحد الأقصى 1000) عند استدعاء ListBatchJobResults لتقليل عمليات الذهاب والعودة لتقسيم الصفحات، وضبط response_content_type فقط على MUTABLE_RESOURCE إذا كان تطبيقك يفحص حقول الموارد التي تم عرضها بعد resource_name.

  • يكون ترتيب النتائج مماثلاً لترتيب التحميل.

إرشادات إضافية حول الاستخدام

  • يمكنك ضبط حد أقصى للمدة المسموح بها لتشغيل مهمة مجمّعة قبل إلغائها. عند إنشاء مهمة مجمّعة جديدة، اضبط حقل metadata.execution_limit_seconds على الحدّ الزمني المفضّل لديك بالثواني. لا يوجد حد زمني تلقائي في حال عدم ضبط السمة metadata.execution_limit_seconds.

  • على الرغم من أنّ الحدّ الأقصى المسموح به في البروتوكول هو 10,000 عملية لكل طلب، ننصحك بعدم إضافة أكثر من 1,000 عملية لكل AddBatchJobOperationsRequest واستخدام sequence_token لتحميل بقية العمليات إلى المهمة نفسها. استنادًا إلى حجم العمليات، قد يؤدي إرسال عدد كبير جدًا من العمليات في AddBatchJobOperationsRequest واحدة إلى حدوث خطأ BatchJobError.REQUEST_TOO_LARGE. يمكنك معالجة هذا الخطأ من خلال تقليل عدد العمليات وإعادة محاولة تنفيذ AddBatchJobOperationsRequest.

القيود

  • يتيح كل BatchJob ما يصل إلى مليون عملية. يؤدي تجاوز هذا الحدّ عند طلب AddBatchJobOperations إلى عرض الخطأ ResourceCountLimitExceededError.RESOURCE_LIMIT (مع ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB في ErrorDetails.resource_count_details).

  • يمكن أن يتضمّن كل حساب ما يصل إلى 100 مهمة نشطة أو في انتظار المراجعة في الوقت نفسه. في حال تجاوز هذا الحدّ عند إنشاء مهمة مجمّعة باستخدام MutateBatchJob، يظهر الخطأ ResourceCountLimitExceededError.RESOURCE_LIMIT (مع ResourceLimitType.BATCH_JOBS_PER_CUSTOMER في ErrorDetails.resource_count_details).

  • تتم تلقائيًا إزالة المهام المعلّقة التي مرّ عليها أكثر من 7 أيام.

  • يبلغ الحدّ الأقصى لعدد عمليات التغيير في كل AddBatchJobOperationsRequest 10,000 عملية لكل طلب. يؤدي تجاوز 10,000 عملية في طلب واحد إلى ظهور الخطأ BatchJobError.REQUEST_TOO_LARGE.

  • بالنسبة إلى حقل page_size في ListBatchJobResultsRequest:

    • إذا لم يتم ضبط السمة page_size أو تم ضبطها على 0، يتم ضبطها تلقائيًا على الحد الأقصى وهو 1000.
    • إذا تجاوزت قيمة page_size الحدّ الأقصى 1000 أو كانت أقل من الحدّ الأدنى 0، ستعرض واجهة برمجة التطبيقات الخطأ BatchJobError.INVALID_PAGE_SIZE.

  • الحد الأقصى لحجم كل AddBatchJobOperationsRequest هو 41,937,920 بايت. في حال تجاوز هذا الحدّ، ستتلقّى الخطأ BatchJobError.REQUEST_TOO_LARGE (أو INTERNAL_ERROR إذا تم رفضه في طبقة النقل). يمكنك تحديد حجم الطلب المتسلسل قبل إرساله واتخاذ الإجراء المناسب إذا كان كبيرًا جدًا:

    جافا

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    #C

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Ruby

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    Perl

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

حجم عملية التبديل الواحدة

على الرغم من أنّ إجمالي حجم الطلب يمكن أن يصل إلى 41,937,920 بايت، فإنّ الحجم التسلسلي لكل MutateOperation ضمن الدفعة يقتصر على 10,484,504 بايت (10 ميبيبايت ناقص 1,256 بايت). ويؤدي تجاوز هذا الحدّ إلى ظهور الخطأ BatchJobError.REQUEST_TOO_LARGE. يُرجى العِلم أنّه على الرغم من أنّ المستندات المرجعية لـ BatchJobError.REQUEST_TOO_LARGE تشير إلى الحدّ الأقصى البالغ 10,484,504 بايت، فإنّ AddBatchJobOperations يعرض رمز الخطأ نفسه عند تجاوز أيّ من الحدود القصوى الثلاثة للطلبات (إجمالي 41,937,920 بايت للطلب، أو 10,484,504 بايت للعملية الواحدة، أو 10,000 عملية لكل طلب)، مع تحديد الحدّ الذي تم تجاوزه في حقل message الخاص بالخطأ.

السابق
فلاتر مجموعات البيانات