Google Cloud CLI는 Datastore 모드의 Firestore 애플리케이션을 테스트하는 데 사용할 수 있는 Firestore용 로컬 인메모리 에뮬레이터를 제공합니다. 에뮬레이터는 모든 Datastore 모드 클라이언트 라이브러리에서 사용할 수 있습니다. 에뮬레이터는 로컬 테스트에만 사용해야 합니다.
gcloud emulators firestore를 --database-mode=datastore-mode와 함께 사용하여 Datastore 모드의 Firestore 동작을 테스트합니다.
프로덕션 배포에는 에뮬레이터를 사용하지 마세요. 에뮬레이터는 메모리에만 데이터를 저장하므로 여러 번 실행할 경우 데이터가 유지되지 않습니다.
에뮬레이터 설치
Firestore 에뮬레이터를 설치하려면 gcloud CLI를 설치하고 업데이트합니다.
최신 기능을 이용하려면 gcloud CLI 설치를 업데이트하세요.
gcloud components update
에뮬레이터 실행
다음 명령어를 실행하여 에뮬레이터를 시작합니다.
gcloud emulators firestore start --database-mode=datastore-mode에뮬레이터가 실행되고 있는 호스트와 포트 번호가 출력됩니다.
기본적으로 에뮬레이터는
127.0.0.1:8080사용을 시도합니다. 에뮬레이터를 특정 호스트 및 포트에 결합하려면 선택사항인--host-port플래그를 사용하고, HOST 및 PORT를 바꿉니다.gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORTControl + C단축키를 사용하여 에뮬레이터를 중지합니다.
에뮬레이터에 연결
클라이언트 라이브러리와 앱을 에뮬레이터에 연결하려면 DATASTORE_EMULATOR_HOST 환경 변수를 설정합니다. 이 환경 변수가 설정되면 클라이언트 라이브러리가 자동으로 에뮬레이터에 연결됩니다.
export DATASTORE_EMULATOR_HOST="HOST:PORT"
에뮬레이터로 항목 가져오기
에뮬레이터의 가져오기 기능을 사용하면 항목 내보내기 파일 모음의 항목을 에뮬레이터로 로드할 수 있습니다. 항목 내보내기 파일은 Datastore 모드 데이터베이스 또는 에뮬레이터 인스턴스에서 내보내기를 수행하여 가져올 수 있습니다.
두 가지 방법으로 항목을 에뮬레이터로 가져올 수 있습니다. 첫 번째는 import-data 플래그를 에뮬레이터 시작 명령어에 추가하는 것입니다. 두 번째 방법은 에뮬레이터에 POST 가져오기 요청을 보내는 것입니다. curl 또는 유사한 도구를 사용할 수 있습니다. 다음 예시를 참조하세요.
프로토콜
curl -X POST http://localhost:8080/emulator/v1/projects/[PROJECT_ID]:import \
-H 'Content-Type: application/json' \
-d '{"database":"[DATABASE]", "export_directory":"[EXPORT_DIRECTORY]"}'
에뮬레이터가 다른 포트를 사용하는 경우 localhost:8080을 수정합니다.CLI 플래그
gcloud emulators firestore start --database-mode=datastore-mode --import-data=[EXPORT_DIRECTORY]
각 매개변수는 다음과 같습니다.
[PROJECT_ID]는 프로젝트 ID입니다.[DATABASE]는 데이터베이스 경로입니다. 예를 들어, 기본 데이터베이스가 있는 프로젝트는 다음과 같이 표시됩니다.{"database":"projects/myProject/databases/"}[EXPORT_DIRECTORY]는 항목 내보내기 파일 중overall_export_metadata파일의 경로입니다. 예를 들면 다음과 같습니다.{"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}
에뮬레이터의 항목 내보내기
에뮬레이터의 내보내기 기능을 사용하면 에뮬레이터의 항목을 항목 내보내기 파일 모음에 저장할 수 있습니다. 그런 다음 가져오기 작업을 사용하여 항목 내보내기 파일의 항목을 Datastore 모드 데이터베이스 또는 에뮬레이터 인스턴스로 로드할 수 있습니다.
두 가지 방법으로 에뮬레이터에서 항목을 내보낼 수 있습니다. 첫 번째는 export-on-exit 플래그를 에뮬레이터 시작 명령어에 추가하는 것입니다. 두 번째 방법은 에뮬레이터에 POST 내보내기 요청을 전송하는 것입니다. curl 또는 유사한 도구를 사용할 수 있습니다. 다음 예시를 참조하세요.
프로토콜
curl -X POST http://localhost:8080/emulator/v1/projects/[PROJECT_ID]:export \
-H 'Content-Type: application/json' \
-d '{"database":"[DATABASE_PATH]", "export_directory":"EXPORT_DIRECTORY"}'
에뮬레이터가 다른 포트를 사용하는 경우 localhost:8080을 수정합니다.CLI 플래그
gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY
각 매개변수는 다음과 같습니다.
[PROJECT_ID]는 프로젝트 ID입니다.[DATABASE_PATH]는 데이터베이스 경로입니다. 예를 들어, 기본 데이터베이스가 있는 프로젝트는 다음과 같이 표시됩니다.{"database":"projects/myProject/databases/"}[EXPORT_DIRECTORY]는 에뮬레이터가 항목 내보내기 파일을 저장하는 디렉터리를 지정합니다. 이 디렉터리에 항목 내보내기 파일 모음이 포함되어 있으면 안 됩니다. 예를 들면 다음과 같습니다.{"export_directory":"/home/user/myexports/2024-03-26/"}
에뮬레이터 데이터 재설정
Firestore 에뮬레이터에는 에뮬레이터에 있는 모든 데이터를 재설정하기 위한 REST 엔드포인트가 포함됩니다. 이 엔드포인트를 사용하면 에뮬레이터를 종료하지 않고도 테스트 간에 데이터를 삭제할 수 있습니다.
에뮬레이터의 모든 데이터를 재설정하려면 다음 엔드포인트에 대해 HTTP POST 작업을 수행합니다. 여기서 HOST 및 PORT를 선택한 호스트 및 포트로 바꾸고 PROJECT_ID를 자체 프로젝트 ID로 바꿉니다.
http://HOST:PORT/reset
에뮬레이터에서 127.0.0.1:8080를 사용하지 않으면 호스트와 포트를 조정합니다.
코드는 재설정이 완료되거나 실패했다는 REST 확인을 기다려야 합니다.
curl을 사용하여 셸에서 이 작업을 수행할 수 있습니다.
$ curl -X POST "http://HOST:PORT/reset"
에뮬레이터와 프로덕션 환경의 차이점
에뮬레이터에서는 프로덕션 서비스의 동작을 충실하게 복제하려고 하지만 몇 가지 주요 제한사항이 있습니다.
동시 실행 및 일관성
에뮬레이터는 비관적 동시 실행과 strong consistency만 지원합니다. 에뮬레이터는 낙관적 동시 실행 및 eventual consistency 설정을 지원하지 않습니다.
트랜잭션
에뮬레이터는 프로덕션 환경에 보이는 모든 트랜잭션 동작을 구현하지는 않습니다. 한 문서에 여러 번의 동시 쓰기를 수반하는 기능을 테스트하는 경우 에뮬레이터에서 쓰기 요청을 완료하는 속도가 느릴 수 있습니다. 경우에 따라 잠금이 해제되는 데 최대 30초가 걸릴 수 있습니다. 필요한 경우 테스트 시간 제한을 조정해 보세요.
색인
에뮬레이터는 복합 색인을 추적하지 않으며 대신 유효한 쿼리를 실행합니다. 실제 Datastore 모드 인스턴스에서 앱을 테스트하여 필요한 색인을 파악해야 합니다.
한도
에뮬레이터는 프로덕션에서 시행되는 모든 한도를 적용하지 않습니다. 예를 들어 프로덕션 서비스에서는 너무 커서 거부될 트랜잭션을 에뮬레이터는 허용할 수 있습니다. 문서화된 한도를 숙지하고 이러한 문제를 사전에 방지하도록 앱을 설계해야 합니다.