Panduan migrasi Admin SDK untuk Python 3.0.0

Versi 3.0.0 dari Firebase Admin SDK untuk Python memperkenalkan beberapa perubahan penting dalam API. Pada dasarnya, perubahan API dalam rilis ini adalah tambahan dan peningkatan pada penanganan error untuk Auth, FCM, dan fitur Firebase lainnya.

Perubahan penanganan error umum

Jenis pengecualian berikut telah dihapus:

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

Sebagai gantinya, modul firebase_admin.exceptions yang baru telah diperkenalkan. API Publik di modul auth, db, instance_id, messaging, dan project_management sekarang meningkatkan instance jenis 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

Jenis exceptions.FirebaseError memiliki banyak subjenis. API Publik di Admin SDK hanya dapat meningkatkan subjenis ini. Oleh sebab itu, Anda dapat menulis kode yang menangkap subjenis tertentu dan menangani error secara lebih terperinci. Contoh:

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

Selain menangkap jenis error tertentu, Anda juga dapat menangkap jenis FirebaseError induk dan membandingkan kode error.

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

Setiap modul dapat mendeklarasikan subjenis tambahan yang diperluas dari jenis induk exceptions.FirebaseError (lihat di bawah).

Pedoman umum untuk penanganan error: Tangkap exceptions.FirebaseError saat Anda tidak perlu membedakan antara kondisi error. Temukan subclass error atau kode error yang lebih spesifik jika Anda perlu membedakan kondisi error.

Perubahan penanganan error autentikasi

Verifikasi JWT

Metode auth.verify_id_token() tidak lagi memunculkan ValueError untuk menunjukkan error validasi token. Sebaliknya, Anda akan mendapatkan salah satu dari jenis error berikut:

• InvalidIdTokenError
• ExpiredIdTokenError
• RevokedIdTokenError

Jenis InvalidIdTokenError memperluas jenis exceptions.InvalidArgumentError, yang selanjutnya memperluas jenis exceptions.FirebaseError. ExpiredIdTokenError dan RevokedIdTokenError memperluas 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')

Demikian pula, metode auth.verify_session_cookie() memunculkan jenis pengecualian berikut:

• InvalidSessionCookieError
• ExpiredSessionCookieError
• RevokedSessionCookieError

Hierarki kelas dan semantik mirip dengan API verify_id_token().

Token kustom

API create_custom_token() memunculkan auth.TokenSignError dan bukan ValueError untuk menunjukkan kegagalan.

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

Pengelolaan pengguna

Jenis error baru berikut telah diperkenalkan ke modul 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')

Perubahan penanganan error FCM

Jenis error baru berikut telah diperkenalkan ke modul 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')

Penghapusan properti pengguna

Anda tidak dapat lagi menghapus properti display_name, photo_url, phone_number, dan custom_claims dengan menetapkannya ke None. Dengan menyetelnya ke None, properti ini tidak akan berubah. Semuanya harus secara eksplisit disetel ke auth.DELETE_ATTRIBUTE untuk menghapusnya.

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