항목 내보내기 및 가져오기

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

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

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

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

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

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

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

  • 내보내기/가져오기 관리 서비스는 동시 실행되는 내보내기 및 가져오기 작업의 개수를 50개로 제한하며 하나의 프로젝트에 대해 분당 최대 20개의 내보내기 및 가져오기 요청을 허용합니다.

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

시작하기 전에

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

  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 버킷에 대한 읽기 또는 쓰기 권한을 부여하는 Cloud Storage IAM 역할을 사용자 계정에 할당합니다.

환경 설정

데이터를 내보내거나 가져오기 전에 사용자 계정을 사용하여 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 도구가 대기하는 것을 방지하려면 --async 플래그를 추가하면 됩니다.

gcloud

gcloud datastore export --namespaces="(default)" gs://${BUCKET}

프로토콜

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "namespaceIds": [""], }, }'

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

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="NAMESPACE1,NAMESPACE2" gs://${BUCKET}

프로토콜

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "kinds": ["KIND1", "KIND2", …], "namespaceIds": ["NAMESPACE1", "NAMESPACE2", …], }, }

항목 가져오기

내보내기/가져오기 관리 서비스를 사용하여 이전에 내보낸 항목을 가져오려면 아래 명령어를 사용하세요. 작업이 완료될 때까지 gcloud 도구가 대기하는 것을 방지하려면 --async 플래그를 추가하면 됩니다.

gcloud

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

프로토콜

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:import
-d '{ "inputUrl": "gs://'${BUCKET}'/[PATH]/[FILE].overall_export_metadata", }'

가져오기 위치에 사용할 값을 확인하려면 Google Cloud Platform 콘솔의 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

프로토콜

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

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

내보내기 및 가져오기를 수행하는 데 오랜 시간이 걸릴 수 있습니다. 내보내기 또는 가져오기를 수행할 때 작업이 완료될 때까지 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는 장기 실행 작업의 상태를 확인하고 장기 실행 작업을 취소, 삭제, 나열하기 위한 작업 관리 API를 제공합니다.

메소드 설명
projects.operations.cancel 장기 실행 작업을 취소합니다.
projects.operations.delete 장기 실행 작업을 삭제합니다.

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

장기 실행 작업 나열

장기 실행 작업을 나열하려면 다음을 실행하세요.

gcloud

gcloud datastore operations list

프로토콜

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
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 값을 사용하세요.

예상 완료 시간 확인

장기 실행 작업의 상태를 요청하면 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"
        },
        ...

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

내보내기/가져오기 관리 서비스를 사용하기 전에 Google Cloud Platform 프로젝트의 결제를 사용 설정해야 합니다. 내보내기 및 가져오기 작업은 Datastore 모드 가격에 나열된 요금을 기준으로 항목 읽기 및 쓰기 작업에 대해 청구됩니다.

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

청구에 대한 자세한 내용은 청구 및 결제 지원을 참조하세요.

권한

내보내기 및 가져오기 작업을 시작하려면 사용자 계정의 IAM 역할datastore.databases.exportdatastore.databases.import 권한을 부여해야 합니다. 예를 들어 Cloud Datastore Import Export Admin 역할은 두 권한을 모두 부여합니다. 마찬가지로 명령줄에서 curl을 사용하여 REST 요청을 제출하는 경우 사용자 계정에 이러한 권한을 부여하는 IAM 역할을 할당해야 합니다. Datastore 모드 데이터베이스 권한에 대한 자세한 내용은 Identity and Access Management(IAM)를 참조하세요.

예제 cron 앱을 사용하는 경우에는 요청에서 GCP 프로젝트의 App Engine 기본 서비스 계정을 사용합니다. App Engine 기본 서비스 계정에 Cloud Datastore Import Export Admin 역할 또는 datastore.databases.export 권한을 부여하는 다른 역할을 부여해야 합니다.

또한 모든 내보내기 요청의 경우 요청하는 계정 및 GCP 프로젝트의 App Engine 기본 서비스 계정 모두 다음과 같은 Cloud Storage 버킷 권한을 부여하는 IAM 역할이 있어야 합니다.

권한 이름 설명
storage.buckets.get IAM 정책을 제외한 버킷 메타데이터를 읽습니다.
storage.objects.create 새 객체를 버킷에 추가합니다.
storage.objects.list 버킷에 객체를 나열합니다. 또한 나열할 때는 ACL을 제외한 객체 메타데이터를 읽습니다.

Cloud Storage 역할 목록은 Cloud Storage IAM 역할을 참조하세요. 예를 들어 Storage Admin 또는 Storage Legacy Bucket Writer 역할은 내보내기에 필요한 모든 Cloud Storage 권한을 포함하며 전체 프로젝트 또는 특정 버킷에 적용될 수 있습니다. Storage Object Creator 역할은 내보내기에 필요한 모든 Cloud Storage 권한을 포함하지 않습니다.

가져오기 요청의 경우, 요청 계정 및 GCP 프로젝트의 기본 서비스 계정 모두에게 다음과 같은 Cloud Storage 버킷 작업 권한을 부여하는 IAM 역할이 있어야 합니다.

권한 이름 설명
storage.objects.get ACL을 제외한 객체 데이터 및 메타데이터를 읽습니다.
storage.objects.list 버킷에 객체를 나열합니다. 또한 나열할 때는 ACL을 제외한 객체 메타데이터를 읽습니다.

Storage Object Viewer 역할은 가져오기에 필요한 모든 권한을 부여합니다.

Cloud Datastore 관리자 백업의 차이

이전에 백업을 위해 Cloud Datastore 관리자 콘솔을 사용했다면 다음과 같은 차이를 확인하게 됩니다.

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

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

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

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

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

BigQuery로 가져오기

관리형 내보내기를 통해 내보낸 데이터를 BigQuery로 가져오려면 Datastore 모드 백업에서 데이터 로드를 참조하세요.

제한사항

  • 항목 필터를 지정하지 않고 내보낸 데이터는 BigQuery에 로드할 수 없습니다. 데이터를 BigQuery로 가져오려면 내보내기 요청의 항목 필터에 하나 이상의 종류 이름을 포함해야 합니다.
이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

Cloud Datastore 문서