معالجة أخطاء المشرف SDK

تنقسم أخطاء SDK للمشرف إلى فئتين:

1. أخطاء البرمجة: هي أخطاء البرمجة والتكوين في تطبيق المستخدم. تحدث هذه الأخطاء في الغالب بسبب الاستخدام غير الصحيح لـ SDK (مثل تمرير قيمة null إلى طريقة لا تقبل القيم null )، وأخطاء التكوين الأخرى على مستوى مشروع Firebase أو SDK (بيانات الاعتماد المفقودة، وسلسلة معرف المشروع غير الصحيحة، وما إلى ذلك) على).
2. أخطاء واجهة برمجة التطبيقات (API): تتضمن هذه الأخطاء العديد من الأخطاء القابلة للاسترداد التي تحدث أثناء تنفيذ SDK، وجميع الأخطاء التي تنشأ في خدمات الواجهة الخلفية لـ Firebase، والأخطاء العابرة الأخرى (مثل انتهاء المهلات) التي قد تحدث أثناء إجراء مكالمات RPC.

تشير Admin SDK إلى أخطاء البرمجة عن طريق ظهور خطأ أصلي في النظام الأساسي المعني.

• Java: يرمي مثيلات IllegalArgumentException أو NullPointerException أو أي نوع خطأ مدمج مماثل في وقت التشغيل.
• Python: رفع مثيلات ValueError أو TypeError أو أي نوع آخر من الأخطاء المضمنة.
• Go: إرجاع خطأ عام.
• .NET: يرمي مثيلات ArgumentException أو ArgumentNullException أو أي نوع خطأ مدمج مماثل.

في معظم المواقف، لا ينبغي عليك التعامل بشكل صريح مع أخطاء البرمجة. بدلاً من ذلك، يجب عليك إصلاح التعليمات البرمجية والتكوين الخاص بك لتجنب أخطاء البرمجة تمامًا. خذ بعين الاعتبار مقتطف Java التالي:

String uid = getUserInput();

UserRecord user = FirebaseAuth.getInstance().getUser(uid);

إذا قام الأسلوب getUserInput() بإرجاع سلاسل null أو فارغة، فستطرح واجهة برمجة التطبيقات FirebaseAuth.getUser() API IllegalArgumentException . بدلاً من معالجتها بشكل صريح، يمكنك التخفيف من المشكلة عن طريق التأكد من أن أسلوب getUserInput() لا يُرجع مطلقًا سلسلة UID غير صالحة. إذا لم يكن ذلك ممكنًا، فقم بتنفيذ التحقق من الوسيطة اللازمة في التعليمات البرمجية الخاصة بك على النحو التالي:

String uid = getUserInput();
if (Strings.isNullOrEmpty(uid)) {
    log.warn("UID must not be null or empty");
    return;
}

UserRecord user = FirebaseAuth.getInstance().getUser(uid);

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

عادةً ما يركز الجزء الأكبر من جهود معالجة الأخطاء على معالجة أخطاء واجهة برمجة التطبيقات (API) . بعض هذه الأخطاء قابلة للاسترداد، مثل الأخطاء التي نتجت عن خدمة غير متاحة مؤقتًا، وبعضها يمكن توقعه أثناء تدفق تنفيذ البرنامج العادي، مثل اكتشاف رموز المعرف غير الصالحة أو منتهية الصلاحية. يوضح الجزء المتبقي من هذا الدليل كيفية تمثيل Admin SDK لأخطاء واجهة برمجة التطبيقات هذه، والخيارات المتنوعة المتاحة للتعامل معها.

هيكل خطأ API

يتكون خطأ API من المكونات التالية:

1. خطا بالكود
2. رسالة خطأ
3. رمز خطأ الخدمة (اختياري)
4. استجابة HTTP (اختياري)

نضمن أن كل خطأ في واجهة برمجة التطبيقات (API) يحتوي على رمز خطأ ورسالة خطأ. تحتوي بعض أخطاء واجهة برمجة التطبيقات (API) أيضًا على رمز خطأ خدمة خاص بواجهة برمجة التطبيقات (API) التي تسببت في حدوث الخطأ. على سبيل المثال، تحتوي بعض الأخطاء التي تم إنشاؤها بواسطة Firebase Auth API على رمز خطأ في الخدمة خاص بـ Firebase Auth. إذا كان الخطأ نتيجة استجابة خطأ HTTP من خدمة الواجهة الخلفية، فإن خطأ واجهة برمجة التطبيقات (API) يحتوي أيضًا على استجابة HTTP المقابلة. يمكن استخدام هذا لفحص الرؤوس والمحتويات الدقيقة للاستجابة الأصلية، وهو أمر مفيد لتصحيح الأخطاء أو التسجيل أو تنفيذ منطق أكثر تعقيدًا لمعالجة الأخطاء.

توفر جميع تطبيقات Admin SDK باستثناء Node.js واجهات برمجة التطبيقات التي تتيح الوصول إلى مكونات أخطاء واجهة برمجة التطبيقات المذكورة أعلاه.

أنواع الأخطاء وواجهات برمجة التطبيقات حسب اللغة

جافا

في Java، تعمل جميع أخطاء واجهة برمجة التطبيقات (API) على توسيع فئة FirebaseException . يمكنك الوصول إلى رمز الخطأ ورسالة الخطأ واستجابة HTTP الاختيارية من هذه الفئة الأساسية.

public class FirebaseException extends Exception {
    @NonNull
    public ErrorCode getErrorCode() {
        // ...
    }

    @NonNull
    public String getMessage() {
        // ...
    }

    @Nullable
    public IncomingHttpResponse getHttpResponse() {
        // ...
    }
}

توفر واجهات برمجة التطبيقات (APIs) التي تكشف رموز خطأ الخدمة فئات فرعية خاصة بواجهة برمجة التطبيقات (API) لـ FirebaseException . على سبيل المثال، تم الإعلان عن جميع الطرق العامة في FirebaseAuth API لرمي مثيلات FirebaseAuthException . يمكنك الوصول إلى رمز خطأ الخدمة من هذه الفئة المشتقة.

public class FirebaseAuthException extends FirebaseException {
    @Nullable
    public AuthErrorCode getAuthErrorCode() {
        // ...
    }
}

بايثون

في Python، تعمل جميع أخطاء واجهة برمجة التطبيقات (API) على توسيع فئة exceptions.FirebaseError . يمكنك الوصول إلى رمز الخطأ ورسالة الخطأ واستجابة HTTP الاختيارية من هذه الفئة الأساسية.

class FirebaseError(Exception):
    @property
    def code(self):
          # ...

    @property
    def message(self):
          # ...

    @property
    def http_response(self):
          # ...

علاوة على ذلك، تقدم Python Admin SDK فئات مشتقة منفصلة لكل رمز خطأ. ونحن نشير إليها على أنها فئات أخطاء النظام الأساسي .

class InvalidArgumentError(FirebaseError):
    # ...

class NotFoundError(FirebaseError):
    # ...

يمكنك إما اكتشاف FirebaseError في التعليمات البرمجية الخاصة بك والتحقق من code الخاصة به، أو إجراء فحص isinstance() مقابل فئة خطأ في النظام الأساسي. أو يمكنك كتابة تعليمات برمجية لاكتشاف أنواع أخطاء معينة في النظام الأساسي مباشرةً. من المرجح أن يؤدي النهج الأخير إلى كود معالجة الأخطاء الأكثر قابلية للقراءة.

توفر واجهات برمجة التطبيقات التي تكشف رموز خطأ الخدمة فئات فرعية خاصة بواجهة برمجة التطبيقات لفئات أخطاء النظام الأساسي. على سبيل المثال، قد تؤدي جميع الطرق العامة في وحدة auth إلى ظهور أنواع أخطاء خاصة بواجهة برمجة التطبيقات (API)، مثل auth.UserNotFoundError و auth.ExpiredIdTokenError .

class UserNotFoundError(exceptions.NotFoundError):
    # …

class ExpiredIdTokenError(exceptions.InvalidArgumentError):
    # ...

يذهب

توفر Go Admin SDK حزمة errorutils التي تحتوي على سلسلة من الوظائف التي تسمح باختبار رموز الأخطاء.

package errorutils

func IsInvalidArgument(err error) bool {
    // ...
}

func IsNotFound(err error) bool {
    // ...
}

رسالة الخطأ هي ببساطة السلسلة التي يتم إرجاعها بواسطة الدالة Error() الخاصة بالخطأ. يمكن الوصول إلى استجابة HTTP الاختيارية عن طريق استدعاء الدالة errorutils.HTTPResponse() ، والتي تقوم بإرجاع *http.Response .

من الآمن تمرير nil أو أي قيمة خطأ أخرى إلى وظائف التحقق من الأخطاء في الحزمة errorutils . فهي تُرجع true إذا كانت وسيطة الإدخال تحتوي بالفعل على رمز الخطأ المعني، وتُرجع false لكل شيء آخر. الدالة HTTPResponse() لها سلوك مشابه، باستثناء أنها تُرجع nil بدلاً من false .

توفر واجهات برمجة التطبيقات التي تكشف رموز خطأ الخدمة وظائف التحقق من الأخطاء الخاصة بواجهة برمجة التطبيقات في الحزم المقابلة. على سبيل المثال، توفر حزمة auth الوظائف IsUserNotFound() و IsExpiredIDTokenError() .

.شبكة

في .NET، تعمل جميع أخطاء واجهة برمجة التطبيقات (API) على توسيع فئة FirebaseException . يمكنك الوصول إلى رمز خطأ النظام الأساسي ورسالة الخطأ واستجابة HTTP الاختيارية من هذه الفئة الأساسية.

public class FirebaseException : Exception {

    public ErrorCode ErrorCode { get; }

    public String Message { get; }

    public HttpResponseMessage HttpResponse { get; }
}

توفر واجهات برمجة التطبيقات (APIs) التي تكشف رموز خطأ الخدمة فئات فرعية خاصة بواجهة برمجة التطبيقات (API) لـ FirebaseException . على سبيل المثال، تم الإعلان عن جميع الأساليب العامة في FirebaseAuth API لطرح مثيلات FirebaseAuthException . يمكنك الوصول إلى رمز خطأ الخدمة من هذه الفئة المشتقة.

public class FirebaseAuthException : FirebaseException {

    public AuthErrorCode AuthErrorCode { get; }
}

رموز خطأ النظام الأساسي

تعد رموز الأخطاء شائعة عبر جميع خدمات Firebase وGoogle Cloud Platform. يوضح الجدول التالي جميع رموز الأخطاء المحتملة في النظام الأساسي. وهذه قائمة مستقرة، ومن المتوقع أن تظل دون تغيير لفترة طويلة.

يمكن أن تؤدي معظم واجهات برمجة التطبيقات (APIs) فقط إلى مجموعة فرعية من رموز الخطأ المذكورة أعلاه. على أية حال، ليس من المتوقع منك أن تتعامل بشكل صريح مع كل رموز الأخطاء هذه عند تنفيذ معالجات الأخطاء الخاصة بك. ستهتم معظم التطبيقات فقط برموز خطأ محددة واحدة أو اثنين وتتعامل مع كل شيء آخر على أنه فشل عام وغير قابل للاسترداد.

رموز الخطأ الخاصة بالخدمة

مصادقة Firebase

المراسلة السحابية من Firebase

إعادة المحاولة التلقائية

تقوم Admin SDK تلقائيًا بإعادة محاولة بعض الأخطاء قبل كشف هذه الأخطاء للمستخدمين. بشكل عام، تتم إعادة محاولة أنواع الأخطاء التالية بشفافية:

• جميع أخطاء واجهة برمجة التطبيقات (API) الناتجة عن استجابات HTTP 503 (الخدمة غير متاحة).
• بعض أخطاء API الناتجة عن استجابات HTTP 500 (خطأ داخلي في الخادم).
• معظم أخطاء الإدخال/الإخراج ذات المستوى المنخفض (تم رفض الاتصال، أو إعادة تعيين الاتصال، وما إلى ذلك).

سيعيد SDK محاولة كل خطأ من الأخطاء المذكورة أعلاه حتى 5 مرات (المحاولة الأصلية + 4 مرات إعادة المحاولة) مع التراجع الأسي. يمكنك تنفيذ آليات إعادة المحاولة الخاصة بك على مستوى التطبيق إذا كنت تريد ذلك، ولكن هذا غير مطلوب عادةً.

إعادة المحاولة-بعد الدعم

تأتي تطبيقات Go و.NET الخاصة بـ Admin SDK مع دعم للتعامل مع رأس HTTP Retry-After . أي أنه إذا كانت استجابة الخطأ التي أرسلتها خوادم الواجهة الخلفية تحتوي على رأس Retry-After القياسي، فسوف تحترم SDK ذلك عند إعادة المحاولة طالما أن مدة الانتظار المحددة ليست طويلة جدًا. إذا كان رأس Retry-After يشير إلى مدة انتظار طويلة جدًا، فسوف يتجاوز SDK عمليات إعادة المحاولة ويلقي خطأ واجهة برمجة التطبيقات (API) المناسب.

لا يدعم Python Admin SDK حاليًا رأس Retry-After ، ويدعم فقط التراجع الأسي البسيط.

أمثلة على معالجة أخطاء واجهة برمجة التطبيقات

تنفيذ معالج الأخطاء العام

في معظم الحالات، ما تريده هو معالج أخطاء عام يلتقط نطاقًا واسعًا من الأخطاء لمنع الإنهاء غير المتوقع لتدفق البرنامج بسبب خطأ في واجهة برمجة التطبيقات (API). عادةً ما تقوم معالجات الأخطاء هذه بتسجيل الأخطاء لأغراض التدقيق، أو استدعاء بعض إجراءات معالجة الأخطاء الافتراضية الأخرى لجميع أخطاء واجهة برمجة التطبيقات (API) التي تمت مواجهتها. إنهم ليسوا مهتمين بالضرورة برموز الخطأ المختلفة أو الأسباب التي قد تكون سببت الخطأ.

try {
  FirebaseToken token = FirebaseAuth.getInstance().verifyIdToken(idToken);
  performPrivilegedOperation(token.getUid());
} catch (FirebaseAuthException ex) {
  System.err.println("Failed to verify ID token: " + ex.getMessage());
}

try:
  token = auth.verify_id_token(idToken)
  perform_privileged_pperation(token.uid)
except exceptions.FirebaseError as ex:
  print(f'Failed to verify ID token: {ex}')

token, err := client.VerifyIDToken(ctx, idToken)
if err != nil {
  log.Printf("Failed to verify ID token: %v", err)
  return
}

performPrivilegedOperation(token)

try
{
  var token = await FirebaseAuth.DefaultInstance.VerifyIdTokenAsync(idToken);
  PerformPrivilegedOperation(token.getUid());
}
catch (FirebaseAuthException ex) 
{
  Conole.WriteLine($"Failed to verify ID token: {ex.Message}");
}

التحقق من رموز الخطأ

في بعض الحالات، قد ترغب في فحص رموز الخطأ الدقيقة، واستدعاء إجراءات مختلفة لمعالجة الأخطاء مع مراعاة السياق. في المثال التالي، لدينا معالج أخطاء يقوم بتسجيل المزيد من رسائل الخطأ المحددة بناءً على رمز خطأ الخدمة.

try {
  FirebaseToken token = FirebaseAuth.getInstance().verifyIdToken(idToken);
  performPrivilegedOperation(token.getUid());
} catch (FirebaseAuthException ex) {
  if (ex.getAuthErrorCode() == AuthErrorCode.ID_TOKEN_EXPIRED) {
    System.err.println("ID token has expired");
  } else if (ex.getAuthErrorCode() == AuthErrorCode.ID_TOKEN_INVALID) {
    System.err.println("ID token is malformed or invalid");
  } else {
    System.err.println("Failed to verify ID token: " + ex.getMessage());
  }
}

try:
  token = auth.verify_id_token(idToken)
  perform_privileged_operation(token.uid)
except auth.ExpiredIdTokenError:
  print('ID token has expired')
except auth.InvalidIdTokenError:
  print('ID token is malformed or invalid')
except exceptions.FirebaseError as ex:
  print(f'Failed to verify ID token: {ex}')

token, err := client.VerifyIDToken(ctx, idToken)
if auth.IsIDTokenExpired(err) {
  log.Print("ID token has expired")
  return
}
if auth.IsIDTokenInvalid(err) {
  log.Print("ID token is malformed or invalid")
  return
}
if err != nil {
  log.Printf("Failed to verify ID token: %v", err)
  return
}

performPrivilegedOperation(token)

try
{
  var token = await FirebaseAuth.DefaultInstance.VerifyIdTokenAsync(idToken);
  PerformPrivilegedOperation(token.getUid());
}
catch (FirebaseAuthException ex)
{
  if (ex.AuthErrorCode == AuthErrorCode.ExpiredIdToken)
  {
    Console.WriteLine("ID token has expired");
  }
  else if (ex.AuthErrorCode == AuthErrorCode.InvalidIdToken)
  {
    Console.WriteLine("ID token is malformed or invalid");
  }
  else
  {
    Conole.WriteLine($"Failed to verify ID token: {ex.Message}");
  }
}

إليك مثال آخر حيث نتحقق من رموز أخطاء المستوى الأعلى والخدمة:

try {
  FirebaseMessaging.getInstance().send(createMyMessage());
} catch (FirebaseMessagingException ex){
  if (ex.getMessagingErrorCode() == MessagingErrorCode.UNREGISTERED) {
    System.err.println("App instance has been unregistered");
    removeTokenFromDatabase();
  } else if (ex.getErrorCode() == ErrorCode.Unavailable) {
    System.err.println("FCM service is temporarily unavailable");
    scheduleForRetryInAnHour();
  } else {
    System.err.println("Failed to send notification: " + ex.getMessage());
  }
}

try:
  messaging.send(create_my_message())
except messaging.UnregisteredError:
  print('App instance has been unregistered')
  remove_token_from_database()
except exceptions.UnavailableError:
  print('FCM service is temporarily unavailable')
  schedule_for_retry_in_an_hour()
except exceptions.FirebaseError as ex:
  print(f'Failed to send notification: {ex}')

_, err := client.Send(ctx, createMyMessage())
if messaging.IsUnregistered(err) {
  log.Print("App instance has been unregistered")
  removeTokenFromDatabase()
  return
}
if errorutils.IsUnavailable(err) {
  log.Print("FCM service is temporarily unavailable")
  scheduleForRetryInAnHour()
  return
}
if err != nil {
  log.Printf("Failed to send notification: %v", err)
  return
}

try
{
  await FirebaseMessaging.DefaultInstance.SendAsync(createMyMessage());
}
catch (FirebaseMessagingException ex)
{
  if (ex.MessagingErrorCode == MessagingErrorCode.UNREGISTERED)
  {
    Console.WriteLine("App instance has been unregistered");
    removeTokenFromDatabase();
  }
  else if (ex.ErrorCode == ErrorCode.Unavailable)
  {
    Console.WriteLine("FCM service is temporarily unavailable");
    scheduleForRetryInAnHour();
  }
  else
  {
    Console.WriteLine($"Failed to send notification: {ex.Message}");
  }
}

الوصول إلى استجابة HTTP

في بعض الحالات النادرة، قد ترغب في فحص استجابة خطأ HTTP التي تم إرجاعها بواسطة خدمة الواجهة الخلفية وتنفيذ بعض إجراءات معالجة الأخطاء عليها. يكشف Admin SDK عن رؤوس ومحتويات استجابات الأخطاء هذه. عادةً ما يتم إرجاع محتوى الاستجابة كسلسلة أو تسلسل بايت خام، ويمكن تحليله إلى أي تنسيق هدف ضروري.

try {
  FirebaseMessaging.getInstance().send(createMyMessage());
} catch (FirebaseMessagingException ex){
  IncomingHttpResponse response = ex.getHttpResponse();
  if (response != null) {
    System.err.println("FCM service responded with HTTP " + response.getStatusCode());

    Map<String, Object> headers = response.getHeaders();
    for (Map.Entry<String, Object> entry : headers.entrySet()) {
      System.err.println(">>> " + entry.getKey() + ": " + entry.getValue());
    }

    System.err.println(">>>");
    System.err.println(">>> " + response.getContent());
  }
}

try:
  messaging.send(create_my_message())
except exceptions.FirebaseError as ex:
  response = ex.http_response
  if response is not None:
    print(f'FCM service responded with HTTP {response.status_code}')

    for key, value in response.headers.items():
      print(f'>>> {key}: {value}')

    print('>>>')
    print(f'>>> {response.content}')

_, err := client.Send(ctx, createMyMessage())
if resp := errorutils.HTTPResponse(err); resp != nil {
  log.Printf("FCM service responded with HTTP %d", resp.StatusCode)

  for key, value := range resp.Header {
      log.Printf(">>> %s: %v", key, value)
  }

  defer resp.Body.Close()
  b, _ := ioutil.ReadAll(resp.Body)
  log.Print(">>>")
  log.Printf(">>> %s", string(b))

  return
}

try
{
  await FirebaseMessaging.DefaultInstance.SendAsync(createMyMessage());
}
catch (FirebaseMessagingException ex)
{
  var response = ex.HttpResponse
  if response != null
  {
    Console.WriteLine($"FCM service responded with HTTP { response.StatusCode}");

    var headers = response.Headers;
    for (var entry in response.Headers)
    {
      Console.WriteLine($">>> {entry.Key}: {entry.Value}");
    }

    var body = await response.Content.ReadAsString();
    Console.WriteLine(">>>");
    Console.WriteLine($">>> {body}");
  }
}