Руководство по миграции Admin SDK для Python 3.0.0

Версия 3.0.0 пакета SDK для администрирования Firebase для Python содержит некоторые важные изменения в API. В первую очередь изменения API в этом выпуске - это добавления и улучшения в обработке ошибок для Auth, FCM и других функций Firebase.

Общие изменения в обработке ошибок

Были удалены следующие типы исключений:

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

Вместо этого новый firebase_admin.exceptions модуль был введен. Общедоступный API , в auth , db , instance_id , обмен messaging и project_management модули в настоящее время поднимают экземпляры 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

exceptions.FirebaseError типа имеет множество подтипов. Общедоступные API в Admin SDK могут только повышать эти подтипы. Таким образом, вы можете написать код, который перехватывает определенный подтип и более детально обрабатывает ошибки. Например:

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

Вместо того , чтобы ловить конкретные тип ошибок, то также можно поймать родительский FirebaseError типа и сравнение кодов ошибок.

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

Каждый модуль может объявить дополнительные подтипы , простирающихся от exceptions.FirebaseError родительского типа (см ниже).

Общее руководство для обработки ошибок: Catch exceptions.FirebaseError , когда вам не нужно различать условие ошибки. Ищите более конкретный подкласс ошибки или код ошибки, когда вам нужно различать условия ошибки.

Изменения в обработке ошибок аутентификации

Проверка JWT

Не auth.verify_id_token() метод больше не вызывает ValueError для указания маркеров ошибки проверки. Вместо этого вы получите один из следующих типов ошибок:

• InvalidIdTokenError
• ExpiredIdTokenError
• RevokedIdTokenError

InvalidIdTokenError тип расширяет exceptions.InvalidArgumentError тип, который в свою очередь расширяет exceptions.FirebaseError тип. ExpiredIdTokenError и RevokedIdTokenError продлить 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')

Аналогичным образом , auth.verify_session_cookie() метод вызывает следующие типы исключений:

• InvalidSessionCookieError
• ExpiredSessionCookieError
• RevokedSessionCookieError

Иерархия классов и семантика похожи на verify_id_token() API.

Пользовательские токены

create_custom_token() API повышает auth.TokenSignError вместо ValueError о сбоях.

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

Управление пользователями

Следующие новые типы ошибок были введены в 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')

Изменения обработки ошибок FCM

Следующие новые типы ошибок были введены в 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')

Удаление свойства пользователя

Это уже невозможно удалить свойства display_name , photo_url , phone_number и custom_claims , установив их в None . Установка их на None листьев эти свойства неизменными. Они должны быть явно установлен в auth.DELETE_ATTRIBUTE , чтобы удалить их.

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