الردود على الخطأ

استجابات الأخطاء العادية

إذا نجح طلب واجهة برمجة التطبيقات Reporting API، ستعرض واجهة برمجة التطبيقات الخطأ 200. في حال حدوث خطأ في أحد الطلبات، تعرض واجهة برمجة التطبيقات رمز حالة HTTP والحالة والسبب في الاستجابة استنادًا إلى نوع الخطأ. بالإضافة إلى ذلك، يحتوي نص الرد على وصف تفصيلي لسبب الخطأ. إليك مثال على استجابة خطأ:

{
 "error": {
  "code": 403,
  "message": "User does not have sufficient permissions for this profile.",
  "status": "PERMISSION_DENIED"
 }
}

جدول الأخطاء

الرمز الحالة الوصف الإجراء المقترَح
400 INVALID_ARGUMENT الطلب غير صالح؛ قد تكون الوسيطة المطلوبة مفقودة أو تتجاوز الحدود أو تتضمن قيمة غير صالحة. راجِع رسالة الخطأ لمعرفة التفاصيل. سيفشل العميل مرة أخرى إذا أعاد المحاولة.
401 UNAUTHENTICATED لم تتم مصادقة العميل بشكل صحيح. يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. يجب الحصول على رمز مصادقة جديد.
403 PERMISSION_DENIED تشير هذه القيمة إلى طلب البيانات الذي لا يمكن للمستخدم الوصول إليه. يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. يجب الحصول على أذونات كافية لتنفيذ العملية على العنصر المحدّد.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-1d يشير إلى نفاد حصة الطلبات اليومية لكل مشروع. يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. لقد استنفدت حصتك اليومية.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-100s يشير إلى نفاد حصة الطلبات لكل 100 ثانية لكل مشروع. أعد المحاولة باستخدام الرقود الأسي. يجب إبطاء معدل إرسال الطلبات.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupUSER-100s يشير إلى استنفاد حصة الطلبات لكل 100 ثانية لكل مستخدم لكل مشروع. أعد المحاولة باستخدام الرقود الأسي. يجب إبطاء معدل إرسال الطلبات.
429 RESOURCE_EXHAUSTED DiscoveryGroupCLIENT_PROJECT-100s يشير إلى نفاد حصة طلبات استكشاف المحتوى لكل 100 ثانية. لا تتغير استجابة الاكتشاف بشكل متكرر. يمكنك تخزين استجابة الاكتشاف مؤقتًا على الجهاز أو إعادة المحاولة باستخدام الرقود الأسي. ويجب تخفيض المعدّل الذي ترسل به الطلبات.
500 INTERNAL حدث خطأ غير متوقّع في الخادم الداخلي. يجب عدم إعادة محاولة إجراء هذا الطلب أكثر من مرّة.
503 BACKEND_ERROR عرَض الخادم خطأ. يجب عدم إعادة محاولة إجراء هذا الطلب أكثر من مرّة.
503 UNAVAILABLE تعذّر على الخدمة معالجة الطلب. هذه حالة مؤقتة على الأرجح ويمكن تصحيحها من خلال إعادة المحاولة باستخدام التراجع الأُسيّ.

تنفيذ التراجع الأسي

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

في ما يلي خطوات تنفيذ تراجع أسي بسيط.

  1. تقديم طلب إلى واجهة برمجة التطبيقات
  2. تلقي استجابة خطأ تحتوي على رمز خطأ يمكن إعادة المحاولة
  3. الانتظار لمدة ثانية واحدة + random_number_milliseconds ثانية
  4. إعادة محاولة الطلب
  5. تلقي استجابة خطأ تحتوي على رمز خطأ يمكن إعادة المحاولة
  6. الانتظار لمدة ثانيتين وrandom_number_milliseconds ثانية
  7. إعادة محاولة الطلب
  8. تلقي استجابة خطأ تحتوي على رمز خطأ يمكن إعادة المحاولة
  9. الانتظار لمدة 4 ثوانٍ + random_number_milliseconds ثانية
  10. إعادة محاولة الطلب
  11. تلقي استجابة خطأ تحتوي على رمز خطأ يمكن إعادة المحاولة
  12. الانتظار لمدة 8 ثوانٍ + random_number_milliseconds ثانية
  13. إعادة محاولة الطلب
  14. تلقي استجابة خطأ تحتوي على رمز خطأ يمكن إعادة المحاولة
  15. الانتظار لمدة 16 ثانية + random_number_milliseconds ثانية
  16. إعادة محاولة الطلب
  17. في حال استمرار ظهور الخطأ، يُرجى التوقف وتسجيل الخطأ.

في المسار أعلاه، يمثّل random_number_milliseconds عددًا عشوائيًا للملي ثانية أقل من أو يساوي 1000. وهذا أمر ضروري لتجنُّب أخطاء قفل معيّنة في بعض عمليات التنفيذ المتزامنة. يجب إعادة تعريف random_number_milliseconds بعد كل انتظار.

ملاحظة: يكون وقت الانتظار دائمًا (2 ^ n) + random_number_milliseconds، حيث n هو عدد صحيح متزايد بشكل روتيني يتم تعريفه في البداية على 0. وتتم زيادة n بمقدار 1 لكل تكرار (كل طلب).

يتم تعيين الخوارزمية على الانتهاء عندما تكون n هي 5. ولا يتم تطبيق هذا الحدّ الأقصى إلّا لمنع العملاء من إعادة المحاولة بشكل غير محدود، ويؤدي إلى تأخير إجمالي لمدة 32 ثانية تقريبًا قبل اعتبار الطلب على أنّه "خطأ لا يمكن إصلاحه".

رمز Python التالي هو تطبيق للخطوات الواردة أعلاه لاسترداد الأخطاء التي تحدث بطريقة تُسمى makeRequest.

import random
import time
from apiclient.errors import HttpError

def makeRequestWithExponentialBackoff(analytics):
  """Wrapper to request Google Analytics data with exponential backoff.

  The makeRequest method accepts the analytics service object, makes API
  requests and returns the response. If any error occurs, the makeRequest
  method is retried using exponential backoff.

  Args:
    analytics: The analytics service object

  Returns:
    The API response from the makeRequest method.
  """
  for n in range(0, 5):
    try:
      return makeRequest(analytics)

    except HttpError, error:
      if error.resp.reason in ['userRateLimitExceeded', 'quotaExceeded',
                               'internalServerError', 'backendError']:
        time.sleep((2 ** n) + random.random())
      else:
        break

  print "There has been an error, the request never succeeded."