Admin SDK untuk panduan migrasi Python 3.0.0

Versi 3.0.0 dari Firebase Admin SDK untuk Python memperkenalkan beberapa perubahan penting dalam API. Terutama, perubahan API dalam rilis ini adalah penambahan dan peningkatan dalam penanganan kesalahan untuk Auth, FCM, dan fitur Firebase lainnya.

Perubahan penanganan kesalahan umum

Jenis pengecualian berikut telah dihapus:

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

Sebagai gantinya, modul firebase_admin.exceptions baru telah diperkenalkan. API publik dalam modul auth , db , instance_id , messaging , dan project_management kini meningkatkan instance tipe 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 subtipe. API publik di Admin SDK hanya dapat meningkatkan subjenis ini. Oleh karena itu, Anda dapat menulis kode yang menangkap subtipe tertentu dan menangani kesalahan secara lebih terperinci. Sebagai 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

Alih-alih menangkap jenis kesalahan tertentu, Anda juga dapat menangkap jenis induk FirebaseError dan membandingkan kode kesalahan.

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 subtipe tambahan yang diperluas dari exceptions.FirebaseError parent type (lihat di bawah).

Pedoman umum untuk penanganan kesalahan: Tangkap exceptions.FirebaseError saat Anda tidak perlu membedakan antara kondisi kesalahan. Cari subkelas kesalahan atau kode kesalahan yang lebih spesifik saat Anda perlu membedakan kondisi kesalahan.

Perubahan penanganan kesalahan autentik

Verifikasi JWT

Metode auth.verify_id_token() tidak lagi memunculkan ValueError untuk menunjukkan kesalahan validasi token. Sebagai gantinya, Anda akan mendapatkan salah satu jenis kesalahan berikut:

• InvalidIdTokenError
• ExpiredIdTokenError
• RevokedIdTokenError

Jenis InvalidIdTokenError memperluas jenis exceptions.InvalidArgumentError , yang pada gilirannya memperluas jenis exceptions.FirebaseError . ExpiredIdTokenError dan RevokedIdTokenError memperpanjang 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

Hirarki dan semantik kelas mirip dengan API verify_id_token() .

Token khusus

API create_custom_token() memunculkan auth.TokenSignError alih-alih 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)

Manajemen pengguna

Jenis kesalahan 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 kesalahan FCM

Jenis kesalahan 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

Tidak mungkin lagi menghapus properti display_name , photo_url , phone_number dan custom_claims dengan menyetelnya ke None . Menyetel ini ke None membuat properti ini tidak berubah. Mereka 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)