Przewodnik po migracji Admin SDK do Pythona 3.0.0

Wersja 3.0.0 pakietu Firebase Admin SDK dla Pythona wprowadza kilka ważnych zmian w interfejsie API. Zmiany w interfejsie API w tej wersji to przede wszystkim dodatki i ulepszenia w obsłudze błędów Auth, FCM i innych funkcji Firebase.

Ogólne zmiany w obsłudze błędów

Usunięto następujące typy wyjątków:

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

Zamiast tego wprowadzono nowy moduł firebase_admin.exceptions . Publiczne interfejsy API w modułach auth , db , instance_id , messaging i project_management teraz podnoszą wystąpienia exceptions.FirebaseError typu 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

Typ exceptions.FirebaseError ma wiele podtypów. Publiczne interfejsy API w pakiecie Admin SDK mogą zgłaszać tylko te podtypy. Dlatego możesz napisać kod, który przechwytuje określony podtyp i bardziej szczegółowo obsługuje błędy. Na przykład:

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

Zamiast przechwytywania określonych typów błędów można również przechwycić nadrzędny typ FirebaseError i porównać kody błędów.

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

Każdy moduł może deklarować dodatkowe podtypy wychodzące z typu nadrzędnego exceptions.FirebaseError (patrz niżej).

Ogólne wytyczne dotyczące obsługi błędów: przechwytywanie exceptions.FirebaseError , gdy nie trzeba rozróżniać warunków błędów. Poszukaj bardziej szczegółowej podklasy błędu lub kodu błędu, gdy musisz rozróżnić warunki błędów.

Zmiany w obsłudze błędów uwierzytelniania

Weryfikacja JWT

Metoda auth.verify_id_token() nie wywołuje już ValueError w celu wskazania błędów walidacji tokenu. Zamiast tego otrzymasz jeden z następujących typów błędów:

• InvalidIdTokenError
• ExpiredIdTokenError
• RevokedIdTokenError

Typ InvalidIdTokenError rozszerza typ exceptions.InvalidArgumentError , który z kolei rozszerza typ exceptions.FirebaseError . ExpiredIdTokenError i RevokedIdTokenError rozszerzają 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')

Podobnie metoda auth.verify_session_cookie() wywołuje następujące typy wyjątków:

• InvalidSessionCookieError
• ExpiredSessionCookieError
• RevokedSessionCookieError

Hierarchia i semantyka klas są podobne do funkcji API verify_id_token() .

Tokeny niestandardowe

Funkcja API create_custom_token() auth.TokenSignError zamiast ValueError w celu wskazania błędów.

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

Zarządzanie użytkownikami

W module auth wprowadzono następujące nowe typy błędów:

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

Zmiany w obsłudze błędów FCM

Do modułu messaging wprowadzono następujące nowe typy błędów.

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

Usunięcie właściwości użytkownika

Nie jest już możliwe usuwanie właściwości display_name , photo_url , phone_number i custom_claims przez ustawienie ich na None . Ustawienie ich na None pozostawia te właściwości bez zmian. Aby je usunąć, muszą być jawnie ustawione na 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)