Python 3.0.0용 Admin SDK 마이그레이션 가이드

Python용 Firebase Admin SDK의 버전 3.0.0에는 몇 가지 중요한 API 변경사항이 있습니다. 기본적으로 이 출시 버전에 포함된 API 변경사항은 인증, 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를 포착합니다. 오류 조건을 구분해야 하는 경우 보다 체적인 오류 서브클래스 또는 오류 코드를 찾아보세요.

인증 오류 처리 변경사항

JWT 인증

auth.verify_id_token() 메서드는 더 이상 토큰 검증 오류를 나타내기 위해 ValueError를 발생시키지 않습니다. 대신 다음 오류 유형 중 하나가 표시됩니다.

  • InvalidIdTokenError
  • ExpiredIdTokenError
  • RevokedIdTokenError

InvalidIdTokenError 유형은 exceptions.InvalidArgumentError 유형을 확장합니다. 그러면 exceptions.FirebaseError 유형이 확장됩니다. 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)