항목 내보내기 및 가져오기

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

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

  • 내보내기 서비스에서는 eventual consistency를 가지는 읽기를 사용합니다. 따라서 내보내기가 동일한 시점에 이루어졌다고 추측할 수 없습니다. 내보내기를 시작한 이후에 작성된 항목은 포함하고 내보내기 시작 전에 작성된 항목은 제외할 수도 있습니다.

  • 내보내기에는 어떠한 색인도 포함되지 않습니다. 데이터를 가져오면 필수 색인이 데이터베이스의 현재 색인 정의를 사용하여 자동으로 다시 구축됩니다. 항목당 속성 값 색인 설정은 내보내기에 포함되고 가져올 때도 반영됩니다.

  • 가져오기를 수행하면 항목에 새로운 ID가 할당되지 않고, 내보낸 시점에 있던 ID를 사용하여 동일한 ID의 기존 항목을 덮어씁니다. 항목을 가져오는 동안에는 ID가 예약됩니다. 이 기능은 가져오기를 실행하는 동안 쓰기가 사용 설정된 경우 새 항목과 ID의 충돌을 방지합니다.

  • 가져오기의 영향을 받지 않는 데이터베이스 내 항목은 가져오기 후에도 데이터베이스에 유지됩니다.

  • 하나의 Datastore 모드 데이터베이스에서 내보낸 데이터를 다른 Datastore 모드 데이터베이스(다른 프로젝트에 있는 경우도 해당)로 가져올 수 있습니다.

  • 관리형 내보내기 및 가져오기 서비스는 동시 실행되는 내보내기와 가져오기 횟수를 50회로 제한하며 한 프로젝트의 내보내기 및 가져오기 요청을 분당 최대 20개까지 허용합니다.

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

  • 항목의 하위 집합을 가져오거나 BigQuery로 데이터를 가져오려면 내보낼 때 항목 필터를 지정해야 합니다.

시작하기 전에

관리형 내보내기 및 가져오기 서비스를 사용하려면 먼저 다음 태스크를 완료해야 합니다.

  1. Google Cloud Platform 프로젝트에 결제를 사용 설정합니다. 결제가 사용 설정된 GCP 프로젝트만 내보내기 및 가져오기 기능을 사용할 수 있습니다.

  2. Datastore 모드의 Cloud Firestore 데이터베이스 위치와 동일한 위치에 Cloud Storage 버킷을 만듭니다. 모든 내보내기 및 가져오기 작업은 Cloud Storage를 기반으로 수행되므로 Cloud Storage 버킷과 Datastore 모드의 Cloud Firestore 데이터베이스에 동일한 위치를 사용해야 합니다. 내보내기 및 가져오기 작업에 요청자 지불 버킷을 사용할 수 없습니다.

  3. 데이터를 내보내는 경우에는 datastore.databases.export 권한을 부여하고 데이터를 가져오는 경우에는 datastore.databases.import 권한을 부여하는 IAM 역할을 사용자 계정에 할당합니다. 예를 들어 Cloud Datastore Import Export Admin 역할은 두 권한을 모두 부여합니다.

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

환경 설정

데이터를 내보내거나 가져오기 전에 먼저 gcloud 도구에 환경 변수를 설정하고 사용자 계정을 사용하여 인증해야 합니다.

  1. GCP 프로젝트 ID의 환경 변수를 설정합니다.

    PROJECT_ID="YOUR_PROJECT_ID"
    
  2. 이 변수를 사용하여 gcloud 도구의 활성 구성으로 프로젝트를 설정합니다.

    gcloud config set project ${PROJECT_ID}
    
  3. gcloud 도구를 사용하여 인증합니다.

    gcloud auth login
    
  4. Cloud Storage 버킷 ID의 환경 변수를 설정합니다.

    BUCKET="YOUR_BUCKET_NAME[/NAMESPACE_PATH]"
    

    여기서 YOUR_BUCKET_NAME은 Cloud Storage 버킷의 이름이고 NAMESPACE_PATH는 선택적 Cloud Storage 네임스페이스 경로(Datastore 모드 네임스페이스가 아님)입니다. Cloud Storage 네임스페이스 경로에 대한 자세한 내용은 객체 이름 고려 사항을 참조하세요.

관리형 내보내기 및 가져오기 작업 시작

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

모든 항목 내보내기

데이터베이스에 있는 모든 항목을 내보내려면 gcloud datastore export 명령어를 사용합니다. 작업이 완료될 때까지 gcloud 도구가 대기하는 것을 방지하려면 --async 플래그를 추가하면 됩니다.

gcloud

gcloud datastore export gs://${BUCKET} --async

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",
}

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

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

특정 종류 또는 네임스페이스의 하위 집합을 내보내려면 종류 및 네임스페이스 ID의 값을 지정한 항목 필터를 제공합니다.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://${BUCKET} --async

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"],
  },
}

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

메타데이터 파일 내보내기

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

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

protoc --decode_raw < export0.export_metadata

모든 항목 가져오기

gcloud datastore import 명령어를 사용하면 관리형 내보내기 서비스로 이전에 내보낸 모든 항목을 가져올 수 있습니다. 작업이 완료될 때까지 gcloud 도구가 대기하는 것을 방지하려면 --async 플래그를 추가하면 됩니다.

gcloud

gcloud datastore import gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata --async

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",
}

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

Google Cloud Platform Console에서 Cloud Storage UI를 사용하여 버킷을 확인하거나 내보내기가 완료된 후 gcloud datastore export 출력 또는 ExportEntitiesResponse를 검사하여 가져오기 위치에 사용할 값을 확인할 수 있습니다. 가져오기 위치의 예시 값은 다음과 같습니다.

gcloud

gs://${BUCKET}/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata --async

rest

"outputUrl": "gs://'${BUCKET}'/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

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

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

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

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata --async

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"],
  },
}

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

비동기식 내보내기 또는 가져오기

내보내기 및 가져오기를 수행하는 데 시간이 오래 걸릴 수 있습니다. 내보내기 또는 가져오기를 수행할 때 작업이 완료될 때까지 gcloud 도구가 대기하는 것을 방지하려면 --async 플래그를 지정하면 됩니다.

내보내기 또는 가져오기 작업을 시작한 후 gcloud 도구에서 반환된 식별자를 사용하여 작업 상태를 확인할 수 있습니다. 예를 들면 다음과 같습니다.

gcloud datastore operations describe ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI

--async 플래그를 잊어버린 경우 Ctrl+c를 사용하여 작업 완료 시까지의 대기를 중지할 수도 있습니다. Ctrl+c를 입력해도 작업은 취소되지 않습니다.

장기 실행 작업 관리

장기 실행 작업은 완료하는 데 상당한 시간이 걸릴 수 있는 메소드 호출입니다. Datastore 모드 데이터베이스는 데이터를 내보내거나 가져올 때 장기 실행 작업을 생성합니다.

예를 들어 내보내기를 시작하면 Datastore 모드 데이터베이스에서는 내보내기 상태를 추적하는 장기 실행 작업을 생성합니다. 내보내기가 시작될 때 출력되는 내용은 다음과 같습니다.

{
  "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2017-05-25T23:54:39.583780Z",
      "operationType": "EXPORT_ENTITIES"
    },
    "progressEntities": {},
    "progressBytes": {},
    "entityFilter": {
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
  }
}

name 필드 값은 장기 실행 작업의 ID입니다.

Datastore 모드의 Cloud Firestore는 장기 실행 작업의 상태를 확인하고 장기 실행 작업을 취소, 삭제, 나열하는 작업 Admin API를 제공합니다.

메서드 설명
projects.operations.cancel 장기 실행 작업을 취소합니다.
projects.operations.delete 장기 실행 작업을 삭제합니다.
참고: 작업을 삭제해도 취소되지 않습니다.
projects.operations.get 장기 실행 작업 상태를 가져옵니다.
projects.operations.list 장기 실행 작업을 나열합니다.

장기 실행 작업 나열

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

gcloud

gcloud datastore operations list

rest

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

  • project-id: 프로젝트 ID

HTTP 메서드 및 URL:

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

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

이 예시 출력은 최근 완료된 내보내기 작업을 보여줍니다. 완료 후 며칠 동안 작업에 액세스할 수 있습니다.

{
  "operations": [
    {
      "name": "projects/[YOUR_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://[YOUR_BUCKET_NAME]"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://[YOUR_BUCKET_NAME]/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

항목을 가져올 때는 input_url 값을 사용합니다.

완료 시간 예상

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

또한 장기 실행 작업 상태를 요청하면 workEstimatedworkCompleted 측정항목이 반환됩니다. 이러한 각 측정항목은 바이트 수와 항목 수로 반환됩니다. workEstimated데이터베이스 통계를 기준으로 작업에서 처리할 것으로 예상되는 총 바이트 및 항목 수를 나타냅니다. workCompleted는 지금까지 처리된 바이트 및 항목 수를 나타냅니다. 작업이 완료되면 workCompleted에 실제로 처리된 총 바이트 및 총 항목 수가 반영되며, 이는 workEstimated 값보다 클 수 있습니다.

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

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

{
  "operations": [
    {
      "name": "projects/[YOUR_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 Platform 프로젝트의 결제를 사용 설정해야 합니다. 내보내기 및 가져오기 작업은 다음 방법으로 Google Cloud Platform 비용을 발생시킵니다.

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

권한

내보내기 및 가져오기 작업을 실행하려면 사용자 계정과 프로젝트의 기본 서비스 계정에 아래 설명된 Cloud Identity and Access Management 권한이 있어야 합니다.

사용자 계정 권한

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

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

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

기본 서비스 계정 권한

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

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

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

기본 서비스 계정에 역할 할당

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

gsutil iam ch serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

또는 GCP Console을 사용하여 이 역할을 할당할 수 있습니다.

내보내기 작업

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

  • 스토리지 관리자
  • 스토리지 객체 관리자
  • 스토리지 기존 버킷 작성자

다음 권한이 있는 Cloud IAM 커스텀 역할을 만들 수도 있습니다.

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.list

가져오기 작업

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

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

다음 권한이 있는 Cloud IAM 커스텀 역할을 만들 수도 있습니다.

  • storage.buckets.get
  • storage.objects.get

Cloud Datastore 관리자 백업의 차이

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

  • 관리형 내보내기 및 가져오기 서비스의 GUI가 없습니다.

  • 관리 내보내기로 생성된 내보내기가 Cloud Datastore 관리자 콘솔에 표시되지 않습니다. 관리형 내보내기 및 가져오기는 App Engine의 백업 및 복원 기능으로 데이터를 공유하지 않고 GCP Console을 통해 관리되는 새로운 서비스입니다.

  • 관리형 내보내기 및 가져오기 서비스는 Cloud Datastore 관리자 백업과 동일한 메타데이터를 지원하지 않으며 진행 상태를 데이터베이스에 저장하지 않습니다. 내보내기 및 가져오기 작업 진행도 확인에 대한 자세한 내용은 장기 실행 작업 관리를 참조하세요.

  • 내보내기 및 가져오기 관리 작업의 서비스 로그를 확인할 수 없습니다.

  • 가져오기 관리 서비스는 Cloud Datastore 관리자 백업 파일과 역호환됩니다. 관리형 가져오기 서비스를 사용하여 Cloud Datastore 관리자 백업 파일을 가져올 수 있지만 Cloud Datastore 관리 콘솔을 사용하여 관리형 내보내기 출력을 가져올 수 없습니다.

BigQuery로 가져오기

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

제한사항

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