항목 내보내기 및 가져오기

이 페이지에서는 관리형 내보내기/가져오기 서비스를 사용하여 Datastore 모드의 Firestore 항목을 내보내고 가져오는 방법을 설명합니다. 관리형 내보내기 및 가져오기 서비스는 콘솔, Google Cloud CLI, Datastore Admin API(REST, RPC)를 통해 사용할 수 있습니다.

관리형 내보내기/가져오기 서비스를 사용하면 실수로 삭제된 데이터를 복원하고 오프라인 처리에 필요한 데이터를 내보낼 수 있습니다. 모든 항목 또는 특정 종류의 항목만 지정하여 내보낼 수 있습니다. 마찬가지로 내보내기한 모든 데이터를 가져오거나 특정 종류만 지정하여 가져오는 것도 가능합니다. 내보내기/가져오기 관리 서비스를 사용할 때는 다음 사항을 고려하세요.

내보내기 서비스는 최종 일관성을 지닌 읽기를 사용합니다. 따라서 내보내기가 동일한 시점에 이루어졌다고 추측할 수 없습니다. 내보내기를 수행할 때 내보내기 시작 후 작성된 항목은 포함하고 내보내기 시작 전 작성된 항목은 제외할 수 있습니다.
내보내기에는 어떠한 색인도 포함되지 않습니다. 데이터를 가져오면 필수 색인이 데이터베이스의 현재 색인 정의를 사용하여 자동으로 다시 구축됩니다. 항목당 속성 값 색인 설정은 내보내기에 포함되고 가져올 때도 반영됩니다.
가져오기를 수행하면 항목에 새로운 ID가 할당되지 않고, 내보낸 시점에 있던 ID를 사용하여 동일한 ID의 기존 항목을 덮어씁니다. 항목을 가져오는 동안에는 ID가 예약됩니다. 이 기능은 가져오기를 실행하는 동안 쓰기가 사용 설정된 경우 새 항목과 ID의 충돌을 방지합니다.
가져오기의 영향을 받지 않는 데이터베이스 내 항목은 가져오기 후에도 데이터베이스에 유지됩니다.
하나의 Datastore 모드 데이터베이스에서 내보낸 데이터를 다른 Datastore 모드 데이터베이스(다른 프로젝트에 있는 경우도 해당)로 가져올 수 있습니다.
관리형 내보내기 및 가져오기 서비스는 동시 실행되는 내보내기와 가져오기 횟수를 50회로 제한하며 한 프로젝트의 내보내기 및 가져오기 요청을 분당 최대 20개까지 허용합니다. 각 요청에 대해 서비스는 항목 필터 조합 수를 100개로 제한합니다.
관리형 내보내기의 출력은 LevelDB 로그 형식을 사용합니다.
항목의 하위 집합을 가져오거나 BigQuery로 데이터를 가져오려면 내보낼 때 항목 필터를 지정해야 합니다.
.overall_export_metadata 파일 이름은 상위 폴더 이름과 일치해야 합니다.

gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

내보내기의 출력 파일을 이동하거나 복사할 경우 PARENT_FOLDER_NAME, 하위 폴더 콘텐츠, .overall_export_metadata 파일 이름을 동일하게 유지합니다.

시작하기 전에

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

Google Cloud 프로젝트에 결제를 사용 설정합니다. 결제가 사용 설정된 Google Cloud 프로젝트만 내보내기 및 가져오기 기능을 사용할 수 있습니다.
Datastore 모드의 Firestore 데이터베이스와 동일한 위치에 Cloud Storage 버킷을 만듭니다. 내보내기/가져오기 작업에는 요청자 지불 버킷을 사용할 수 없습니다.
데이터를 내보내는 경우에는 datastore.databases.export 권한을 부여하고 데이터를 가져오는 경우에는 datastore.databases.import 권한을 부여하는 IAM 역할을 사용자 계정에 할당합니다. 예를 들어 Datastore Import Export Admin 역할은 두 권한을 모두 부여합니다.
Cloud Storage 버킷이 다른 프로젝트에 있으면 Firestore 서비스 에이전트에 버킷에 대한 액세스 권한을 부여하세요.

프로젝트에 `gcloud` 설정

gcloud를 사용하여 가져오기 및 내보내기 작업을 시작하려면 gcloud를 설정하고 다음 방법 중 하나를 사용하여 프로젝트에 연결합니다.

Cloud Shell을 사용하여 Google Cloud 콘솔에서 gcloud에 액세스합니다.

Cloud Shell 시작

현재 프로젝트를 사용하도록 gcloud CLI를 구성합니다.
```
gcloud config set project project-id
```
Google Cloud CLI를 설치하고 초기화합니다.

권한

내보내기 및 가져오기 작업을 실행하려면 사용자 계정과 프로젝트의 Datastore 모드 서비스 에이전트에 다음 Identity and Access Management 권한이 있어야 합니다.

사용자 계정 권한

작업을 시작하는 사용자 계정 또는 서비스 계정에는 datastore.databases.export 및 datastore.databases.import IAM 권한이 필요합니다. 프로젝트 소유자인 계정에는 필요한 권한이 있습니다. 그렇지 않으면 다음 IAM 역할이 필요한 권한을 부여합니다.

Datastore 소유자
Datastore 가져오기 내보내기 관리자

이러한 권한을 맞춤 역할로 할당할 수도 있습니다.

프로젝트 소유자는 액세스 권한 부여 단계를 따라 이러한 역할 중 하나를 부여할 수 있습니다.

서비스 에이전트 권한

내보내기 및 가져오기 작업은 Firestore 서비스 에이전트를 사용하여 Cloud Storage 작업을 승인합니다. Firestore 서비스 에이전트는 다음 이름 지정 규칙을 사용합니다.

Firestore 서비스 에이전트: service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

서비스 에이전트에 대한 자세한 내용은 서비스 에이전트를 참조하세요.

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

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

서비스 에이전트에 역할 할당

gsutil 명령줄 도구를 사용하면 아래 역할 중 하나를 할당할 수 있습니다. 예를 들어 스토리지 관리자 역할을 Firestore 서비스 에이전트에 할당하려면 다음을 실행합니다.

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

PROJECT_NUMBER를 Firestore 서비스 에이전트 이름 지정에 사용되는 프로젝트 번호로 바꿉니다. 서비스 에이전트 이름을 보려면 서비스 에이전트 이름 보기를 참조하세요.

또는 Google Cloud 콘솔을 사용하여 이 역할을 할당할 수 있습니다.

서비스 에이전트 이름 보기

Google Cloud 콘솔의 가져오기/내보내기 페이지에서 가져오기 및 내보내기 작업이 요청을 승인하는 데 사용하는 계정을 볼 수 있습니다. 데이터베이스에서 Firestore 서비스 에이전트 또는 기존 App Engine 서비스 계정을 사용하는지도 확인할 수 있습니다.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
가져오기/내보내기 작업 실행 계정 라벨 옆에 있는 승인 계정을 확인합니다.

내보내기 작업

다른 프로젝트의 버킷과 관련된 내보내기 작업의 경우 버킷의 권한을 수정하여 Datastore 모드 데이터베이스를 포함한 프로젝트의 Datastore 모드 서비스 에이전트에 다음 Identity and Access Management 역할 중 하나를 할당합니다.

스토리지 관리자
소유자(기본 역할)

또한 위에 나열된 역할에 포함된 권한과 약간 다른 권한을 가진 IAM 커스텀 역할을 만들 수도 있습니다.

storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.list

가져오기 작업

다른 프로젝트의 Cloud Storage 버킷과 관련된 가져오기 작업의 경우 버킷의 권한을 수정하여, Datastore 모드 데이터베이스가 포함된 프로젝트의 Datastore 모드 서비스 에이전트에 다음 Cloud Storage 역할 중 하나를 할당합니다.

스토리지 관리자
스토리지 객체 뷰어 및 스토리지 기존 버킷 리더

또한 다음 권한이 있는 IAM 맞춤 역할을 만들 수도 있습니다.

storage.buckets.get
storage.objects.get

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

이 섹션에서는 관리형 내보내기 또는 가져오기 작업을 시작하는 방법을 설명합니다.

모든 항목 내보내기

콘솔

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.

탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
내보내기를 클릭합니다.
네임스페이스 필드를 All Namespaces로 설정하고, 종류 필드를 All Kinds로 설정합니다.
대상 아래에 Cloud Storage 버킷의 이름을 입력합니다.
내보내기를 클릭합니다.

콘솔이 가져오기/내보내기 페이지로 돌아갑니다. 알림은 관리형 내보내기 요청의 성공 또는 실패를 보고합니다.

gcloud

gcloud firestore export 명령어를 사용하여 데이터베이스의 모든 항목을 내보낼 수 있습니다.

 gcloud firestore export gs://bucket-name --async --database=DATABASE

여기서 bucket-name은 Cloud Storage 버킷의 이름이며 선택사항인 프리픽스입니다(예: bucket-name/datastore-exports/export-name). 동일한 프리픽스를 다른 내보내기 작업에 다시 사용할 수 없습니다. 파일 프리픽스를 제공하지 않으면 관리형 내보내기 서비스는 현재 시간을 기준으로 프리픽스를 만듭니다.

작업이 완료될 때까지 gcloud가 대기하는 것을 방지하려면 [--async][async-flag] 플래그를 사용하세요. --async 플래그를 생략하는 경우 Ctrl+c를 입력하여 작업 대기를 중지할 수 있습니다. 이렇게 해도 작업이 취소되지는 않습니다.

--database 플래그를 항목을 내보낼 데이터베이스의 이름으로 설정합니다. 기본 데이터베이스에는 --database='(default)'를 사용합니다.

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

project-id: 프로젝트 ID입니다.
bucket-name: Cloud Storage 버킷 이름

HTTP 메서드 및 URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

JSON 요청 본문:

{
  "outputUrlPrefix": "gs://bucket-name",
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}

응답은 완료 여부를 확인할 수 있는 장기 실행 작업입니다.

특정 종류 또는 네임스페이스 내보내기

특정 종류 또는 네임스페이스의 하위 집합을 내보내려면 종류 및 네임스페이스 ID의 값을 지정한 항목 필터를 제공합니다. 각 요청은 100개의 항목 필터 조합으로 제한되며, 필터링된 종류와 네임스페이스의 각 조합은 이 한도에서 개별 필터로 집계됩니다.

콘솔

콘솔에서 모든 종류 또는 특정 종류를 선택할 수 있습니다. 마찬가지로 모든 네임스페이스 또는 특정 네임스페이스를 선택할 수 있습니다.

내보낼 네임스페이스 및 종류 목록을 지정하려면 대신 gcloud를 사용하세요.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
내보내기를 클릭합니다.
네임스페이스 필드를 All Namespaces 또는 네임스페이스 중 하나의 이름으로 설정합니다.
종류 필드를 All Kinds 또는 종류의 이름으로 설정합니다.
대상 아래에 Cloud Storage 버킷의 이름을 입력합니다.
내보내기를 클릭합니다.

콘솔이 가져오기/내보내기 페이지로 돌아갑니다. 알림은 관리형 내보내기 요청의 성공 또는 실패를 보고합니다.

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

--database 플래그를 특정 종류 또는 네임스페이스를 내보낼 데이터베이스의 이름으로 설정합니다. 기본 데이터베이스에는 --database='(default)'를 사용합니다.

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

project-id: 프로젝트 ID입니다.
bucket-name: Cloud Storage 버킷 이름
kind: 항목 종류
namespace: 네임스페이스 ID(기본 네임스페이스 ID로 "" 사용)

HTTP 메서드 및 URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

JSON 요청 본문:

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

PowerShell(Windows)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}

응답은 완료 여부를 확인할 수 있는 장기 실행 작업입니다.

메타데이터 파일

내보내기 작업은 지정된 각 네임스페이스-종류 쌍에 메타데이터 파일을 만듭니다. 일반적으로 메타데이터 파일의 이름은 NAMESPACE_NAME_KIND_NAME.export_metadata입니다. 하지만 네임스페이스 또는 종류가 잘못된 Cloud Storage 객체 이름을 만드는 경우 파일 이름은 export[NUM].export_metadata입니다.

메타데이터 파일은 프로토콜 버퍼이며 protoc 프로토콜 컴파일러로 디코딩될 수 있습니다. 예를 들어 메타데이터 파일을 디코딩하면 내보내기 파일에 포함된 네임스페이스와 종류를 확인할 수 있습니다.

protoc --decode_raw < export0.export_metadata

모든 항목 가져오기

콘솔

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
가져오기를 클릭합니다.
File 필드에서 찾아보기를 클릭하고 .overall_export_metadata 파일을 선택합니다.

.overall_export_metadata 파일이 기본 위치에서 이동되지 않았는지 확인합니다.
네임스페이스 필드를 All Namespaces로 설정하고, 종류 필드를 All Kinds로 설정합니다.
가져오기를 클릭합니다.

콘솔이 가져오기/내보내기 페이지로 돌아갑니다. 알림은 관리형 가져오기 요청의 성공 또는 실패를 보고합니다.

gcloud

gcloud firestore import 명령어를 사용하면 관리형 내보내기 서비스로 이전에 내보낸 모든 항목을 가져올 수 있습니다.

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

여기서 bucket-name/file-path/file-name은 Cloud Storage 버킷 내의 overall_export_metadata 파일 경로입니다.

--database 플래그를 모든 항목을 가져올 데이터베이스의 이름으로 설정합니다. 기본 데이터베이스에는 --database='(default)'를 사용합니다.

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

project-id: 프로젝트 ID입니다.
bucket-name: Cloud Storage 버킷 이름
object-name: Cloud Storage 객체 이름(예: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

HTTP 메서드 및 URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

JSON 요청 본문:

{
  "inputUrl": "gs://bucket-name/object-name",
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

PowerShell(Windows)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}

응답은 완료 여부를 확인할 수 있는 장기 실행 작업입니다.

`overall_export_metadata` 파일 찾기

Google Cloud 콘솔에서 Cloud Storage 브라우저를 사용하여 가져오기 위치에 사용할 값을 결정할 수 있습니다.

Cloud Storage 브라우저 열기

완료된 작업을 나열하고 설명할 수도 있습니다. outputURL 필드는 overall_export_metadata 파일의 이름을 보여 줍니다.

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

특정 종류 또는 네임스페이스 가져오기

종류 또는 네임스페이스의 하위 집합을 가져오려면 종류 및 네임스페이스 ID의 값을 항목 필터에 제공합니다.

항목 필터를 사용하여 내보내기 파일을 만든 경우에만 종류 및 네임스페이스를 지정할 수 있습니다. 모든 항목 내보내기에서 종류 및 네임스페이스의 하위 집합을 가져올 수 없습니다.

콘솔

콘솔에서 모든 종류 또는 특정 종류를 선택할 수 있습니다. 마찬가지로 모든 네임스페이스 또는 특정 네임스페이스를 선택할 수 있습니다.

가져올 네임스페이스 및 종류 목록을 지정하려면 대신 gcloud를 사용하세요.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
가져오기를 클릭합니다.
File 필드에서 찾아보기를 클릭하고 .overall_export_metadata 파일을 선택합니다.

.export_metadata 파일이 아닌 .overall_export_metadata 파일을 가져와야 합니다.
네임스페이스 필드를 All Namespaces 또는 특정 네임스페이스로 설정합니다.
종류 필드를 All Kinds 또는 특정 종류로 설정합니다.
가져오기를 클릭합니다.

콘솔이 가져오기/내보내기 페이지로 돌아갑니다. 알림은 관리형 가져오기 요청의 성공 또는 실패를 보고합니다.

gcloud

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

여기서 bucket-name/file-path/file-name은 Cloud Storage 버킷 내의 overall_export_metadata 파일 경로입니다.

--database 플래그를 특정 종류 또는 네임스페이스를 가져올 데이터베이스의 이름으로 설정합니다. 기본 데이터베이스에는 --database='(default)'를 사용합니다.

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

project-id: 프로젝트 ID입니다.
bucket-name: Cloud Storage 버킷 이름
object-name: Cloud Storage 객체 이름(예: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata
kind: 항목 종류
namespace: 네임스페이스 ID(기본 네임스페이스 ID로 "" 사용)

HTTP 메서드 및 URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

JSON 요청 본문:

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

PowerShell(Windows)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}

응답은 완료 여부를 확인할 수 있는 장기 실행 작업입니다.

PITR 데이터에서 내보내기 및 가져오기

gcloud firestore export 명령어를 사용하여 데이터베이스를 PITR 데이터에서 Cloud Storage로 내보낼 수 있습니다. 타임스탬프가 지난 7일 이내의 1분 타임스탬프이고 earliestVersionTime 이후인 PITR 데이터를 내보낼 수 있습니다. 데이터가 더 이상 지정된 타임스탬프에 없으면 내보내기 작업이 실패합니다.

PITR 내보내기 작업은 모든 항목 내보내기와 특정 종류 또는 네임스페이스 내보내기를 포함한 모든 필터를 지원합니다.

snapshot-time 매개변수를 필요한 복구 타임스탬프로 지정하여 데이터베이스를 내보냅니다.
gcloud
다음 명령어를 실행하여 데이터베이스를 버킷으로 내보냅니다.
```
gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP] \
    --collection-ids=[COLLECTION_IDS] \
    --namespace-ids=[NAMESPACE_IDS]
```
각 항목의 의미는 다음과 같습니다.
- PITR_TIMESTAMP - 분 단위의 PITR 타임스탬프입니다(예: 2023-05-26T10:20:00.00Z).
[항목 필터를 사용하여 종류 또는 네임스페이스의 특정 하위 집합 내보내기][export-kind]도 지원됩니다.

PITR 데이터를 내보내기 전에 다음 사항에 유의하세요.
- RFC 3339 형식으로 타임스탬프를 지정합니다. 예를 들면 2020-09-01T23:59:30.234233Z입니다.
- 지정한 타임스탬프가 지난 7일 이내의 1분 타임스탬프여야 하지만 earliestVersionTime 이전이어야 합니다. 지정된 타임스탬프에 데이터가 더 이상 존재하지 않으면 오류가 발생합니다.
- 실패한 PITR 내보내기 작업에 대해서는 요금이 청구되지 않습니다.
데이터베이스로 가져옵니다.

모든 항목 가져오기의 단계에 따라 내보낸 데이터베이스를 가져옵니다. 데이터베이스에 이미 항목이 있으면 덮어쓰게 됩니다. [항목 필터를 사용하여 종류 또는 네임스페이스의 특정 하위 집합 가져오기][import-kind]도 지원됩니다.

변환 가져오기

다른 프로젝트에서 항목을 가져올 때 항목 키에 프로젝트 ID가 포함된다는 점에 유의하세요. 가져오기 작업은 가져오기 데이터의 항목 키와 키 참조 속성을 대상 프로젝트의 프로젝트 ID로 업데이트합니다. 이 업데이트로 인해 항목 크기가 증가하면 가져오기 작업에 '항목이 너무 큽니다' 또는 '색인 항목이 너무 큽니다' 오류가 발생할 수 있습니다.

이 오류를 방지하려면 프로젝트 ID가 더 짧은 대상 프로젝트로 가져옵니다. 동일한 프로젝트의 데이터를 사용하는 가져오기 작업에는 영향을 미치지 않습니다.

장기 실행 작업 관리

관리형 가져오기 및 내보내기 작업은 장기 실행 작업입니다. 이러한 메서드 호출은 완료하는 데 상당한 시간이 걸릴 수 있습니다.

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

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

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

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

모든 장기 실행 작업 나열

다음과 같은 방법으로 진행 중인 작업과 최근에 완료된 작업을 볼 수 있습니다. 작업은 완료 후 며칠 동안 나열됩니다.

콘솔

장기 실행 작업 목록은 Google Cloud 콘솔의 가져오기/내보내기 페이지에서 볼 수 있습니다.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.

gcloud

장기 실행 작업을 나열하려면 gcloud datastore operations list 명령어를 사용합니다.

gcloud datastore operations list

예를 들어 최근에 완료된 내보내기 작업은 다음 정보를 보여줍니다.

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

project-id: 프로젝트 ID입니다.

HTTP 메서드 및 URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

다음 명령어를 실행합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

PowerShell(Windows)

다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

아래에서 응답에 대한 정보를 참조하세요.

예를 들어 최근에 완료된 내보내기 작업은 다음 정보를 보여줍니다.

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

작업 상태 확인

장기 실행 작업 상태를 확인하려면 다음 안내를 따르세요.

콘솔

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

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.

gcloud

operations describe 명령어를 사용하여 장기 실행 작업의 상태를 표시할 수 있습니다.

gcloud datastore operations describe operation-name

rest

요청 데이터를 사용하기 전에 다음을 바꿉니다.

project-id: 프로젝트 ID입니다.
operation-name: 작업 이름

HTTP 메서드 및 URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

다음 명령어를 실행합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name"

PowerShell(Windows)

다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

완료 시간 예상

작업이 실행되면 state 필드 값을 통해 작업의 전체 상태를 확인할 수 있습니다.

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

workEstimated는 작업에서 처리할 것으로 예상되는 총 바이트 및 문서 수를 나타냅니다. Datastore 모드가 예상치를 산출하지 못하는 경우 이 측정항목이 생략될 수 있습니다.
workCompleted는 지금까지 처리된 바이트 및 문서 수를 나타냅니다. 작업이 완료된 후 이 값은 실제로 처리된 총 바이트 및 문서 수를 나타내며 workEstimated 값보다 클 수 있습니다.

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

예를 들어 내보내기 작업의 진행도는 다음과 같이 표시됩니다.

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

작업이 완료되면 작업 설명에 "done": true가 포함됩니다. 작업 결과는 state 필드의 값을 참조하세요. 응답에 done 필드가 설정되지 않으면 이 값은 false입니다 진행 중인 작업에 done 값을 사용해서는 안 됩니다.

작업 취소

콘솔

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

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.

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

gcloud

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

gcloud datastore operations cancel operation-name

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

작업 삭제

gcloud

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

gcloud datastore operations delete operation-name

내보내기/가져오기 관리 결제 및 가격 책정

관리형 내보내기 및 가져오기 서비스를 사용하기 전에 Google Cloud 프로젝트의 결제를 사용 설정해야 합니다. 내보내기 및 가져오기 작업은 다음과 같은 방식으로 Google Cloud 비용에 반영됩니다.

내보내기 및 가져오기 작업에서 수행된 항목 읽기 및 쓰기는 Datastore 모드의 Firestore 비용으로 계산됩니다. 내보내기 작업은 내보낸 항목당 읽기 작업이 1회 발생합니다. 가져오기 작업은 가져온 항목당 쓰기 작업이 1회 발생합니다.
Cloud Storage에 저장된 출력 파일은 Cloud Storage 데이터 스토리지 비용으로 계산됩니다.

내보내기 또는 가져오기 작업은 완료 후까지 Google Cloud 예산 알림을 트리거하지 않습니다. 마찬가지로 내보내기 또는 가져오기 작업 도중 수행되는 읽기 및 쓰기는 작업 완료 후 일일 할당량에 반영됩니다.

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

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

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

Datastore 관리자 백업과의 차이점

Datastore 관리 콘솔을 사용하여 백업한 경우와의 차이점은 아래와 같습니다.

관리형 내보내기로 생성된 내보내기가 Datastore 관리 콘솔에 표시되지 않습니다. 관리형 내보내기 및 가져오기는 Google Cloud 콘솔을 통해 관리되는 App Engine의 백업 및 복원 기능과 데이터를 공유하지 않는 새로운 서비스입니다.
관리형 내보내기 및 가져오기 서비스는 Datastore 관리자 백업과 동일한 메타데이터를 지원하지 않으며 진행 상태를 데이터베이스에 저장하지 않습니다. 내보내기 및 가져오기 작업 진행도 확인에 대한 자세한 내용은 장기 실행 작업 관리를 참조하세요.
관리형 내보내기 및 가져오기 작업의 서비스 로그를 확인할 수 없습니다.
관리형 가져오기 서비스는 Datastore 관리자 백업 파일과 하위 호환됩니다. 관리형 가져오기 서비스를 사용하여 Datastore 관리자 백업 파일을 가져올 수 있지만 Datastore 관리 콘솔을 사용하여 관리형 내보내기 출력을 가져올 수 없습니다.

BigQuery로 가져오기

관리형 내보내기의 데이터를 BigQuery로 가져오려면 Datastore 내보내기 서비스 데이터 로드를 참조하세요.

항목 필터를 지정하지 않고 내보낸 데이터는 BigQuery에 로드될 수 없습니다. 데이터를 BigQuery로 가져오려면 내보내기 요청의 항목 필터에 종류 이름이 한 개 이상 포함되어야 합니다.

BigQuery 열 한도

BigQuery는 테이블당 열을 10,000개로 제한합니다. 내보내기 작업은 종류마다 BigQuery 테이블 스키마를 생성합니다. 이 스키마에서 종류의 항목 내 각 고유 속성은 스키마 열이 됩니다.

종류의 BigQuery 스키마 열이 10,000개를 초과하면 내보내기 작업은 포함된 항목을 blob으로 처리하여 열 한도를 넘지 않으려 합니다. 이 변환으로 스키마의 열 수가 10,000개 미만이 되면 BigQuery에 데이터를 로드할 수 있지만 포함된 항목 내에서 속성을 쿼리할 수 없습니다. 열의 수가 여전히 10,000개를 초과하는 경우 내보내기 작업은 종류의 BigQuery 스키마를 생성하지 않으며 데이터를 BigQuery에 로드할 수 없습니다.

서비스 에이전트 마이그레이션

Firestore는 App Engine 서비스 계정을 사용하는 대신 Firestore 서비스 에이전트를 사용하여 가져오기 및 내보내기 작업을 승인합니다. 서비스 에이전트와 서비스 계정은 다음 이름 지정 규칙을 사용합니다.

Firestore 서비스 에이전트: service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Firestore는 이전에 Firestore 서비스 에이전트 대신 App Engine 기본 서비스 계정을 사용했습니다. 데이터베이스에서 여전히 App Engine 서비스 계정을 사용하여 데이터를 가져오거나 내보내는 경우 이 섹션의 안내에 따라 Firestore 서비스 에이전트를 사용하도록 마이그레이션하는 것이 좋습니다.

App Engine 서비스 계정: PROJECT_ID@appspot.gserviceaccount.com

Firestore 서비스 에이전트는 Firestore에 국한되므로 더 좋습니다. App Engine 서비스 계정은 서비스 두 개 이상에서 공유됩니다.

승인 계정 보기

Google Cloud 콘솔의 가져오기/내보내기 페이지에서 가져오기 및 내보내기 작업이 요청을 승인하는 데 사용하는 계정을 볼 수 있습니다. 데이터베이스에서 이미 Firestore 서비스 에이전트를 사용 중인지도 확인할 수 있습니다.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
가져오기/내보내기 작업 실행 계정 라벨 옆에 있는 승인 계정을 확인합니다.

프로젝트에서 Firestore 서비스 에이전트를 사용하지 않는 경우 다음 기법 중 하나를 사용하여 Firestore 서비스 에이전트로 마이그레이션할 수 있습니다.

Cloud Storage 버킷 권한을 확인 및 업데이트하여 프로젝트를 마이그레이션합니다(권장).
조직 내의 모든 프로젝트에 영향을 미치는 조직 전체 정책 제약조건을 추가합니다.

이러한 기법 중 첫 번째 기법은 영향의 범위를 단일 Datastore 모드 프로젝트로 국소화하므로 더 좋습니다. 두 번째 기법은 기존 Cloud Storage 버킷 권한을 마이그레이션하지 않으므로 선호되지 않습니다. 하지만 조직 수준의 보안 규정 준수를 제공합니다.

Cloud Storage 버킷 권한을 확인하고 업데이트하여 마이그레이션

마이그레이션 프로세스는 두 단계로 구성됩니다.

Cloud Storage 버킷 권한을 업데이트합니다. 자세한 내용은 다음 섹션을 참조하세요.
Firestore 서비스 에이전트로 마이그레이션을 확인합니다.

서비스 에이전트 버킷 권한

다른 프로젝트의 Cloud Storage 버킷을 사용하는 내보내기 또는 가져오기 작업의 경우 해당 버킷에 대한 Firestore 서비스 에이전트 권한을 부여해야 합니다. 예를 들어 데이터를 다른 프로젝트로 이동하는 작업은 해당 프로젝트의 버킷에 액세스해야 합니다. 그렇지 않으면 Firestore 서비스 에이전트로 마이그레이션한 후에 이 작업이 실패합니다.

같은 프로젝트 내에 있는 가져오기 및 내보내기 워크플로에서는 권한을 변경할 필요가 없습니다. Firestore 서비스 에이전트는 기본적으로 같은 프로젝트의 버킷에 액세스할 수 있습니다.

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com 서비스 에이전트에 대한 액세스 권한을 부여하려면 다른 프로젝트에서 Cloud Storage 버킷 권한을 업데이트합니다. 서비스 에이전트에 Firestore Service Agent 역할을 부여합니다.

Firestore Service Agent 역할은 Cloud Storage 버킷에 대한 읽기 및 쓰기 권한을 부여합니다. 읽기 권한만 또는 쓰기 권한만 부여해야 하는 경우 커스텀 역할을 사용합니다.

다음 섹션에 설명된 마이그레이션 프로세스는 권한 업데이트가 필요할 수 있는 Cloud Storage 버킷을 식별하는 데 도움이 됩니다.

Firestore 서비스 에이전트로 프로젝트 마이그레이션

App Engine 서비스 계정에서 Firestore 서비스 에이전트로 마이그레이션하려면 다음 단계를 완료합니다. 완료하면 마이그레이션을 취소할 수 없습니다.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
프로젝트가 아직 Firestore 서비스 에이전트로 마이그레이션되지 않은 경우 마이그레이션을 설명하는 배너와 버킷 상태 확인 버튼이 표시됩니다. 다음 단계는 잠재적 권한 오류를 식별하고 수정하는 데 도움이 됩니다.

버킷 상태 확인을 클릭합니다.

마이그레이션을 완료하는 옵션과 Cloud Storage 버킷 목록이 있는 메뉴가 나타납니다. 목록 로드가 완료되는 데 몇 분 정도 걸릴 수 있습니다.

이 목록에는 최근에 가져오기 및 내보내기 작업에 사용되었지만 현재 Firestore 서비스 에이전트에 읽기 및 쓰기 권한이 부여되지 않은 버킷이 포함됩니다.
프로젝트의 Datastore 모드 서비스 에이전트의 주 구성원 이름을 기록해 둡니다. 서비스 에이전트 이름이 액세스 권한을 부여할 서비스 에이전트 라벨 아래에 나타납니다.
나중에 가져오기 또는 내보내기 작업에 사용할 목록의 버킷에 다음 단계를 완료합니다.
1. 이 버킷의 테이블 행에서 수정을 클릭합니다. 그러면 새 탭에 버킷의 권한 페이지가 열립니다.
2. Add(추가)를 클릭합니다.
3. 새 주 구성원 필드에 Firestore 서비스 에이전트 이름을 입력합니다.
4. 역할 선택 필드에서 서비스 에이전트 > Firestore 서비스 에이전트를 선택합니다.
5. 저장을 클릭합니다.
6. Datastore 모드 가져오기/내보내기 페이지가 있는 탭으로 돌아갑니다.
7. 목록의 다른 버킷에 이 단계를 반복합니다. 목록의 모든 페이지를 확인해야 합니다.
Firestore 서비스 에이전트로 마이그레이션을 클릭합니다. 권한 확인에 실패한 버킷이 아직 있으면 마이그레이션을 클릭하여 마이그레이션을 확인해야 합니다.

마이그레이션이 완료되면 알림이 표시됩니다. 마이그레이션을 취소할 수 없습니다.

마이그레이션 상태 보기

프로젝트의 마이그레이션 상태를 확인하려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 데이터베이스 페이지로 이동합니다.

데이터베이스로 이동
데이터베이스 목록에서 필요한 데이터베이스를 선택합니다.
탐색 메뉴에서 가져오기/내보내기를 클릭합니다.
가져오기/내보내기 작업 실행 주 구성원 라벨 옆에 있는 주 구성원을 찾습니다.

주 구성원이 service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com이면 프로젝트가 이미 Firestore 서비스 에이전트로 마이그레이션된 것입니다. 마이그레이션을 취소할 수 없습니다.

프로젝트가 마이그레이션되지 않으면 버킷 상태 확인 버튼이 있는 페이지 상단에 배너가 표시됩니다. 마이그레이션을 완료하려면 Firestore 서비스 에이전트로 마이그레이션을 참조하세요.

조직 전체 정책 제약조건 추가

조직 정책에 다음 제약조건을 설정합니다.

가져오기/내보내기에 Firestore 서비스 에이전트가 필요합니다(firestore.requireP4SAforImportExport).

이 제약조건을 사용하려면 Firestore 서비스 에이전트를 사용하여 요청을 승인하는 가져오기 및 내보내기 작업이 필요합니다. 이 제약조건을 설정하려면 조직 정책 만들기 및 관리를 확인하세요.

이 조직 정책 제약조건을 적용해도 Firestore 서비스 에이전트에 적절한 Cloud Storage 버킷 권한이 자동으로 부여되지 않습니다.

제약조건이 가져오기 또는 내보내기 워크플로에 대한 권한 오류를 만드는 경우 중지하여 기본 서비스 계정을 다시 사용할 수 있습니다. Cloud Storage 버킷 권한을 확인 및 업데이트하면 제약조건을 다시 사용 설정할 수 있습니다.

항목 내보내기 및 가져오기

시작하기 전에

프로젝트에 gcloud 설정

권한

사용자 계정 권한

서비스 에이전트 권한

서비스 에이전트에 역할 할당

서비스 에이전트 이름 보기

내보내기 작업

가져오기 작업

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

모든 항목 내보내기

콘솔

gcloud

rest

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

특정 종류 또는 네임스페이스 내보내기

콘솔

gcloud

rest

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

메타데이터 파일

모든 항목 가져오기

콘솔

gcloud

rest

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

overall_export_metadata 파일 찾기

특정 종류 또는 네임스페이스 가져오기

콘솔

gcloud

rest

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

PITR 데이터에서 내보내기 및 가져오기

gcloud

변환 가져오기

장기 실행 작업 관리

모든 장기 실행 작업 나열

콘솔

gcloud

rest

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

작업 상태 확인

콘솔

gcloud

rest

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

완료 시간 예상

작업 취소

콘솔

gcloud

작업 삭제

gcloud

내보내기/가져오기 관리 결제 및 가격 책정

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

Datastore 관리자 백업과의 차이점

BigQuery로 가져오기

BigQuery 열 한도

서비스 에이전트 마이그레이션

승인 계정 보기

Cloud Storage 버킷 권한을 확인하고 업데이트하여 마이그레이션

서비스 에이전트 버킷 권한

Firestore 서비스 에이전트로 프로젝트 마이그레이션

마이그레이션 상태 보기

조직 전체 정책 제약조건 추가

프로젝트에 `gcloud` 설정

`overall_export_metadata` 파일 찾기