Google 致力于为黑人社区推动种族平等。查看具体举措

Guide de migration du SDK d'administration pour Python 3.0.0

La version 3.0.0 du SDK Firebase Admin pour Python introduit des modifications importantes dans l'API. Principalement, les modifications de l'API dans cette version sont des ajouts et des améliorations dans la gestion des erreurs pour Auth, FCM et d'autres fonctionnalités de Firebase.

Modifications générales de la gestion des erreurs

Les types d'exception suivants ont été supprimés :

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

Au lieu de cela, un nouveau module firebase_admin.exceptions a été introduit. Les API publiques des modules auth , db , instance_id , messaging et project_management lèvent désormais des instances de type 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

Le type exceptions.FirebaseError comporte de nombreux sous-types. Les API publiques du SDK Admin ne peuvent générer que ces sous-types. Par conséquent, vous pouvez écrire du code qui intercepte un sous-type spécifique et gère les erreurs de manière plus granulaire. Par example:

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

Au lieu d'intercepter des types d'erreur spécifiques, il est également possible d'intercepter le type parent FirebaseError et de comparer les codes d'erreur.

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

Chaque module peut déclarer des sous-types supplémentaires s'étendant du type parent exceptions.FirebaseError (voir ci-dessous).

Directive générale pour la gestion des erreurs : interceptez exceptions.FirebaseError lorsque vous n'avez pas besoin de différencier les conditions d'erreur. Recherchez une sous-classe d'erreur ou un code d'erreur plus spécifique lorsque vous devez différencier les conditions d'erreur.

Modifications de la gestion des erreurs d'authentification

Vérification JWT

La méthode auth.verify_id_token() ne déclenche plus ValueError pour indiquer des erreurs de validation de jeton. Au lieu de cela, vous obtiendrez l'un des types d'erreur suivants :

  • InvalidIdTokenError
  • ExpiredIdTokenError
  • RevokedIdTokenError

Le type InvalidIdTokenError étend le type exceptions.InvalidArgumentError , qui à son tour étend le type exceptions.FirebaseError . ExpiredIdTokenError et RevokedIdTokenError étendent 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')

De même, la méthode auth.verify_session_cookie() lève les types d'exceptions suivants :

  • InvalidSessionCookieError
  • ExpiredSessionCookieError
  • RevokedSessionCookieError

La hiérarchie et la sémantique des classes sont similaires à l'API verify_id_token() .

Jetons personnalisés

L'API create_custom_token() déclenche auth.TokenSignError au lieu de ValueError pour indiquer les échecs.

# 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)

Gestion des utilisateurs

Les nouveaux types d'erreurs suivants ont été introduits dans le module d' 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')

Modifications de gestion des erreurs FCM

Les nouveaux types d'erreur suivants ont été introduits dans le module de 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')

Suppression de la propriété utilisateur

Il n'est plus possible de supprimer les propriétés display_name , photo_url , phone_number et custom_claims en les définissant sur None . Les définir sur None laisse ces propriétés inchangées. Ils doivent être explicitement définis sur auth.DELETE_ATTRIBUTE pour les supprimer.

# 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)