Guide de migration du SDK Admin 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 apportées à 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'exceptions suivants ont été supprimés :

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

Au lieu de cela, un nouveau firebase_admin.exceptions module a été introduit. API publiques dans auth , db , instance_id , messaging et project_management modules soulèvent maintenant des instances de exceptions.FirebaseError de type.

# 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 exceptions.FirebaseError type a 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 exemple:

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'attraper les types d'erreur spécifique, il est également possible d'attraper le parent FirebaseError type et les codes d'erreur comparer.

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 étendant à partir du exceptions.FirebaseError type parent (voir ci - dessous).

Directive générale pour la gestion des erreurs: Catch exceptions.FirebaseError lorsque vous n'avez pas besoin de faire la différence entre 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

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

  • InvalidIdTokenError
  • ExpiredIdTokenError
  • RevokedIdTokenError

Le InvalidIdTokenError Type étend la exceptions.InvalidArgumentError type, qui à son tour prolonge la exceptions.FirebaseError de type. 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, le auth.verify_session_cookie() méthode soulève les types d'exceptions suivantes:

  • InvalidSessionCookieError
  • ExpiredSessionCookieError
  • RevokedSessionCookieError

Hiérarchie des classes et la sémantique sont similaires à la verify_id_token() API.

Jetons personnalisés

Le create_custom_token() API augmente auth.TokenSignError au lieu de ValueError pour indiquer les défaillances.

# 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'erreur suivants ont été introduits au auth Module:

  • 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')

Erreur FCM lors de la gestion des modifications

Les nouveaux types d'erreur suivants ont été introduits à la messaging module.

  • 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é de l'utilisateur

Il est plus possible de supprimer des propriétés display_name , photo_url , phone_number et custom_claims en les mettant à None . La définition de ces à None feuilles ces propriétés inchangées. Elles doivent être définies explicitement 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)