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

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

تحسين سرعة معالجة البيانات

• يُفضّل أن تكون هناك وظائف أكبر قليلة على أن تكون هناك وظائف أصغر كثيرة.

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

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

التجزئة الذرية في التقسيم المجمّع

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

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

AssetGroupListingGroupFilterOperation يدير مجموعات البيانات ضمن AssetGroup، وهو أمر شائع في "حملات الأداء الأفضل". تتولّى AdGroupCriterionOperation إدارة مجموعات بيانات المتجر ضمن AdGroup، وهو أمر شائع في "حملات Shopping" العادية. يُستخدم كلاهما لتحديد استهداف المنتجات. إذا أجريت تغييرات تؤثّر في التسلسل الهرمي لاستهداف المنتجات في السياقَين معًا، عليك تجميع هذه العمليات بشكل متتابع في مهمة الدفعات لضمان تطبيقها معًا.

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

للحفاظ على اتساق البيانات ومنع التعديلات الجزئية، أضِف عمليات مجموعة بيانات البطاقات ذات الصلة على التوالي إلى مهمة الدفعات. يساعد هذا الترتيب في تجميعها في دفعات فرعية أساسية حسب منطق تقسيم الدفعات في واجهة برمجة التطبيقات، ما يمنع ترك حسابك في حالة غير متسقة.

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

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

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

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

• لا تطلب حالة المهمة بشكل متكرر جدًا، وإلا ستواجه أخطاء الحدّ من معدّل الزحف.

• لا تستردّ أكثر من 1,000 نتيجة في كل صفحة. قد يعرض الخادم عددًا أقل من ذلك بسبب الحمولة أو عوامل أخرى.

• سيكون ترتيب النتائج هو نفسه ترتيب التحميل.

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

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

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

القيود

• يمكن لكل BatchJob تنفيذ ما يصل إلى مليون عملية.

• يمكن أن يتضمّن كل حساب ما يصل إلى 100 وظيفة نشطة أو في انتظار المراجعة في الوقت نفسه.

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

• اعتبارًا من الإصدار 22، يبلغ الحد الأقصى لعدد عمليات التعديل في كل طلب AddBatchJobOperations‏ 10,000 عملية.

• اعتبارًا من الإصدار 22، بالنسبة إلى الحقل page_size في ListBatchJobResultsRequest:

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

• اعتبارًا من الإصدار 23، يبلغ الحد الأقصى لحجم كل AddBatchJobOperationsRequest 41,937,920 بايت. وفي حال تجاوزت هذا الحد، ستتلقّى INTERNAL_ERROR. يمكنك تحديد حجم الطلب قبل إرساله واتّخاذ الإجراء المناسب إذا كان كبيرًا جدًا.

  جافا

  
  static final int MAX_REQUEST_BYTES = 41_937_920;
  
  ... (code to get the request object)
  
  int sizeInBytes = request.getSerializedSize();
  

  Python

  
  from google.ads.googleads.client import GoogleAdsClient
  
  MAX_REQUEST_BYTES = 41937920
  
  ... (code to get the request object)
  
  size_in_bytes = request._pb.ByteSize()
  

  Ruby

  
  require 'google/ads/google_ads'
  
  MAX_REQUEST_BYTES = 41937920
  
  ... (code to get the request object)
  
  size_in_bytes = request.to_proto.bytesize
  

  PHP

  
  use Google\Ads\GoogleAds\V16\Resources\Campaign;
  
  const MAX_REQUEST_BYTES = 41937920;
  
  ... (code to get the request object)
  
  $size_in_bytes = $campaign->byteSize() . PHP_EOL;
  

  NET.

  
  using Google.Protobuf;
  const int MAX_REQUEST_BYTES = 41937920;
  
  ... (code to get the request object)
  
  int sizeInBytes = request.ToByteArray().Length;
  

  Perl

  
  use Devel::Size qw(total_size);
  use constant MAX_REQUEST_BYTES => 41937920;
  
  ... (code to get the request object)
  
  my $size_in_bytes = total_size($request);
  

حجم عملية التعديل الفردية

على الرغم من أنّ الطلب الإجمالي يمكن أن يكون أكبر، إلا أنّ حجم عملية تغيير واحدة ضمن المجموعة يبلغ 10,484,488 بايت كحدّ أقصى (حوالي 10.48 ميغابايت).