Admin SDK لدليل ترحيل Python 3.0.0

يقدم الإصدار 3.0.0 من Firebase Admin SDK for Python بعض التغييرات المهمة في واجهة برمجة التطبيقات. بشكل أساسي ، تعد تغييرات API في هذا الإصدار إضافات وتحسينات في معالجة الأخطاء لمصادقة Auth و FCM وميزات Firebase الأخرى.

تغييرات معالجة الأخطاء العامة

تمت إزالة أنواع الاستثناءات التالية:

  • auth.AuthError
  • db.ApiCallError
  • instance_id.ApiCallError
  • messaging.ApiCallError
  • project_management.ApiCallError

بدلاً من ذلك ، تم تقديم وحدة firebase_admin.exceptions جديدة. تثير واجهات برمجة التطبيقات العامة في وحدات auth و db و instance_id و messaging و project_management حالات من exceptions.FirebaseError .

# Before
from firebase_admin import messaging

try:
    messaging.send(build_message())
except messaging.ApiCallError as ex:
    print('Error message:', ex)

# v3
from firebase_admin import exceptions
from firebase_admin import messaging

try:
    messaging.send(build_message())
except exceptions.FirebaseError as ex:
    print('Error message:', ex)
    print('Error code:', ex.code) # Platform-wide error code
    print('HTTP response:', ex.http_response) # requests HTTP response object

يحتوي نوع exceptions.FirebaseError .FirebaseError على العديد من الأنواع الفرعية. يمكن لواجهات برمجة التطبيقات العامة في Admin SDK رفع هذه الأنواع الفرعية فقط. لذلك ، يمكنك كتابة التعليمات البرمجية التي تلتقط نوعًا فرعيًا معينًا وتعالج الأخطاء بشكل أكثر دقة. فمثلا:

try:
    messaging.send(build_message())
except exceptions.InvalidArgumentError as ex:
    print(ex) # One or more arguments were invalid
except exceptions.UnavailableError as ex:
    print(ex) # FCM service is temporarily down
except exceptions.FirebaseError as ex:
    print(ex) # All other errors

بدلاً من اكتشاف أنواع أخطاء معينة ، من الممكن أيضًا اكتشاف نوع FirebaseError الأصلي ومقارنة رموز الخطأ.

try:
    messaging.send(build_message())
except exceptions.FirebaseError as ex:
    if ex.code == exceptions.INVALID_ARGUMENT:
        print(ex) # One or more arguments were invalid
    elif ex.code == exceptions.UNAVAILABLE:
        print(ex) # FCM service is temporarily down
    else:
        print(ex) # All other errors

قد تعلن كل وحدة عن أنواع فرعية إضافية تمتد من exceptions.FirebaseError . نوع أصل FirebaseError (انظر أدناه).

إرشادات عامة لمعالجة الخطأ: exceptions.FirebaseError الصيد. قاعدة إطلاق النار خطأ عندما لا تحتاج إلى التفريق بين حالات الخطأ. ابحث عن فئة فرعية أو رمز خطأ أكثر تحديدًا عندما تحتاج إلى التمييز بين حالات الخطأ.

خطأ في معالجة التغييرات

التحقق من JWT

لم تعد طريقة auth.verify_id_token() ترفع ValueError للإشارة إلى أخطاء التحقق من صحة الرمز المميز. بدلاً من ذلك ، ستحصل على أحد أنواع الأخطاء التالية:

  • InvalidIdTokenError
  • ExpiredIdTokenError
  • RevokedIdTokenError

يقوم النوع InvalidIdTokenError exceptions.FirebaseError exceptions.InvalidArgumentError ExpiredIdTokenError و RevokedIdTokenError إلى توسيع InvalidIdTokenError .

# Before
from firebase_admin import auth

try:
    auth.verify_id_token(id_token, check_revoked=True)
except ValueError as ex:
    print('Error message:', ex)

 # v3
from firebase_admin import auth

# Coarse-grained error handling
try:
    auth.verify_id_token(id_token, check_revoked=True)
except auth.InvalidIdTokenError as ex:
    print('ID token is invalid, expired or revoked')

# Fine-grained error handling
try:
    auth.verify_id_token(id_token, check_revoked=True)
except auth.RevokedIdTokenError as ex:
    print('ID token has been revoked')
except auth.ExpiredIdTokenError as ex:
    print('ID token is expired')
except auth.InvalidIdTokenError as ex:
    print('ID token is invalid')

وبالمثل ، تثير طريقة auth.verify_session_cookie() أنواع الاستثناءات التالية:

  • InvalidSessionCookieError
  • ExpiredSessionCookieError
  • RevokedSessionCookieError

يتشابه التسلسل الهرمي للدلالات والدلالات مع واجهة برمجة التطبيقات verify_id_token() .

الرموز المخصصة

تعمل واجهة برمجة التطبيقات create_custom_token() على رفع auth.TokenSignError بدلاً من ValueError للإشارة إلى حالات الفشل.

# Before
from firebase_admin import auth

try:
    auth.create_custom_token(uid)
except ValueError as ex:
    print('Error message:', ex)

 # v3
from firebase_admin import auth

try:
    auth.create_custom_token(uid)
except auth.TokenSignError as ex:
    print('Error message:', ex)

إدارةالمستخدم

تم تقديم أنواع الأخطاء الجديدة التالية إلى وحدة auth :

  • EmailAlreadyExistsError
  • InvalidDynamicLinkDomainError
  • PhoneNumberAlreadyExistsError
  • UidAlreadyExistsError
  • UnexpectedResponseError
  • UserNotFoundError
# Before
from firebase_admin import auth

try:
    auth.get_user(uid)
except auth.AuthError as ex:
    if ex.code == auth.USER_NOT_FOUND_ERROR:
        print('Specified user does not exist')
    else:
        print('Something else went wrong')

 # v3
from firebase_admin import auth
from firebase_admin import exceptions

try:
    auth.get_user(uid)
except auth.UserNotFoundError as ex:
    print('Specified user does not exist')
except exceptions.FirebaseError as ex:
    print('Something else went wrong')

FCM خطأ في معالجة التغييرات

تم تقديم أنواع الأخطاء الجديدة التالية إلى وحدة messaging .

  • QuotaExceededError
  • SenderIdMismatchError
  • ThirdPartyAuthError
  • UnregisteredError
# Before
from firebase_admin import messaging

try:
    messaging.send(msg)
except messaging.ApiCallError as ex:
    if ex.code == 'registration-token-not-registered':
        print('Registration token has been unregistered')
    elif ex.code == 'invalid-argument':
        print('One or more arguments invalid')
    else:
        print('Something else went wrong')

# v3
from firebase_admin import exceptions
from firebase_admin import messaging

try:
    messaging.send(msg)
except messaging.UnregisteredError as ex:
    print('Registration token has been unregistered')
except exceptions.InvalidArgumentError as ex:
    print('One or more arguments invalid')
except exceptions.FirebaseError as ex:
    print('Something else went wrong')

حذف خاصية المستخدم

لم يعد من الممكن حذف الخصائص display_name و photo_url و phone_number و custom_claims من خلال تعيينها على None . تعيين هذه على None يترك هذه الخصائص دون تغيير. يجب تعيينها بشكل صريح للمصادقة. auth.DELETE_ATTRIBUTE لحذفها.

# Before
from firebase_admin import auth

auth.update_user(uid, display_name=None, photo_url=None)

 # v3
from firebase_admin import auth

auth.update_user(
  uid, display_name=auth.DELETE_ATTRIBUTE, photo_url=auth.DELETE_ATTRIBUTE)