Admin SDK für Python 3.0.0-Migrationsanleitung

Version 3.0.0 des Firebase Admin SDK für Python führt einige wichtige Änderungen in der API ein. Die API-Änderungen in dieser Version sind in erster Linie Ergänzungen und Verbesserungen bei der Fehlerbehandlung für Auth, FCM und andere Firebase-Funktionen.

Allgemeine Änderungen bei der Fehlerbehandlung

Die folgenden Ausnahmetypen wurden entfernt:

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

Stattdessen wurde ein neues firebase_admin.exceptions -Modul eingeführt. Öffentliche APIs in den Modulen auth , db , instance_id , messaging und project_management jetzt Instanzen des Typs exceptions.FirebaseError aus.

# 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

Der Typ exceptions.FirebaseError hat viele Untertypen. Öffentliche APIs im Admin SDK können nur diese Untertypen auslösen. Daher können Sie Code schreiben, der einen bestimmten Untertyp abfängt und Fehler detaillierter behandelt. Beispielsweise:

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

Anstatt bestimmte Fehlertypen abzufangen, ist es auch möglich, den übergeordneten FirebaseError -Typ abzufangen und Fehlercodes zu vergleichen.

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

Jedes Modul kann zusätzliche Subtypen deklarieren, die sich vom übergeordneten Typ exceptions.FirebaseError ausdehnen (siehe unten).

Allgemeine Richtlinie für die Fehlerbehandlung: Fangen Sie exceptions.FirebaseError ab, wenn Sie nicht zwischen Fehlerbedingungen unterscheiden müssen. Suchen Sie nach einer spezifischeren Fehlerunterklasse oder einem Fehlercode, wenn Sie Fehlerbedingungen unterscheiden müssen.

Änderungen bei der Behandlung von Authentifizierungsfehlern

JWT-Verifizierung

Die Methode auth.verify_id_token() löst ValueError nicht mehr aus, um Token-Validierungsfehler anzuzeigen. Stattdessen erhalten Sie einen der folgenden Fehlertypen:

• InvalidIdTokenError
• ExpiredIdTokenError
• RevokedIdTokenError

Der Typ InvalidIdTokenError “ erweitert den Typ „ exceptions.InvalidArgumentError “, der wiederum den Typ „ exceptions.FirebaseError “ erweitert. ExpiredIdTokenError und RevokedIdTokenError erweitern 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')

In ähnlicher Weise löst die Methode auth.verify_session_cookie() die folgenden Ausnahmetypen aus:

• InvalidSessionCookieError
• ExpiredSessionCookieError
• RevokedSessionCookieError

Klassenhierarchie und -semantik ähneln denen der verify_id_token() API.

Benutzerdefinierte Token

Die API create_custom_token() löst auth.TokenSignError anstelle von ValueError aus, um Fehler anzuzeigen.

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

Benutzerverwaltung

Die folgenden neuen Fehlertypen wurden in das auth -Modul eingeführt:

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

Änderungen bei der FCM-Fehlerbehandlung

Die folgenden neuen Fehlertypen wurden in das messaging -Modul eingeführt.

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

Löschen von Benutzereigenschaften

Es ist nicht mehr möglich, die Eigenschaften display_name , photo_url , phone_number und custom_claims zu löschen, indem Sie sie auf None setzen. Wenn Sie diese auf None setzen, bleiben diese Eigenschaften unverändert. Sie müssen explizit auf auth.DELETE_ATTRIBUTE gesetzt werden, um sie zu löschen.

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