Admin SDK for Python 3.0.0 移行ガイド

Firebase Admin SDK for Python のバージョン 3.0.0 では、API にいくつかの重要な変更が導入されています。主に、このリリースの API の変更は、Auth、FCM、その他の Firebase 機能に関するエラー処理の追加と改善です。

一般的なエラー処理の変更点

次の例外タイプが削除されました。

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

代わりに、新しい firebase_admin.exceptions モジュールが導入されました。auth、db、instance_id、messaging、project_management モジュールの公開 API で、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 タイプには多くのサブタイプがあります。Admin SDK の公開 API では、これらのサブタイプのみ生成できます。そのため、特定のサブタイプをキャッチし、エラーをもっときめ細かく処理するためのコードを記述できます。例:

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 親タイプから拡張される追加のサブタイプを宣言できます（以下を参照）。

エラー処理に関する一般的なガイドライン: エラー条件を区別する必要がない場合は、exceptions.FirebaseError をキャッチします。エラー条件を区別する必要がある場合は、より具体的なエラーサブクラスまたはエラーコードを探します。

Auth エラー処理の変更点

JWT 検証

auth.verify_id_token() メソッドは、トークンの検証エラーを示す ValueError を生成しなくなりました。代わりに、次のいずれかのエラータイプが表示されます。

InvalidIdTokenError
ExpiredIdTokenError
RevokedIdTokenError

InvalidIdTokenError タイプは、exceptions.FirebaseError タイプを拡張する exceptions.InvalidArgumentError タイプを拡張します。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 は、ValueError の代わりに auth.TokenSignError を生成して失敗を示します。

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