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

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

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

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "invalidParameter",
    "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]",
    "locationType": "parameter",
    "location": "max-results"
   }
  ],
  "code": 400,
  "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]"
 }
}

ملاحظة: يمكن أن يتغير الوصف في أي وقت، لذا يجب ألا تعتمد التطبيقات على نص الوصف الفعلي.

جدول الأخطاء

الرمز	السبب	الوصف	الإجراء المقترَح
400	invalidParameter	يشير إلى أن معلمة الطلب تتضمن قيمة غير صالحة. يقدّم الحقلان locationType وlocation في استجابة الخطأ معلومات عن القيمة غير الصالحة.	يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. تحتاج إلى توفير قيمة صالحة للمَعلمة المحدّدة في استجابة الخطأ.
400	badRequest	يشير إلى أن طلب البحث غير صالح. على سبيل المثال، كان رقم التعريف الرئيسي غير متوفّر أو كانت مجموعة السمات أو المقاييس المطلوبة غير صالحة.	يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. تحتاج إلى إجراء تغييرات على طلب بحث واجهة برمجة التطبيقات لكي يعمل.
401	invalidCredentials	يشير إلى أن الرمز المميز للمصادقة غير صالح أو منتهي الصلاحية.	يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. يجب الحصول على رمز مصادقة جديد.
403	insufficientPermissions	يشير إلى أنّ المستخدم لا يملك الأذونات الكافية للعنصر المحدَّد في طلب البحث.	يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. يجب الحصول على أذونات كافية لتنفيذ العملية على العنصر المحدّد.
403	dailyLimitExceeded	يشير إلى أن المستخدم قد تجاوز الحصة اليومية (إما لكل مشروع أو لكل ملف شخصي (الملف الشخصي)).	يُرجى عدم إعادة المحاولة بدون حلّ المشكلة. لقد استنفدت حصتك اليومية. يُرجى الاطّلاع على الحدود والحصص الخاصة بواجهة برمجة التطبيقات.
403	userRateLimitExceeded	يشير إلى تجاوز الحدّ الأقصى لطلبات البحث لكل 100 ثانية لكل مستخدم. والقيمة التلقائية المحدَّدة في وحدة تحكّم Google API هي 100 طلب بحث لكل 100 ثانية لكل مستخدم. يمكنك زيادة هذا الحد في وحدة التحكم في واجهة Google API إلى 1,000 كحد أقصى.	أعد المحاولة باستخدام الرقود الأسي. يجب إبطاء معدل إرسال الطلبات.
403	rateLimitExceeded	يشير إلى أنه تم تجاوز حدود معدل طلبات البحث لكل 100 ثانية للمشروع.	أعد المحاولة باستخدام الرقود الأسي. يجب إبطاء معدل إرسال الطلبات.
403	quotaExceeded	يشير هذا الحقل إلى بلوغ الطلبات العشرة المتزامنة لكل ملف شخصي (الملف الشخصي) في Core Reporting API.	أعد المحاولة باستخدام الرقود الأسي. يجب الانتظار حتى يكتمل طلب واحد على الأقل قيد التقدم لهذا الملف الشخصي (الملف الشخصي).
500	internalServerError	حدث خطأ غير متوقّع في الخادم الداخلي.	يجب عدم إعادة محاولة إجراء هذا الطلب أكثر من مرّة.
503	backendError	عرَض الخادم خطأ.	يجب عدم إعادة محاولة إجراء هذا الطلب أكثر من مرّة.

معالجة 500 أو 503 ردود

قد يظهر الخطأ 500 أو 503 أثناء التحميل الزائد أو مع الطلبات الأكبر تعقيدًا. بالنسبة للطلبات الأكبر، يمكنك التفكير في طلب البيانات لفترة زمنية أقصر. يمكنك أيضًا تنفيذ عملية تراجع أُسيّ. ويمكن أن يعتمد تكرار هذه الأخطاء على الملف الشخصي (الملف الشخصي) ومقدار بيانات إعداد التقارير المرتبطة بهذا الملف الشخصي، فطلب البحث الذي يتسبب في حدوث الخطأ 500 أو 503 لملف شخصي واحد لن يتسبب بالضرورة في حدوث خطأ لطلب البحث نفسه بملف شخصي مختلف.

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

التراجع التزايدي هو عملية يُعيد فيها العميل محاولة إجراء طلب غير ناجح بشكل دوري على مدار فترة زمنية متزايدة. وهي استراتيجية عادية لمعالجة الأخطاء لتطبيقات الشبكة. تم تصميم Management 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."