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

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

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

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

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

عند تعديل تسلسل هرمي لاستهداف المنتجات (AssetGroupListingGroupFilterOperation في "حملات الأداء الأفضل" أو AdGroupCriterionOperation في "حملات Shopping") أو إنشاء 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 في الخطأ للحدّ الذي تمّ تجاوزه.

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