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

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

إذا تم قبول طلب 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-100 ثانية	يشير إلى استنفاد حصة طلبات الاكتشاف لكل 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، بينما تتم زيادته بمقدار 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."