Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

데이터 내보내기 및 가져오기

Cloud Firestore 내보내기/가져오기 관리 서비스를 사용하면 실수로 삭제한 데이터를 복원하고 오프라인 처리를 위해 데이터를 내보낼 수 있습니다. 모든 문서를 내보내거나 특정 컬렉션만 지정하여 내보낼 수 있습니다. 마찬가지로 내보내기한 모든 데이터를 가져오거나 특정 컬렉션만 지정하여 가져오는 것도 가능합니다. 한 Cloud Firestore 데이터베이스에서 내보낸 데이터를 다른 Cloud Firestore 데이터베이스에 가져올 수 있습니다. 또한 Cloud Firestore 내보내기를 BigQuery로 로드할 수 있습니다.

이 페이지에서는 내보내기/가져오기 관리 서비스와 Cloud Storage를 사용하여 Cloud Firestore 문서를 내보내고 가져오는 방법을 설명합니다. Cloud Firestore 내보내기/가져오기 관리 서비스는 gcloud 명령줄 도구 및 Cloud Firestore API(REST, RPC)를 통해 사용할 수 있습니다.

시작하기 전에

내보내기/가져오기 관리 서비스를 사용하려면 먼저 다음 작업을 완료해야 합니다.

  1. Google Cloud 프로젝트에 결제를 사용 설정합니다. 결제가 사용 설정된 Google Cloud 프로젝트만 내보내기 및 가져오기 기능을 사용할 수 있습니다.
  2. Cloud Firestore 데이터베이스 위치와 가까운 위치에 프로젝트에 사용할 Cloud Storage 버킷을 생성합니다. 내보내기/가져오기 작업에는 요청자 지불 버킷을 사용할 수 없습니다.
  3. 계정에 Cloud Firestore와 Cloud Storage에 필요한 권한이 있는지 확인합니다. 프로젝트 소유자인 계정에는 필요한 권한이 있습니다. 그렇지 않은 경우 다음 역할은 내보내기/가져오기 작업과 Cloud Storage 액세스에 필요한 권한을 부여합니다.

    • Cloud Firestore 역할: Owner, Cloud Datastore Owner 또는 Cloud Datastore Import Export Admin
    • Cloud Storage 역할: Owner 또는 Storage Admin

기본 서비스 계정 권한

각 Google Cloud 프로젝트는 PROJECT_ID@appspot.gserviceaccount.com이라는 기본 서비스 계정을 자동으로 만듭니다. 내보내기 및 가져오기 작업은 이 서비스 계정을 사용하여 Cloud Storage 작업을 승인합니다.

프로젝트의 기본 서비스 계정은 내보내기 또는 가져오기 작업에 사용되는 Cloud Storage 버킷에 액세스할 수 있어야 합니다. Cloud Storage 버킷이 Cloud Firestore 데이터베이스와 동일한 프로젝트에 있으면 기본적으로 기본 서비스 계정이 버킷에 액세스할 수 있습니다.

Cloud Storage 버킷이 다른 프로젝트에 있으면 기본 서비스 계정에 Cloud Storage 버킷에 대한 액세스 권한을 부여해야 합니다.

서비스 계정은 내보내기 또는 가져오기 작업에 사용할 Cloud Storage 버킷의 Storage Admin 역할이 필요합니다.

App Engine 기본 서비스 계정을 사용 중지하거나 삭제하면 App Engine 앱은 Cloud Firestore 데이터베이스에 대한 액세스 권한을 상실합니다. App Engine 서비스 계정을 사용 중지한 경우 다시 사용 설정할 수 있습니다. 서비스 계정 사용 설정을 참조하세요. 지난 30일 내에 App Engine 서비스 계정을 삭제한 경우, 서비스 계정을 복원할 수 있습니다. 서비스 계정 삭제 취소를 참조하세요.

프로젝트에 gcloud 설정

Google Cloud Platform Console 또는 gcloud 명령줄 도구를 통해 가져오기/내보내기 작업을 시작할 수 있습니다. gcloud를 사용하려면 다음 방법 중 하나를 사용해 명령줄 도구를 설정하고 프로젝트에 연결합니다.

데이터 내보내기

내보내기 작업은 데이터베이스의 문서를 Cloud Storage 버킷의 파일 집합에 복사합니다. 내보내기는 내보내기 시작 시간에 생성된 정확한 데이터베이스 스냅샷이 아닙니다. 내보내기에는 작업 실행 중에 수행된 변경 사항이 포함될 수 있습니다.

모든 문서 내보내기

Google Cloud Console

  1. Google Cloud Platform Console의 Cloud Firestore 가져오기/내보내기 페이지로 이동합니다.

    가져오기/내보내기 페이지로 이동

  2. 내보내기를 클릭합니다.

  3. 전체 데이터베이스 내보내기 옵션을 클릭합니다.

  4. 대상 선택에서 Cloud Storage 버킷의 이름을 입력하거나 찾아보기 버튼을 사용하여 버킷을 선택합니다.

  5. 내보내기를 클릭합니다.

Console이 가져오기/내보내기 페이지로 돌아갑니다. 작업이 성공적으로 시작되면 최근 가져오기/내보내기 페이지에 항목이 추가됩니다. 실패하면 페이지에 오류 메시지가 표시됩니다.

gcloud

[BUCKET_NAME]을 Cloud Storage 버킷 이름으로 바꾸며 데이터베이스의 모든 문서를 내보내려면 firestore export 명령어를 사용합니다. 작업이 완료될 때까지 gcloud 도구가 대기하는 것을 방지하려면 --async 플래그를 추가합니다.

gcloud firestore export gs://[BUCKET_NAME]

버킷 이름 뒤에 파일 프리픽스를 추가하여 내보내기를 구성할 수 있습니다(예: BUCKET_NAME/my-exports-folder/export-name). 파일 프리픽스를 지정하지 않은 경우 내보내기 관리 서비스는 현재 타임스탬프를 기준으로 파일 프리픽스를 하나 만듭니다.

내보내기 작업을 시작하면 터미널을 닫아도 작업이 취소되지 않습니다. 작업 취소를 참조하세요.

특정 컬렉션 내보내기

Google Cloud Console

  1. Google Cloud Platform Console의 Cloud Firestore 가져오기/내보내기 페이지로 이동합니다.

    가져오기/내보내기 페이지로 이동

  2. 내보내기를 클릭합니다.

  3. 하나 이상의 컬렉션 그룹 내보내기 옵션을 클릭합니다. 드롭다운 메뉴를 사용하여 하나 이상의 컬렉션 그룹을 선택합니다.

  4. 대상 선택에서 Cloud Storage 버킷의 이름을 입력하거나 찾아보기 버튼을 사용하여 버킷을 선택합니다.

  5. 내보내기를 클릭합니다.

Console이 가져오기/내보내기 페이지로 돌아갑니다. 작업이 성공적으로 시작되면 최근 가져오기/내보내기 페이지에 항목이 추가됩니다. 실패하면 페이지에 오류 메시지가 표시됩니다.

gcloud

특정 컬렉션 그룹을 내보내려면 --collection-ids 플래그를 사용합니다. 이 작업은 컬렉션 ID가 지정된 컬렉션 그룹만 내보냅니다. 컬렉션 그룹에는 컬렉션 ID가 지정된 모든 경로의 컬렉션 및 하위 컬렉션이 모두 포함됩니다.

gcloud firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

데이터 가져오기

Cloud Storage에서 파일을 내보냈다면 그 파일의 문서를 사용자의 프로젝트 또는 다른 프로젝트로 다시 가져올 수 있습니다. 가져오기 작업에 대한 다음 사항을 유의하세요.

  • 데이터를 가져오면 필수 색인이 데이터베이스의 현재 색인 정의를 사용하여 업데이트됩니다. 내보내기에는 색인 정의가 포함되지 않습니다.

  • 가져오기를 수행하면 새 문서 ID를 할당하지 않고 내보낼 때 캡처된 ID를 사용합니다. 문서를 가져올 때 문서의 ID가 유지되어 ID 충돌을 방지합니다. ID가 같은 문서가 이미 있는 경우에 가져오기를 수행하면 기존 문서를 덮어씁니다.

  • 가져오기의 영향을 받지 않는 데이터베이스의 문서는 가져오기 후에도 데이터베이스에 남아있게 됩니다.

  • 가져오기 작업은 Cloud Functions를 트리거하지 않습니다. 스냅샷 리스너는 가져오기 작업과 관련된 업데이트를 받습니다.

내보내기에서 모든 문서 가져오기

Google Cloud Console

  1. Google Cloud Platform Console의 Cloud Firestore 가져오기/내보내기 페이지로 이동합니다.

    가져오기/내보내기 페이지로 이동

  2. 가져오기를 클릭합니다.

  3. 파일 이름 필드에 완료된 내보내기 작업에서 .overall_export_metadata 파일의 파일 이름을 입력합니다. 찾아보기 버튼을 사용하면 파일을 선택할 수 있습니다.

  4. 가져오기를 클릭합니다.

Console이 가져오기/내보내기 페이지로 돌아갑니다. 작업이 성공적으로 시작되면 최근 가져오기/내보내기 페이지에 항목이 추가됩니다. 실패하면 페이지에 오류 메시지가 표시됩니다.

gcloud

이전 내보내기 작업에서 문서를 가져오려면 firestore import 명령어를 사용합니다.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

여기에서 [BUCKET_NAME][EXPORT_PREFIX]는 내보내기 파일의 위치를 가리킵니다. 예를 들면 다음과 같습니다.

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

Google Cloud Platform Console의 Cloud Storage 브라우저에서 내보내기 파일의 위치를 확인할 수 있습니다.

Cloud Storage 브라우저 열기

가져오기 작업을 시작하면 터미널을 닫아도 작업이 취소되지 않습니다. 작업 취소를 참조하세요.

특정 컬렉션 가져오기

Google Cloud Console

Console에서 특정 컬렉션을 선택할 수 없습니다. 대신 gcloud를 사용하세요.

gcloud

내보내기 파일 집합에서 특정 컬렉션 그룹을 가져오려면 --collection-ids 플래그를 사용합니다. 이 작업은 컬렉션 ID가 지정된 컬렉션 그룹만 가져옵니다. 컬렉션 그룹에는 컬렉션 ID가 지정된 모든 경로의 컬렉션 및 하위 컬렉션이 모두 포함됩니다.

특정 컬렉션 그룹의 내보내기만 특정 컬렉션 그룹 가져오기를 지원합니다. 모든 문서 내보내기에서는 특정 컬렉션을 가져올 수 없습니다.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

내보내기/가져오기 작업 관리

내보내기 또는 가져오기 작업을 시작한 후 Cloud Firestore는 작업에 고유한 이름을 할당합니다. 이 작업 이름을 사용하면 작업을 삭제 또는 취소하거나 상태를 확인할 수 있습니다.

작업 이름은 다음 예시와 같이 projects/[PROJECT_ID]/databases/(default)/operations/로 시작합니다.

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

describe, cancel, delete 명령어에 작업 이름을 지정할 때 프리픽스는 제외할 수 있습니다.

내보내기/가져오기 작업 모두 나열

Google Cloud Console

Google Cloud Platform Console의 Cloud Firestore 가져오기/내보내기 페이지에서 최근 내보내기/가져오기 작업 목록을 볼 수 있습니다.

가져오기/내보내기 페이지로 이동

gcloud

operations list 명령어를 사용하면 모든 실행 중인 작업과 최근에 완료된 내보내기/가져오기 작업을 볼 수 있습니다.

gcloud firestore operations list

작업 상태 확인

Google Cloud Console

Google Cloud Platform Console의 Cloud Firestore 가져오기/내보내기 페이지에서 최근 내보내기 또는 가져오기 작업의 상태를 볼 수 있습니다.

가져오기/내보내기 페이지로 이동

gcloud

내보내기 또는 가져오기 작업의 상태를 표시하려면 operations describe 명령어를 사용하세요.

gcloud firestore operations describe [OPERATION_NAME]

완료 시간 예상

장기 실행 작업의 상태를 요청하면 workEstimatedworkCompleted 측정항목이 반환됩니다. 이러한 각 측정항목은 바이트 수와 항목 수 단위로 반환됩니다.

  • workEstimated는 작업에서 처리할 것으로 예상되는 총 바이트 및 문서 수를 나타냅니다.

  • workCompleted는 지금까지 처리된 바이트 및 문서 수를 나타냅니다. 작업이 완료된 후 이 값은 실제로 처리된 총 바이트 및 문서 수를 나타내며 workEstimated 값보다 클 수 있습니다.

workCompletedworkEstimated로 나누면 예상 진행도를 대략적으로 추정할 수 있습니다. 이 예상치는 통계 수집이 지연되어 정확하지 않을 수 있습니다.

작업 취소

Google Cloud Console

Google Cloud Platform Console의 Cloud Firestore 가져오기/내보내기 페이지에서 실행 중인 내보내기 또는 가져오기 작업을 취소할 수 있습니다.

가져오기/내보내기 페이지로 이동

최근 내보내기/가져오기 테이블의 현재 실행 중인 작업에는 완료됨 열에 취소 버튼이 포함됩니다. 작업을 중지하려면 취소 버튼을 클릭합니다. 버튼이 취소 중 메시지로 변경된 다음 작업이 완전히 중지되면 취소됨으로 변경됩니다.

gcloud

operations cancel 명령어를 사용하면 진행 중인 작업을 중지할 수 있습니다.

gcloud firestore operations cancel [OPERATION_NAME]

실행 중인 작업을 취소해도 이미 진행된 작업은 취소되지 않습니다. 취소된 내보내기 작업은 Cloud Storage에 이미 내보낸 문서를 그대로 두고 취소된 가져오기 작업은 데이터베이스에 이미 수행된 업데이트를 그대로 둡니다. 일부만 완료된 내보내기는 가져올 수 없습니다.

작업 삭제

최근 작업 목록에서 작업을 삭제하려면 gcloud firestore operations delete 명령어를 사용하세요. 이 명령어로 Cloud Storage에서 내보내기 파일이 삭제되지는 않습니다.

gcloud firestore operations delete [OPERATION_NAME]

내보내기/가져오기 작업 결제 및 가격 책정

내보내기/가져오기 관리 서비스를 사용하기 전에 Google Cloud 프로젝트의 결제를 사용 설정해야 합니다. 내보내기/가져오기 작업은 Cloud Firestore 가격 책정에 나온 요금에 따라 문서 읽기 및 쓰기에 대한 요금이 청구됩니다.

내보내기/가져오기 작업 비용은 지출 한도에 포함되지 않습니다. 내보내기 또는 가져오기 작업은 완료 후까지 Google Cloud 예산 알림을 트리거하지 않습니다. 마찬가지로 내보내기 또는 가져오기 작업 도중 수행되는 읽기 및 쓰기는 작업 완료 후 일일 할당량에 반영됩니다. 내보내기/가져오기 작업은 Console의 사용량 섹션에 표시되는 사용량에는 영향을 미치지 않습니다.

내보내기/가져오기 비용 보기

내보내기/가져오기 작업은 청구 작업에 goog-firestoremanaged:exportimport 라벨을 적용합니다. Cloud Billing 보고서 페이지에서 이 라벨을 사용하여 가져오기/내보내기 작업과 관련된 비용을 볼 수 있습니다.

필터 메뉴에서 goog-firestoremanaged 라벨에 액세스합니다.

BigQuery로 내보내기

collection-ids 필터를 지정한 경우에만 Cloud Firestore 내보내기에서 BigQuery로 데이터를 로드할 수 있습니다. Cloud Firestore 내보내기에서 데이터 로드를 참조하세요.

BigQuery 열 한도

BigQuery는 테이블당 열을 10,000개로 제한합니다. Cloud Firestore 내보내기 작업은 각 컬렉션 그룹에 대한 BigQuery 테이블 스키마를 생성합니다. 이 스키마에서 컬렉션 그룹 내 각 고유 필드 이름은 스키마 열이 됩니다.

컬렉션 그룹의 BigQuery 스키마가 10,000 개 열을 초과하면 Cloud Firestore 내보내기 작업은 지도 필드를 바이트로 취급하여 열 제한을 넘지 않도록 합니다. 이 변환으로 10,000개 미만의 열을 가져 오면 데이터를 BigQuery에 로드할 수 있지만 지도 필드 내의 하위 필드는 쿼리할 수 없습니다. 열 수가 여전히 10,000개를 초과하면 내보내기 작업은 컬렉션 그룹에 대한 BigQuery 스키마를 생성하지 않으며 데이터를 BigQuery에 로드할 수 없습니다.

내보내기 형식 및 메타데이터 파일

관리형 내보내기의 출력은 LevelDB 로그 형식을 사용합니다.

메타데이터 파일

내보내기 작업으로 지정한 컬렉션 그룹마다 메타데이터 파일이 생성됩니다. 일반적으로 메타데이터 파일의 이름은 ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata입니다.

메타데이터 파일은 프로토콜 버퍼이며 protoc 프로토콜 컴파일러로 디코딩할 수 있습니다. 예를 들어 메타데이터 파일을 디코딩하면 내보내기 파일에 포함된 컬렉션 그룹을 확인할 수 있습니다.

protoc --decode_raw < export0.export_metadata