Datastream to Cloud Spanner 템플릿

Datastream to Cloud Spanner 템플릿은 Cloud Storage 버킷에서 Datastream 이벤트를 읽고 Cloud Spanner 데이터베이스에 쓰는 스트리밍 파이프라인입니다. 데이터를 Datastream 소스에서 Cloud Spanner로 마이그레이션합니다.

마이그레이션에 필요한 모든 테이블은 템플릿을 실행하기 전에 대상 Cloud Spanner 데이터베이스에 있어야 합니다. 따라서 데이터 마이그레이션 전에 소스 데이터베이스에서 대상 Cloud Spanner로 스키마 마이그레이션을 완료해야 합니다. 마이그레이션하기 전에 데이터가 테이블에 있을 수 있습니다. 이 템플릿은 Datastream 스키마 변경사항을 Cloud Spanner 데이터베이스에 전파하지 않습니다.

데이터 일관성은 모든 데이터가 Cloud Spanner에 기록될 때 마이그레이션 종료 시에만 보장됩니다. Cloud Spanner에 쓰인 각 레코드의 순서 정보를 저장하도록 이 템플릿은 Cloud Spanner 데이터베이스의 각 테이블에 추가 테이블(섀도 테이블이라고 함)을 만듭니다. 이 테이블은 마이그레이션 종료 시 일관성을 보장하는 데 사용됩니다. 섀도 테이블은 마이그레이션 후에 삭제되지 않으며 마이그레이션 종료 시 유효성 검사 목적으로 사용될 수 있습니다.

스키마 불일치, 잘못된 형식의 JSON 파일 또는 변환 실행으로 발생하는 오류와 같은 작업 중에 발생하는 모든 오류는 오류 큐에 기록됩니다. 오류 큐는 오류와 함께 오류가 발생한 모든 Datastream 이벤트를 텍스트 형식으로 저장하는 Cloud Storage 폴더입니다. 오류는 일시적이거나 영구적일 수 있으며 오류 큐의 적절한 Cloud Storage 폴더에 저장됩니다. 일시적인 오류는 자동으로 재시도되지만 영구 오류는 그렇지 않습니다. 영구적인 오류가 발생할 경우 변경 이벤트를 수정하고 템플릿이 실행되는 동안 재시도 가능한 버킷으로 이동할 수 있습니다.

파이프라인 요구사항

실행 중 또는 시작되지 않음 상태의 Datastream 스트림
Datastream 이벤트가 복제되는 Cloud Storage 버킷
기존 테이블이 있는 Cloud Spanner 데이터베이스 이러한 테이블은 비어 있거나 데이터를 포함할 수 있습니다.

템플릿 매개변수

매개변수	설명
`inputFilePattern`	Cloud Storage에서 복제할 Datastream 파일의 파일 위치입니다. 일반적으로 이는 스트림의 루트 경로입니다.
`streamName`	스키마 정보와 소스 유형을 폴링할 스키마의 이름이나 템플릿입니다.
`instanceId`	변경사항이 복제된 Cloud Spanner 인스턴스입니다.
`databaseId`	변경사항이 복제된 Cloud Spanner 데이터베이스입니다.
`projectId`	Cloud Spanner 프로젝트 ID입니다.
`deadLetterQueueDirectory`	(선택사항) 오류 큐 출력을 저장할 파일 경로입니다. 기본값은 Dataflow 작업의 임시 위치 아래에 있는 디렉터리입니다.
`inputFileFormat`	(선택사항) Datastream에서 생성한 출력 파일의 형식입니다. 예를 들면 `avro,json`입니다. 기본값은 `avro`입니다.
`shadowTablePrefix`	(선택사항) 섀도우 테이블의 이름을 지정하는 데 사용되는 프리픽스입니다. 기본값: `shadow_`

템플릿 실행

콘솔

Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다.

템플릿에서 작업 만들기로 이동

작업 이름 필드에 고유한 작업 이름을 입력합니다.
선택사항: 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전 엔드포인트는 us-central1입니다.
Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.
Dataflow 템플릿 드롭다운 메뉴에서 the Cloud Datastream to Spanner template을 선택합니다.
제공된 매개변수 필드에 매개변수 값을 입력합니다.
작업 실행을 클릭합니다.

gcloud

셸 또는 터미널에서 템플릿을 실행합니다.

gcloud beta dataflow flex-template run JOB_NAME \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Cloud_Datastream_to_Spanner \
    --parameters \
inputFilePattern=GCS_FILE_PATH,\
streamName=STREAM_NAME,\
instanceId=CLOUDSPANNER_INSTANCE,\
databaseId=CLOUDSPANNER_DATABASE,\
deadLetterQueueDirectory=DLQ

다음을 바꿉니다.

PROJECT_ID: Dataflow 작업을 실행할 Cloud 프로젝트 ID
JOB_NAME: 선택한 고유한 작업 이름
REGION_NAME: Dataflow 작업을 배포할 리전 엔드포인트(예: us-central1)
VERSION: 사용할 템플릿 버전
다음 값을 사용할 수 있습니다.
- latest: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.
- 버전 이름(예: 2021-09-20-00_RC00): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
주의: 최신 버전의 템플릿이 브레이킹 체인지로 업데이트될 수 있습니다. 프로덕션 환경에서는 이러한 브레이킹 체인지가 프로덕션 워크플로에 영향을 미치지 않도록 최신 날짜가 지정된 상위 폴더에 보관된 템플릿을 사용해야 합니다.
GCS_FILE_PATH: Datastream 이벤트를 저장하는 데 사용되는 Cloud Storage 경로입니다. 예를 들면 gs://bucket/path/to/data/입니다.
CLOUDSPANNER_INSTANCE: Cloud Spanner 인스턴스
CLOUDSPANNER_DATABASE: Cloud Spanner 데이터베이스
DLQ: 오류 큐 디렉터리의 Cloud Storage 경로

API

REST API를 사용하여 템플릿을 실행하려면 HTTP POST 요청을 전송합니다. API 및 승인 범위에 대한 자세한 내용은 projects.templates.launch를 참조하세요.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launch_parameter": {
      "jobName": "JOB_NAME",
      "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Cloud_Datastream_to_Spanner",
      "parameters": {
          "inputFilePattern": "GCS_FILE_PATH",
          "streamName": "STREAM_NAME"
          "instanceId": "CLOUDSPANNER_INSTANCE"
          "databaseId": "CLOUDSPANNER_DATABASE"
          "deadLetterQueueDirectory": "DLQ"
      }
   }
}

다음을 바꿉니다.

PROJECT_ID: Dataflow 작업을 실행할 Cloud 프로젝트 ID
JOB_NAME: 선택한 고유한 작업 이름
LOCATION: Dataflow 작업을 배포할 리전 엔드포인트(예: us-central1)
VERSION: 사용할 템플릿 버전
다음 값을 사용할 수 있습니다.
- latest: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.
- 버전 이름(예: 2021-09-20-00_RC00): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
주의: 최신 버전의 템플릿이 브레이킹 체인지로 업데이트될 수 있습니다. 프로덕션 환경에서는 이러한 브레이킹 체인지가 프로덕션 워크플로에 영향을 미치지 않도록 최신 날짜가 지정된 상위 폴더에 보관된 템플릿을 사용해야 합니다.
GCS_FILE_PATH: Datastream 이벤트를 저장하는 데 사용되는 Cloud Storage 경로입니다. 예를 들면 gs://bucket/path/to/data/입니다.
CLOUDSPANNER_INSTANCE: Cloud Spanner 인스턴스
CLOUDSPANNER_DATABASE: Cloud Spanner 데이터베이스
DLQ: 오류 큐 디렉터리의 Cloud Storage 경로