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

يُرجى مراعاة هذه الإرشادات عند استخدام 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\V24\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 ميغابايت).