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

Sebaliknya, baru firebase_admin.exceptions modul telah diperkenalkan. API publik di auth , db , instance_id , messaging dan project_management modul sekarang menaikkan contoh exceptions.FirebaseError jenis.

# 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

The exceptions.FirebaseError jenis 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, juga memungkinkan untuk menangkap induk FirebaseError jenis dan kode kesalahan membandingkan.

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 menyatakan subtipe tambahan memanjang dari exceptions.FirebaseError jenis induk (lihat di bawah).

Pedoman umum untuk penanganan error: Menangkap exceptions.FirebaseError ketika 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

The auth.verify_id_token() metode tidak lagi menimbulkan ValueError untuk menunjukkan kesalahan validasi tanda. Sebagai gantinya, Anda akan mendapatkan salah satu jenis kesalahan berikut:

• InvalidIdTokenError
• ExpiredIdTokenError
• RevokedIdTokenError

The InvalidIdTokenError jenis memperluas exceptions.InvalidArgumentError jenis, yang pada gilirannya memperluas exceptions.FirebaseError jenis. 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, auth.verify_session_cookie() metode menimbulkan jenis pengecualian berikut:

• InvalidSessionCookieError
• ExpiredSessionCookieError
• RevokedSessionCookieError

Hirarki kelas dan semantik yang mirip dengan verify_id_token() API.

Token khusus

The create_custom_token() API menimbulkan auth.TokenSignError 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)

Manajemen pengguna

Berikut jenis kesalahan baru telah diperkenalkan ke auth modul:

• 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

Berikut jenis kesalahan baru telah diperkenalkan ke messaging modul.

• 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

Hal ini tidak mungkin lagi untuk menghapus sifat display_name , photo_url , phone_number dan custom_claims dengan menetapkan mereka untuk None . Pengaturan ini untuk None daun sifat ini tidak berubah. Mereka harus secara eksplisit diatur untuk 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)