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.
Alterações gerais no 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 módulo firebase_admin.exceptions foi introduzido. APIs públicas nos módulos auth , db , instance_id , messaging e project_management agora geram instâncias do tipo 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
O tipo exceptions.FirebaseError tem muitos subtipos. APIs públicas no SDK Admin só podem gerar esses subtipos. Portanto, você pode escrever um código que capture um subtipo específico e trate os erros de forma 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 capturar tipos de erro específicos, também é possível capturar o tipo FirebaseError pai e comparar os códigos de erro.
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 estendem do tipo pai exceptions.FirebaseError (veja abaixo).
Diretriz geral para tratamento de erros: Capture exceptions.FirebaseError quando não precisar diferenciar entre 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.
Alterações no tratamento de erros de autenticação
Verificação de JWT
O método auth.verify_id_token() não gera mais ValueError para indicar erros de validação de token. Em vez disso, você receberá um dos seguintes tipos de erro:
-
InvalidIdTokenError -
ExpiredIdTokenError -
RevokedIdTokenError
O tipo InvalidIdTokenError estende o tipo exceptions.InvalidArgumentError , que por sua vez estende o tipo exceptions.FirebaseError . ExpiredIdTokenError e RevokedIdTokenError estendem 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 método auth.verify_session_cookie() gera os seguintes tipos de exceção:
-
InvalidSessionCookieError -
ExpiredSessionCookieError -
RevokedSessionCookieError
A hierarquia de classes e a semântica são semelhantes à API verify_id_token() .
Tokens personalizados
A API create_custom_token() gera auth.TokenSignError em 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)
Gerenciamento de usuários
Os seguintes novos tipos de erro foram introduzidos no módulo de 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')
Alterações no tratamento de erros do FCM
Os novos tipos de erro a seguir foram introduzidos no módulo 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')
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 como None . Defini-los como None deixa essas propriedades inalteradas. Eles devem ser definidos explicitamente como 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)