Catch up on everthing we announced at this year's Firebase Summit. Learn more

Guía de migración del SDK de Admim para Python 3.0.0

La versión 3.0.0 del SDK de Firebase Admin para Python presenta algunos cambios importantes en la API. Principalmente, los cambios de API en esta versión son adiciones y mejoras en el manejo de errores para Auth, FCM y otras funciones de Firebase.

Cambios generales en el manejo de errores

Se han eliminado los siguientes tipos de excepciones:

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

En su lugar, una nueva firebase_admin.exceptions se ha introducido el módulo. API públicas de auth , db , instance_id , messaging y project_management módulos ahora plantean casos de exceptions.FirebaseError tipo.

# 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

El exceptions.FirebaseError tipo tiene muchos subtipos. Las API públicas del SDK de administrador solo pueden generar estos subtipos. Por lo tanto, puede escribir código que capture un subtipo específico y maneje los errores de manera más granular. Por ejemplo:

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

En lugar de la captura de los tipos de error específico, también es posible coger el padre FirebaseError tipo y códigos de error comparar.

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

Cada módulo puede declarar subtipos adicionales que se extienden desde la exceptions.FirebaseError tipo padre (ver abajo).

Pauta general para el tratamiento de errores de captura exceptions.FirebaseError cuando no es necesario diferenciar entre las condiciones de error. Busque una subclase de error o un código de error más específicos cuando necesite diferenciar las condiciones de error.

Cambios en el manejo de errores de autenticación

Verificación JWT

El auth.verify_id_token() método ya no plantea ValueError para indicar los errores de validación de fichas. En su lugar, obtendrá uno de los siguientes tipos de error:

  • InvalidIdTokenError
  • ExpiredIdTokenError
  • RevokedIdTokenError

El InvalidIdTokenError tipo extiende el exceptions.InvalidArgumentError tipo, que a su vez se extiende la exceptions.FirebaseError tipo. ExpiredIdTokenError y RevokedIdTokenError extienden 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')

Del mismo modo, la auth.verify_session_cookie() método plantea los siguientes tipos de excepción:

  • InvalidSessionCookieError
  • ExpiredSessionCookieError
  • RevokedSessionCookieError

Jerarquía de clases y la semántica son similares a la verify_id_token() API.

Tokens personalizados

El create_custom_token() API plantea auth.TokenSignError en lugar de ValueError para indicar fallos.

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

Gestión de usuarios

Los siguientes nuevos tipos de errores se han introducido para la auth del módulo:

  • 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 Error en el manejo de cambios

Los siguientes nuevos tipos de errores se han introducido a la messaging módulo.

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

Eliminación de propiedad de usuario

Ya no es posible eliminar las propiedades display_name , photo_url , phone_number y custom_claims estableciendo su valor a None . Dejarlas en None hojas de estas propiedades sin cambios. Deben establecerse explícitamente a auth.DELETE_ATTRIBUTE para eliminarlos.

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