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

يُرجى مراعاة الإرشادات التالية عند استخدام 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.

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

  Java

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

  Python

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

  Ruby

  
  require 'google/ads/google_ads'
  
  MAX_REQUEST_BYTES = 10484504
  
  ... (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 = 10484504;
  
  ... (code to get the request object)
  
  $size_in_bytes = $campaign->byteSize() . PHP_EOL;
  

  NET.

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

  Perl

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