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

Guia de migração do Admim SDK para Python 3.0.0

A versão 3.0.0 do SDK Admin do Firebase para Python apresenta algumas mudanças importantes na API. Principalmente, as alterações da API nesta versão são adições e melhorias no tratamento de erros para Auth, FCM e outros recursos do Firebase.

Mudanças gerais de tratamento de erros

Os seguintes tipos de exceção foram removidos:

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

Em vez disso, um novo firebase_admin.exceptions foi introduzido módulo. APIs públicas na auth , db , instance_id , messaging e project_management módulos agora levantar 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

O exceptions.FirebaseError tipo tem muitos subtipos. As APIs públicas no Admin SDK só podem aumentar esses subtipos. Portanto, você pode escrever um código que captura um subtipo específico e trata os erros de maneira mais granular. Por exemplo:

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

Em vez de pegar tipos de erro específica, também é possível pegar o pai FirebaseError tipo e códigos de erro 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 pode declarar subtipos adicionais que se prolongam a partir da exceptions.FirebaseError tipo pai (ver abaixo).

Orientação geral para o tratamento de erros: Catch exceptions.FirebaseError quando você não precisa diferenciar entre as condições de erro. Procure uma subclasse de erro ou código de erro mais específico quando precisar diferenciar as condições de erro.

Erro de autenticação no tratamento de alterações

Verificação JWT

O auth.verify_id_token() método deixou de suscitar ValueError para indicar erros de validação de tokens. Em vez disso, você obterá um dos seguintes tipos de erro:

  • InvalidIdTokenError
  • ExpiredIdTokenError
  • RevokedIdTokenError

O InvalidIdTokenError tipo estende a exceptions.InvalidArgumentError tipo, que por sua vez se estende a exceptions.FirebaseError tipo. ExpiredIdTokenError e RevokedIdTokenError estender 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')

Da mesma forma, o auth.verify_session_cookie() método levanta os seguintes tipos de exceção:

  • InvalidSessionCookieError
  • ExpiredSessionCookieError
  • RevokedSessionCookieError

Hierarquia de classes e semântica são semelhantes ao verify_id_token() API.

Tokens personalizados

O create_custom_token() API levanta auth.TokenSignError vez de ValueError para indicar falhas.

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

Gestão de usuários

Os seguintes novos tipos de erros foram introduzidos para a auth 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')

Erro do FCM ao lidar com alterações

Os seguintes novos tipos de erros foram introduzidos para o 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')

Exclusão de propriedade do usuário

Não é mais possível excluir propriedades display_name , photo_url , phone_number e custom_claims , definindo-as para None . A definição destas para None folhas essas propriedades inalteradas. Eles devem ser explicitamente definido para auth.DELETE_ATTRIBUTE para excluí-los.

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