Spanner change streams to Cloud Storage 템플릿

Spanner change streams to Cloud Storage 템플릿은 Spanner 데이터 변경 레코드를 스트리밍하고 Dataflow Runner v2를 사용하여 Cloud Storage 버킷에 쓰는 스트리밍 파이프라인입니다.

파이프라인은 Spanner 변경 내역 기록을 타임스탬프에 따라 기간으로 그룹화하며, 각 기간은 이 템플릿으로 구성할 수 있는 기간을 나타냅니다. 기간에 속한 타임스탬프가 있는 모든 레코드는 지연될 수 없으므로 기간 내에 존재한다고 보장됩니다. 또한 출력 샤드를 여러 개 정의할 수도 있습니다. 파이프라인은 샤드당 기간별로 하나의 Cloud Storage 출력 파일을 만듭니다. 출력 파일 내에서 레코드는 정렬되지 않습니다. 출력 파일은 사용자 구성에 따라 JSON 또는 AVRO 형식으로 작성될 수 있습니다.

Spanner 인스턴스 또는 Cloud Storage 버킷과 동일한 리전에서 Dataflow 작업을 실행하면 네트워크 지연 시간과 네트워크 전송 비용을 최소화할 수 있습니다. 작업 리전 외부에 있는 소스, 싱크, 스테이징 파일 위치 또는 임시 파일 위치를 사용하면 데이터가 리전 간에서 전송될 수 있습니다. Dataflow 리전에 대해 자세히 알아보세요.

변경 스트림, 변경 스트림 Dataflow 파이프라인 빌드 방법, 권장사항에 대해 자세히 알아보세요.

파이프라인 요구사항

  • 파이프라인을 실행하기 전에 Spanner 인스턴스가 있어야 합니다.
  • 파이프라인을 실행하기 전에 Spanner 데이터베이스가 있어야 합니다.
  • 파이프라인을 실행하기 전에 Spanner 메타데이터 인스턴스가 있어야 합니다.
  • 파이프라인을 실행하기 전에 Spanner 메타데이터 데이터베이스가 있어야 합니다.
  • 파이프라인을 실행하기 전에 Spanner 변경 내역이 있어야 합니다.
  • 파이프라인을 실행하기 전에 Cloud Storage 출력 버킷이 있어야 합니다.

템플릿 매개변수

필수 매개변수

  • spannerInstanceId: 변경 내역 데이터를 읽어올 Spanner 인스턴스 ID입니다.
  • spannerDatabase: 변경 내역 데이터를 읽어올 Spanner 데이터베이스입니다.
  • spannerMetadataInstanceId: 변경 내역 커넥터 메타데이터 테이블에 사용할 Spanner 인스턴스 ID입니다.
  • spannerMetadataDatabase: 변경 내역 커넥터 메타데이터 테이블에 사용할 Spanner 데이터베이스입니다.
  • spannerChangeStreamName: 읽어 올 Spanner 변경 내역의 이름입니다.
  • gcsOutputDirectory: 출력 파일을 쓰기 위한 경로와 파일 이름 프리픽스입니다. 슬래시로 끝나야 합니다. DateTime 형식은 날짜 및 시간 포맷터의 디렉터리 경로를 파싱하는 데 사용됩니다. (예: gs://your-bucket/your-path)

선택적 매개변수

  • spannerProjectId: 변경 내역을 읽어올 Spanner 데이터베이스가 포함된 Google Cloud 프로젝트의 ID입니다. 또한 이 프로젝트에서 변경 내역 커넥터 메타데이터 테이블이 생성됩니다. 이 매개변수의 기본값은 Dataflow 파이프라인이 실행되는 프로젝트입니다.
  • spannerDatabaseRole: 템플릿을 실행할 때 사용할 Spanner 데이터베이스 역할입니다. 이 매개변수는 템플릿을 실행하는 IAM 주 구성원이 세분화된 액세스 제어 사용자인 경우에만 필요합니다. 데이터베이스 역할에는 변경 내역에 대한 SELECT 권한과 변경 내역의 읽기 함수에 대한 EXECUTE 권한이 있어야 합니다. 자세한 내용은 변경 내역에 대한 세분화된 액세스 제어(https://cloud.google.com/spanner/docs/fgac-change-streams)를 참조하세요.
  • spannerMetadataTableName: 사용할 Spanner 변경 내역 커넥터 메타데이터 테이블 이름입니다. 제공하지 않으면 파이프라인 실행 중에 Spanner 변경 내역 메타데이터 테이블이 자동으로 생성됩니다. 기존 파이프라인을 업데이트할 때는 이 매개변수의 값을 제공해야 합니다. 그렇지 않으면 이 매개변수를 사용하지 마세요.
  • startTimestamp: 변경 내역을 읽는 데 사용할 시작 DateTime으로 Ex-2021-10-12T07:20:50.52Z 형식입니다. 기본값은 파이프라인이 시작되는 시점의 타임스탬프, 즉 현재 시간입니다.
  • endTimestamp: 변경 내역을 읽는 데 사용할 종료 DateTime(경계 포함)입니다. 예를 들면 Ex-2021-10-12T07:20:50.52Z입니다. 기본값은 미래의 무한대 시간입니다.
  • spannerHost: 템플릿에서 호출할 Cloud Spanner 엔드포인트입니다. 테스트에만 사용됩니다. (예: https://spanner.googleapis.com). 기본값은 https://spanner.googleapis.com입니다.
  • outputFileFormat: 출력 Cloud Storage 파일의 형식입니다. 허용되는 형식은 TEXT 및 AVRO입니다. 기본값은 AVRO입니다.
  • windowDuration: 범위 기간은 데이터가 출력 디렉터리에 기록되는 간격입니다. 파이프라인의 처리량을 기준으로 기간을 구성합니다. 예를 들어 처리량이 높을수록 데이터가 메모리에 적합하도록 더 작은 범위가 필요할 수 있습니다. 기본값은 5m(5분)이며 최소 1s(1초)입니다. 허용되는 형식은 [int]s(초 단위, 예: 5s), [int]m(분 단위, 예: 12m), [int]h(시간 단위, 예: 2h)입니다. 예를 들면 5m과 같습니다.
  • rpcPriority: Spanner 호출의 요청 우선순위입니다. 값은 HIGH, MEDIUM 또는 LOW여야 합니다. 기본값은 HIGH입니다.
  • outputFilenamePrefix: 윈도우 설정된 각 파일에 넣을 프리픽스입니다. (예: output-) 기본값은 output입니다.
  • numShards: 쓰는 동안에 생성되는 최대 출력 샤드 수입니다. 샤드 수가 많을수록 Cloud Storage 쓰기 처리량이 높아지지만 출력 Cloud Storage 파일을 처리할 때 샤드 간에 데이터 집계 비용이 늘어날 수 있습니다. 기본값은 20입니다.

템플릿 실행

콘솔

  1. Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다.
    2. 템플릿에서 작업 만들기로 이동
  2. 작업 이름 필드에 고유한 작업 이름을 입력합니다.
  3. (선택사항): 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전은 us-central1입니다.

    Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.

  4. Dataflow 템플릿 드롭다운 메뉴에서 the Cloud Spanner change streams to Google Cloud Storage template을 선택합니다.
  5. 제공된 매개변수 필드에 매개변수 값을 입력합니다.
  6. 작업 실행을 클릭합니다.

gcloud

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

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/Spanner_Change_Streams_to_Google_Cloud_Storage \
    --region REGION_NAME \
    --parameters \
spannerInstanceId=SPANNER_INSTANCE_ID,\
spannerDatabase=SPANNER_DATABASE,\
spannerMetadataInstanceId=SPANNER_METADATA_INSTANCE_ID,\
spannerMetadataDatabase=SPANNER_METADATA_DATABASE,\
spannerChangeStreamName=SPANNER_CHANGE_STREAM,\
gcsOutputDirectory=GCS_OUTPUT_DIRECTORY

다음을 바꿉니다.

  • JOB_NAME: 선택한 고유한 작업 이름
  • VERSION: 사용할 템플릿 버전

    다음 값을 사용할 수 있습니다.

  • REGION_NAME: Dataflow 작업을 배포할 리전(예: us-central1)
  • SPANNER_INSTANCE_ID: Cloud Spanner 인스턴스 ID
  • SPANNER_DATABASE: Cloud Spanner 데이터베이스
  • SPANNER_METADATA_INSTANCE_ID: Cloud Spanner 메타데이터 인스턴스 ID
  • SPANNER_METADATA_DATABASE: Cloud Spanner 메타데이터 데이터베이스
  • SPANNER_CHANGE_STREAM: Cloud Spanner 변경 내역
  • GCS_OUTPUT_DIRECTORY: 변경 스트림 출력용 파일 위치

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",
      "parameters": {
          "spannerInstanceId": "SPANNER_INSTANCE_ID",
          "spannerDatabase": "SPANNER_DATABASE",
          "spannerMetadataInstanceId": "SPANNER_METADATA_INSTANCE_ID",
          "spannerMetadataDatabase": "SPANNER_METADATA_DATABASE",
          "spannerChangeStreamName": "SPANNER_CHANGE_STREAM",
          "gcsOutputDirectory": "GCS_OUTPUT_DIRECTORY"
      },
      "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/Spanner_Change_Streams_to_Google_Cloud_Storage",
   }
}

다음을 바꿉니다.

  • PROJECT_ID: Dataflow 작업을 실행하려는 Google Cloud 프로젝트 ID
  • JOB_NAME: 선택한 고유한 작업 이름
  • VERSION: 사용할 템플릿 버전

    다음 값을 사용할 수 있습니다.

  • LOCATION: Dataflow 작업을 배포할 리전(예: us-central1)
  • SPANNER_INSTANCE_ID: Cloud Spanner 인스턴스 ID
  • SPANNER_DATABASE: Cloud Spanner 데이터베이스
  • SPANNER_METADATA_INSTANCE_ID: Cloud Spanner 메타데이터 인스턴스 ID
  • SPANNER_METADATA_DATABASE: Cloud Spanner 메타데이터 데이터베이스
  • SPANNER_CHANGE_STREAM: Cloud Spanner 변경 내역
  • GCS_OUTPUT_DIRECTORY: 변경 스트림 출력용 파일 위치

다음 단계