Cloud NDB로 마이그레이션

App Engine 위치

App Engine은 리전을 기반으로 합니다. 즉, 앱을 실행하는 인프라가 특정 리전에 위치해 있으며 해당 리전 내의 모든 영역에서 중복으로 사용할 수 있도록 Google이 관리합니다.

앱을 실행하는 리전을 선택하는 데 있어 중요한 기준은 지연 시간, 가용성 또는 내구성 요구사항입니다. 일반적으로 앱 사용자와 가장 가까운 리전을 선택할 수 있지만 App Engine을 사용할 수 있는 위치와 앱에서 사용하는 다른 Google Cloud 제품 및 서비스의 위치도 고려해야 합니다. 여러 위치에서 서비스를 사용하면 앱의 지연 시간과 가격 책정에 영향을 미칠 수 있습니다.

앱의 리전을 설정한 후에는 변경할 수 없습니다.

App Engine 애플리케이션을 이미 만든 경우 다음 중 한 가지 방법으로 해당 리전을 볼 수 있습니다.

Cloud NDB는 App Engine NDB를 대체하는 Python용 클라이언트 라이브러리입니다. App Engine NDB는 Python 2 앱이 Datastore 데이터베이스에서 데이터를 저장하고 쿼리할 수 있도록 합니다. Cloud NDB는 Python 2 및 Python 3 앱에서 동일한 데이터베이스의 데이터를 저장하고 쿼리할 수 있지만 데이터베이스를 관리하는 제품은 Datastore에서 Datastore 모드의 Firestore로 변경되었습니다. Cloud NDB 라이브러리는 App Engine NDB로 생성된 모든 데이터에 액세스할 수 있지만 Cloud NDB를 사용하여 저장된 일부 구조화된 데이터 유형은 App Engine NDB로 액세스할 수 없습니다. 따라서 Cloud NDB로 마이그레이션하면 되돌릴 수 없는 것으로 간주됩니다.

앱을 Python 3으로 업그레이드하기 전에 Cloud NDB로 마이그레이션하는 것이 좋습니다. 이러한 증분적인 마이그레이션 방식은 마이그레이션 프로세스 전반에 걸쳐 앱을 작동 및 테스트 가능한 상태로 유지할 수 있게 해줍니다.

Cloud NDB는 App Engine NDB의 기능을 대체하므로 Datastore 모드에서 Firestore의 새 기능을 지원하지 않습니다. 새 Python 3 앱은 Cloud NDB 대신 Datastore 모드 클라이언트 라이브러리를 사용하는 것이 좋습니다.

Cloud NDB에 대한 자세한 내용은 GitHub의 다음 페이지를 참조하세요.

App Engine NDB와 Cloud NDB 비교

유사점:

  • Cloud NDB는 App Engine NDB에서 지원되는 거의 모든 기능을 지원하며, 메서드 구문에 미묘한 차이만 있을 뿐입니다.

차이점:

  • App Engine Python 2.7 런타임 관련 서비스를 사용하는 App Engine NDB API는 Cloud NDB에서 업데이트되거나 삭제되었습니다.

  • Python 3 및 Django의 새로운 기능으로 인해 google.appengine.ext.ndb.django_middleware가 필요하지 않습니다. 대신 몇 줄의 코드만으로 손쉽게 미들웨어를 작성할 수 있습니다.

  • App Engine NDB에서는 앱과 Datastore 데이터베이스가 동일한 Google Cloud 프로젝트에 있어야 하며 App Engine이 사용자 인증 정보를 자동으로 제공합니다. Cloud NDB는 클라이언트를 제대로 인증하면 모든 프로젝트의 Datastore 모드 데이터베이스에 액세스할 수 있습니다. 다른 Google Cloud API 및 클라이언트 라이브러리와도 일치합니다.

  • Cloud NDB는 App Engine Memcache 서비스를 사용하여 데이터를 캐시하지 않습니다.

    대신 Cloud NDB는 Memorystore, Redis Labs 또는 기타 시스템에서 관리하는 Redis 인메모리 데이터 스토어에서 데이터를 캐시할 수 있습니다. 현재 Redis 데이터 저장소만 지원되지만 Cloud NDB는 추상적인 GlobalCache 인터페이스에서 캐싱을 일반화하고 정의했으며 이를 통해 구체적인 추가 구현을 지원할 수 있습니다.

    Redis용 Memorystore에 액세스하려면 앱에서 서버리스 VPC 액세스를 사용해야 합니다.

    Redis용 Memorystore와 서버리스 VPC 액세스 모두 무료 등급을 제공하지 않으며 이러한 제품은 앱 리전에서 제공되지 않을 수 있습니다. 자세한 내용은 마이그레이션을 시작하기 전에를 참조하세요.

차이점의 전체 목록은 Cloud NDB GitHub 프로젝트의 마이그레이션 참고 사항에서 확인할 수 있습니다.

코드 샘플:

마이그레이션을 시작하기 전에

마이그레이션을 시작하기 전에 다음 사항이 선행되어야 합니다.

  1. 아직 하지 않은 경우 Google Cloud와 호환되는 Python 버전을 사용하도록 Python 개발 환경을 설정하고 격리된 Python 환경을 만드는 테스트 도구를 설치하세요.

  2. 데이터 캐시 필요성 판단

  3. 데이터를 캐시해야 하는 경우 서버리스 VPC 액세스 및 Redis용 Memorystore에서 앱의 리전을 지원하는지 확인

  4. Datastore 모드 권한 이해

데이터 캐시 필요성 판단

앱에서 데이터를 캐시해야 하는 경우 Redis용 Memorystore와 서버리스 VPC 액세스에는 무료 등급이 없으며 모든 Google Cloud 리전을 지원하지 않음을 이해합니다.

일반적으로 다음과 같습니다.

  • 앱에서 동일한 데이터를 자주 읽는 경우 캐싱으로 지연 시간을 줄일 수 있습니다.

  • 앱이 제공하는 요청이 많을수록 캐싱이 큰 영향을 미칠 수 있습니다.

현재 캐싱된 데이터를 얼마나 사용하고 있는지 확인하려면 Memcache 대시보드에서 캐시 적중과 누락의 비율을 확인하세요. 비율이 높으면 데이터 캐시를 사용하는 것이 앱의 지연 시간을 줄이는 데 큰 영향을 미칠 수 있습니다.

App Engine Memcache로 이동

가격 책정에 대한 자세한 내용은 Memorystore 가격 책정서버리스 VPC 액세스 가격 책정을 참조하세요.

앱 리전 확인

데이터를 캐시해야 하는 경우 Redis용 Memorystore 및 서버리스 VPC 액세스에서 앱의 리전을 지원하는지 확인하세요.

  1. Google Cloud 콘솔의 App Engine 대시보드 상단에 표시되는 앱 리전을 확인합니다.

    App Engine으로 이동

    리전은 페이지 상단의 앱 URL 바로 아래에 표시됩니다.

  2. 앱이 서버리스 VPC 액세스에서 지원되는 리전에 있는지 확인합니다.

  3. 커넥터 만들기 페이지로 이동한 후 리전 목록에서 지역을 확인하여 앱이 Redis용 Memorystore에서 지원되는 리전에 있는지 확인합니다.

    서버리스 VPC 액세스로 이동

앱이 Redis용 Memorystore 및 서버리스 VPC 액세스에서 지원하는 리전에 없는 경우 다음을 수행합니다.

  1. Google Cloud 프로젝트를 만듭니다.

  2. 프로젝트에서 새 App Engine 앱을 만들고 지원되는 리전을 선택합니다.

  3. 앱이 새 프로젝트에서 사용하는 Google Cloud 서비스를 만듭니다.

    또는 기존 프로젝트의 기존 서비스를 사용하도록 앱을 업데이트할 수도 있지만 다른 프로젝트 및 리전에서 서비스를 사용하면 가격 책정 및 리소스 사용이 다를 수 있습니다. 자세한 내용은 각 서비스의 문서를 참조하세요.

  4. 앱을 새 프로젝트에 배포합니다.

Datastore 모드 권한 이해

Google Cloud 서비스와의 모든 상호작용은 승인을 받아야 합니다. 예를 들어 Datastore 모드 데이터베이스에 데이터를 저장하거나 쿼리하려면 앱에서 데이터베이스에 액세스하도록 승인된 계정의 사용자 인증 정보를 제공해야 합니다.

기본적으로 앱은 앱과 동일한 프로젝트에 있는 데이터베이스에 액세스하도록 승인된 App Engine 기본 서비스 계정의 사용자 인증 정보를 제공합니다.

다음 조건 중 하나라도 해당하는 경우 사용자 인증 정보를 명시적으로 제공하는 대체 인증 기술을 사용해야 합니다.

  • 앱과 Datastore 모드 데이터베이스가 서로 다른 Google Cloud 프로젝트에 있는 경우

  • 기본 App Engine 서비스 계정에 할당된 역할이 변경된 경우

대체 인증 기술에 대한 자세한 내용은 서버 간 프로덕션 애플리케이션용 인증 설정을 참조하세요.

마이그레이션 프로세스 개요

Cloud NDB로 마이그레이션하려면 다음 안내를 따르세요.

  1. Python 앱을 업데이트합니다.

    1. Cloud NDB 클라이언트 라이브러리를 설치합니다.

    2. import 문을 업데이트하여 Cloud NDB에서 모듈을 가져옵니다.

    3. Cloud NDB 클라이언트를 만드는 코드를 추가합니다. 클라이언트는 앱의 환경 변수를 읽고 데이터를 사용하여 Datastore 모드로 인증할 수 있습니다.

    4. 클라이언트의 런타임 컨텍스트를 사용하여 스레드 간에 캐시와 트랜잭션을 분리하는 코드를 추가합니다.

    5. 더 이상 지원되지 않는 메서드와 속성을 사용하는 코드를 삭제하거나 업데이트합니다.

  2. 캐싱 사용 설정

  3. 업데이트를 테스트합니다.

  4. App Engine에 앱을 배포합니다.

    앱을 변경할 때와 마찬가지로 트래픽 분할을 사용하여 트래픽을 천천히 늘려보세요. 앱을 면밀히 모니터링하여 데이터베이스에 문제가 없는 것을 확인한 후 더 많은 트래픽을 업데이트된 앱으로 라우팅합니다.

Python 앱 업데이트

Python 앱용 Cloud NDB 라이브러리 설치

App Engine Python 앱에 Cloud NDB 클라이언트 라이브러리를 설치하려면 다음 안내를 따르세요.

  1. app.yaml 파일을 업데이트합니다. 사용 중인 Python 버전에 해당하는 안내를 따르세요.

    Python 2

    Python 2 앱의 경우 최신 버전의 grpcio, setuptools 라이브러리를 추가하세요.

    다음은 app.yaml 파일의 예시입니다.

    runtime: python27
    threadsafe: yes
    api_version: 1
    
    libraries:
    - name: grpcio
      version: latest
    - name: setuptools
      version: latest
    

    Python 3

    Python 3 앱의 경우 지원되는 Python 3 버전을 사용하여 runtime 요소를 지정하고 불필요한 줄을 삭제합니다. 예를 들어 app.yaml 파일은 다음과 같이 표시될 수 있습니다.

    runtime: python310 # or another support version
    

    Python 3 런타임은 라이브러리를 자동으로 설치하므로 이전 Python 2 런타임의 기본 제공 라이브러리를 지정할 필요가 없습니다. 마이그레이션 시 Python 3 앱이 다른 기존 번들 서비스를 사용하는 경우 app.yaml 파일을 그대로 둡니다.

  2. requirements.txt 파일을 업데이트합니다. 사용 중인 Python 버전에 해당하는 안내를 따르세요.

    Python 2

    Cloud NDB용 Cloud 클라이언트 라이브러리를 requirements.txt 파일의 종속 항목 목록에 추가합니다.

    google-cloud-ndb
    

    그런 다음 pip install -t lib -r requirements.txt를 실행하여 앱에 사용 가능한 라이브러리 목록을 업데이트합니다.

    Python 3

    Cloud NDB용 Cloud 클라이언트 라이브러리를 requirements.txt 파일의 종속 항목 목록에 추가합니다.

    google-cloud-ndb
    

    App Engine은 Python 3 런타임에서 앱 배포 중에 이러한 종속 항목을 자동으로 설치하므로, lib 폴더가 있는 경우 이를 삭제하세요.

  3. Python 2 앱의 경우 앱에서 lib 디렉터리에 지정된 기본 제공 또는 복사된 라이브러리를 사용한다면 appengine_config.py 파일에서 해당 경로를 지정해야 합니다.

    import pkg_resources
    from google.appengine.ext import vendor
    
    # Set PATH to your libraries folder.
    PATH = 'lib'
    # Add libraries installed in the PATH folder.
    vendor.add(PATH)
    # Add libraries to pkg_resources working set to find the distribution.
    pkg_resources.working_set.add_entry(PATH)
    

    pkg_resources 모듈을 사용하여 앱이 클라이언트 라이브러리의 올바른 배포를 사용하는지 확인합니다.

    앞의 예시의 appengine_config.py 파일은 lib 폴더가 현재 작업 디렉터리에 있다고 가정합니다. lib가 항상 현재 작업 디렉터리에 있다는 것을 보장할 수 없으면 lib 폴더에 전체 경로를 지정합니다. 예를 들면 다음과 같습니다.

    import os
    path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
    

    앱을 배포할 때 App Engine은 appengine_config.py 파일에 지정된 디렉터리의 모든 라이브러리를 업로드합니다.

import 문 업데이트

NDB 모듈의 위치가 google.cloud.ndb로 이동했습니다. 다음 표와 같이 앱의 import 문을 업데이트합니다.

삭제 바꾸기
from google.appengine.ext import ndb from google.cloud import ndb

Cloud NDB 클라이언트 만들기

Google Cloud API를 기반으로 하는 다른 클라이언트 라이브러리와 마찬가지로 Cloud NDB 사용의 첫 번째 단계는 Client 객체를 만드는 것입니다. 클라이언트에는 Datastore 모드에 연결하는 데 필요한 사용자 인증 정보와 기타 데이터가 포함되어 있습니다. 예를 들면 다음과 같습니다.

from google.cloud import ndb

client = ndb.Client()

앞에서 설명한 기본 승인 시나리오에서 Cloud NDB 클라이언트는 Datastore 모드와 상호작용하도록 승인된 App Engine의 기본 서비스 계정의 사용자 인증 정보를 포함합니다. 이 기본 시나리오에서 작업하지 않는 경우 사용자 인증 정보를 제공하는 방법에 대한 자세한 내용은 애플리케이션 기본 사용자 인증 정보(ADC)를 참조하세요.

클라이언트의 런타임 컨텍스트 사용

Datastore 모드와 상호작용하는 데 필요한 사용자 인증 정보를 제공하는 것 외에도 Cloud NDB 클라이언트에는 런타임 컨텍스트를 반환하는 context() 메서드가 포함되어 있습니다. 런타임 컨텍스트는 다른 동시 Datastore 모드 상호작용에서 캐싱 및 트랜잭션 요청을 격리합니다.

Datastore 모드와의 모든 상호작용은 NDB 런타임 컨텍스트 내에서 발생해야 합니다. 모델 정의 만들기는 Datastore 모드와 상호작용하지 않으므로 Cloud NDB 클라이언트를 만들고 런타임 컨텍스트를 검색하기 전에 모델 클래스를 정의한 다음 요청 핸들러의 런타임 컨텍스트를 사용하여 데이터베이스에서 데이터를 가져올 수 있습니다.

예를 들면 다음과 같습니다.

from google.cloud import ndb


class Book(ndb.Model):
    title = ndb.StringProperty()


client = ndb.Client()


def list_books():
    with client.context():
        books = Book.query()
        for book in books:
            print(book.to_dict())

멀티스레드 앱

Cloud NDB 클라이언트가 반환하는 런타임 컨텍스트는 단일 스레드에만 적용됩니다. 앱이 단일 요청에 멀티스레드를 사용하는 경우 Cloud NDB 라이브러리를 사용할 각 스레드에 대해 별도의 런타임 컨텍스트를 검색해야 합니다.

WSGI 프레임워크에서 런타임 컨텍스트 사용

웹 앱에서 WSGI 프레임워크를 사용하는 경우 런타임 컨텍스트를 검색하는 미들웨어 객체를 만든 다음 미들웨어 객체에 앱을 래핑하여 모든 요청에 대해 새로운 런타임 컨텍스트를 자동으로 만들 수 있습니다.

다음은 Flask와 함께 미들웨어를 사용하는 예시입니다.

  • middleware 메서드는 NDB 클라이언트의 런타임 컨텍스트 내에 WSGI 미들웨어 객체를 생성합니다.

  • Flask 앱은 미들웨어 객체로 래핑됩니다.

  • Flask는 각 요청을 미들웨어 객체를 통해 전달하며 이 객체는 요청마다 새로운 NDB 런타임 컨텍스트를 가져옵니다.

from flask import Flask

from google.cloud import ndb


client = ndb.Client()


def ndb_wsgi_middleware(wsgi_app):
    def middleware(environ, start_response):
        with client.context():
            return wsgi_app(environ, start_response)

    return middleware


app = Flask(__name__)
app.wsgi_app = ndb_wsgi_middleware(app.wsgi_app)  # Wrap the app in middleware.


class Book(ndb.Model):
    title = ndb.StringProperty()


@app.route("/")
def list_books():
    books = Book.query()
    return str([book.to_dict() for book in books])

Django에서 런타임 컨텍스트 사용

App Engine NDB 라이브러리에서 제공하는 Django 미들웨어는 Cloud NDB 라이브러리에서 지원되지 않습니다. 앱에서 이 미들웨어(google.appengine.ext.ndb.django_middleware)를 사용한 경우 다음 단계에 따라 앱을 업데이트하세요.

  1. Django의 미들웨어 시스템을 사용하여 요청마다 새로운 런타임 컨텍스트를 만듭니다.

    아래 예시를 참조하세요.

    • ndb_django_middleware 메서드는 Cloud NDB 클라이언트를 만듭니다.

    • middleware 메서드는 NDB 클라이언트의 런타임 컨텍스트 내에 미들웨어 객체를 생성합니다.

    from google.cloud import ndb
    
    
    # Once this middleware is activated in Django settings, NDB calls inside Django
    # views will be executed in context, with a separate context for each request.
    def ndb_django_middleware(get_response):
        client = ndb.Client()
    
        def middleware(request):
            with client.context():
                return get_response(request)
    
        return middleware
    
    
  2. Django settings.py 파일에서 MIDDLEWARE 설정을 업데이트하여 google.appengine.ext.ndb.NdbDjangoMiddleware 대신 새로 만든 미들웨어를 나열합니다.

이제 Django가 MIDDLEWARE 설정에 나열된 미들웨어 객체를 통해 각 요청을 전달하며, 이 객체는 각 요청에 대해 새로운 NDB 런타임 컨텍스트를 검색합니다.

삭제되거나 변경된 NDB API의 코드 업데이트

App Engine 관련 API 및 서비스를 사용하는 NDB API가 Cloud NDB 라이브러리에서 업데이트되거나 삭제되었습니다.

코드가 다음 NDB API 중 하나를 사용하는 경우 코드를 업데이트해야 합니다.

모델 및 모델 속성

google.appengine.ext.ndb.Model의 다음 메서드는 더 이상 사용할 수 없는 App Engine 관련 API를 사용하므로 Cloud NDB 라이브러리에서 사용할 수 없습니다.

삭제된 API 대체
Model.get_indexes
Model.get_indexes_async
없음
Model._deserialize
Model._serialize
없음
Model.make_connection 없음

다음 표에서는 Cloud NDB 라이브러리에서 변경된 특정 google.appengine.ext.ndb.Model 속성을 설명합니다.

속성 변경
TextProperty google.cloud.ndb.TextProperty의 색인을 생성할 수 없습니다. google.cloud.ndb.TextProperty.indexed를 설정하려고 하면 NotImplementedError가 발생합니다.
StringProperty StringProperty는 항상 색인이 생성됩니다. google.cloud.ndb.StringProperty.indexed를 설정하려고 하면 NotImplementedError가 발생합니다.
생성자의 name 또는 kind 인수가 있는 모든 속성. unicode가 Python 3에서 str로 대체되었으므로 name 또는 kindstr 데이터 유형이어야 합니다.

다음 표의 클래스와 메서드는 더 이상 사용할 수 없는 App Engine 관련 리소스를 사용하므로 더 이상 사용할 수 없습니다.

삭제된 API 대체
google.appengine.ext.ndb.msgprop.MessageProperty
google.appengine.ext.ndb.msgprop.EnumProperty
없음

이러한 객체를 만들려고 하면 NotImplementedError가 발생합니다.

google.appengine.ext.ndb.model.Property:
_db_get_value
_db_set_value
_db_set_compressed_meaning
_db_set_uncompressed_meaning
__creation_counter_global
없음

이러한 메서드는 변경된 Datastore 모드 프로토콜 버퍼를 사용합니다.

Model.make_connection 없음

google.appengine.ext.ndb.Key의 다음 메서드는 Cloud NDB 라이브러리에서 사용할 수 없습니다. 이러한 메서드는 더 이상 지원되지 않는 DB Datastore API와 키를 주고받는 데 사용되었습니다(DB는 App Engine NDB의 전신).

삭제된 API 대체
Key.from_old_key
Key.to_old_key
없음

또한 다음과 같은 변경 사항이 있습니다.

App Engine NDB Cloud NDB
종류 및 문자열 ID는 500바이트 미만이어야 합니다. 종류 및 문자열 ID는 1,500바이트 미만이어야 합니다.
Key.app()은 키를 만들 때 지정한 프로젝트 ID를 반환합니다. google.cloud.ndb.Key.app()에서 반환한 값은 생성자에 전달된 원래 ID와 다를 수 있습니다. s~example과 같은 프리픽스가 붙은 앱 ID가 App Engine의 기존 식별자이기 때문입니다. example과 같은 동일한 프로젝트 ID로 대체되었습니다.

쿼리

App Engine NDB와 마찬가지로 Cloud NDB는 QueryOptions 클래스(google.cloud.ndb.query.QueryOptions)를 사용하면 각 쿼리에 대해 재정의하는 대신 특정 쿼리 옵션 집합을 재사용할 수 있습니다. 하지만 Cloud NDB의 QueryOptionsgoogle.appengine.datastore.datastore_rpc.Configuration에서 상속되지 않으므로 ...datastore_rpc.Configuration 메서드를 지원하지 않습니다.

또한 google.appengine.datastore.datastore_query.Ordergoogle.cloud.ndb.query.PropertyOrder로 대체되었습니다. Order와 마찬가지로 PropertyOrder 클래스를 사용하면 여러 쿼리 간에 정렬 순서를 지정할 수 있습니다. PropertyOrder 생성자는 Order의 생성자와 동일합니다. 클래스 이름만 변경되었습니다.

삭제된 API 대체
google.appengine.datastore.datastore_rpc.Configuration:
deadline(value)
on_completion(value)
read_policy(value)
force_writes(value)
max_entity_groups_per_rpc(value)
max_allocate_ids_keys(value)
max_rpc_bytes(value)
max_get_keys(value)
max_put_entities(value)
max_delete_keys(value)

이러한 메서드에 대한 설명은 소스 코드를 참조하세요.

없음
google.appengine.ext.ndb.Order
예시:
order=Order(-Account.birthday, Account.name)
google.cloud.ndb.PropertyOrder
예시:
google.cloud.ndb.PropertyOrder(-Account.birthday, Account.name)

Utils

ndb.utils 모듈(google.appengine.ext.ndb.utils)은 더 이상 사용할 수 없습니다. 이 모듈의 대부분의 메서드는 App Engine NDB 내부에 있었지만 새 ndb의 구현 차이로 인해 일부 메서드가 삭제되었으며 다른 메서드는 새로운 Python 3 기능으로 인해 사용되지 않습니다.

예를 들어 이전 utils 모듈의 위치 데코레이터는 함수 또는 메서드의 첫 번째 n 인수만 위치일 수 있다고 선언했습니다. 그러나 Python 3는 키워드 전용 인수를 사용하여 이를 수행할 수 있습니다. 이전에는 다음과 같이 작성되었습니다.

@utils.positional(2)
def function1(arg1, arg2, arg3=None, arg4=None)
  pass

Python 3에서는 다음과 같이 작성할 수 있습니다.

def function1(arg1, arg2, *, arg3=None, arg4=None)
  pass

네임스페이스

네임스페이스를 사용하면 멀티테넌트 애플리케이션이 동일한 Datastore 모드 데이터베이스를 사용하는 동안 각 테넌트에 대해 별도의 데이터 사일로를 사용할 수 있습니다. 즉, 각 테넌트는 자체 네임스페이스 아래에 데이터를 저장합니다.

App Engine 관련 google.appengine.api.namespacemanager를 사용하는 대신 Cloud NDB 클라이언트를 만들 때 기본 네임스페이스를 지정한 다음 클라이언트의 런타임 컨텍스트 내에서 Cloud NDB 메서드를 호출하여 기본 네임스페이스를 사용합니다. 네임스페이스를 지원하는 다른 Google Cloud API와 동일한 패턴을 따릅니다.

삭제된 API 대체
google.appengine.api.namespace_manager.namespace_manager.set_namespace(str)
google.appengine.api.namespacemanager.getnamespace()
client=google.cloud.ndb.Client(namespace="my namespace")

with client.context() as context:
    key = ndb.Key("SomeKind", "SomeId")
       
또는
key-non-default-namespace=ndb.Key("SomeKind," "AnotherId",
namespace="non-default-nspace")
기타 모든 google.appengine.api.namespacemanager 메서드 없음

Tasklets

이제 TaskletReturn 예외를 발생시키는 대신 표준 return 문을 사용하여 결과를 반환할 수 있습니다. 예를 들면 다음과 같습니다.

App Engine NDB 라이브러리 Cloud NDB 라이브러리
        @ndb.tasklet
        def get_cart():
          cart = yield
        CartItem.query().fetch_async()
          raise Return(cart)
       
        @ndb.tasklet
        def get_cart():
          cart = yield
        CartItem.query().fetch_async()
          return cart
        

Return 예외를 발생시켜 Cloud NDB에서 결과를 반환할 수는 있지만 권장되지 않습니다.

또한 Cloud NDB 라이브러리에서 NDB 컨텍스트를 만들고 사용하는 방법이 변경되어 다음 Tasklets 메서드와 서브클래스를 더 이상 사용할 수 없습니다.

삭제된 API 대체
google.appengine.api.ext.ndb.tasklets:
add_flow_exception
make_context
make_default_context
set_context
없음
google.appengine.api.ext.ndb.tasklets:
QueueFuture
ReducedFuture
SerialQueueFuture
없음

예외

Cloud NDB 라이브러리의 google.cloud.ndb.exceptions 모듈에는 App Engine NDB 라이브러리의 동일한 예외가 많이 포함되어 있지만 이전 예외 중 일부는 새 라이브러리에서 사용할 수 없습니다. 다음 표에는 더 이상 사용할 수 없는 예외가 나와 있습니다.

삭제된 API 대체
google.appengine.api.datastore_errors:
BadKeyError
BadPropertyError
CommittedButStillApplying
EntityNotFoundError
InternalError
NeedIndexError
QueryNotFoundError
ReferencePropertyResolveError
Timeout
TransactionFailedError
TransactionNotFoundError
google.cloud.ndb.exceptions

데이터 캐싱 사용 설정

Cloud NDB는 Memorystore, Redis Labs 또는 기타 시스템에서 관리하는 Redis 인메모리 데이터 스토어에서 데이터를 캐시할 수 있습니다. 이 가이드에서는 Redis용 Memorystore를 사용하여 데이터를 캐시하는 방법을 설명합니다.

  1. 서버리스 VPC 액세스 설정

  2. Redis용 Memorystore 설정

  3. 앱에 Redis 연결 URL을 추가합니다.

  4. RedisCache 객체를 만듭니다.

서버리스 VPC 액세스 설정

앱은 서버리스 VPC 액세스 커넥터를 통해서만 Memorystore와 통신할 수 있습니다. 서버리스 VPC 액세스 커넥터를 설정하려면 다음 안내를 따르세요.

  1. 서버리스 VPC 액세스 커넥터 만들기

  2. 커넥터를 사용하도록 앱을 구성합니다.

Redis용 Memorystore 설정

Redis용 Memorystore를 설정하려면 다음 안내를 따르세요.

  1. Memorystore에서 Redis 인스턴스를 만듭니다. 인스턴스를 만들 때 다음을 수행합니다.

  2. 만들려는 Redis 인스턴스의 IP 주소와 포트 번호를 기록합니다. 이 정보는 Cloud NDB에 데이터 캐싱을 사용 설정할 때 사용됩니다.

    앱 업데이트를 배포하려면 gcloud beta 명령어를 사용해야 합니다. 베타 명령어만 VPC 커넥터를 사용하도록 앱을 업데이트할 수 있습니다.

Redis 연결 URL 추가

앱의 app.yaml 파일에 REDIS_CACHE_URL 환경 변수를 추가하여 Redis 캐시에 연결할 수 있습니다. REDIS_CACHE_URL의 값은 다음 형식입니다.

redis://IP address for your instance:port

예를 들어 앱의 app.yaml 파일에 다음 줄을 추가할 수 있습니다.

     env_variables:
      REDIS_CACHE_URL: redis://10.0.0.3:6379

Redis 캐시 객체 생성 및 사용

REDIS_CACHE_URL을 환경 변수로 설정한 경우 코드 한 줄로 RedisCache 객체를 만든 다음 런타임 컨텍스트를 설정할 때 Client.context()에 전달하여 캐시를 사용할 수 있습니다.

client = ndb.Client()
global_cache = ndb.RedisCache.from_environment()

with client.context(global_cache=global_cache):
  books = Book.query()
  for book in books:
      print(book.to_dict())

REDIS_CACHE_URL을 환경 변수로 설정하지 않으면 Redis 클라이언트를 구성하고 클라이언트를 ndb.RedisCache() 생성자에 전달해야 합니다. 예를 들면 다음과 같습니다.

global_cache = ndb.RedisCache(redis.StrictRedis(host=IP-address, port=redis_port))

Cloud NDB 라이브러리는 이미 Redis 클라이언트 라이브러리에 종속되어 있으므로 Redis 클라이언트 라이브러리에 대한 종속 항목을 선언할 필요가 없습니다.

Redis 클라이언트를 구성하는 예시는 Memorystore 샘플 애플리케이션을 참조하세요.

업데이트 테스트

App Engine에 배포하기 전에 테스트 데이터베이스를 설정하고 로컬에서 앱을 실행하려면 다음 안내를 따르세요.

  1. Datastore 모드 로컬 에뮬레이터를 실행하여 데이터를 저장하고 검색합니다.

    앱이 프로덕션 Datastore 모드 환경 대신 에뮬레이터에 연결되도록 환경 변수 설정 안내를 따라야 합니다.

    데이터베이스에 사전 로드된 데이터로 테스트를 시작하려면 에뮬레이터로 데이터를 가져올 수도 있습니다.

  2. 로컬 개발 서버를 사용하여 앱을 실행합니다.

    로컬 개발 중에 GOOGLE_CLOUD_PROJECT 환경 변수가 올바르게 설정되었는지 확인하려면 다음 매개변수를 사용하여 dev_appserver를 초기화합니다.

    --application=PROJECT_ID

    PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다. gcloud config list project 명령어를 사용하거나 Google Cloud 콘솔에서 프로젝트 페이지를 검토하여 프로젝트 ID를 찾을 수 있습니다.

앱 배포

앱이 로컬 개발 서버에서 오류 없이 실행되면 다음을 수행합니다.

  1. App Engine에서 앱을 테스트합니다.

  2. 앱이 오류 없이 실행되면 트래픽 분할을 사용하여 업데이트된 앱의 트래픽을 천천히 늘립니다. 앱을 면밀히 모니터링하여 데이터베이스에 문제가 없는 것을 확인한 후 더 많은 트래픽을 업데이트된 앱으로 라우팅합니다.

다음 단계