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

선택적 매개변수

  • spannerProjectId: 변경 내역을 읽어 올 프로젝트입니다. 이 매개변수의 기본값은 Dataflow 파이프라인이 실행되는 프로젝트입니다.
  • spannerDatabaseRole: 사용자가 변경 내역을 읽는 동안 데이터베이스 역할을 맡습니다. 데이터베이스 역할에는 변경 내역에서 읽는 데 필요한 권한이 있어야 합니다. 데이터베이스 역할을 지정하지 않으면 사용자에게 데이터베이스에서 읽는 데 필요한 IAM 권한이 있어야 합니다.
  • spannerMetadataTableName: 사용할 Cloud Spanner 변경 내역 커넥터 메타데이터 테이블 이름입니다. 제공하지 않으면 파이프라인 흐름 중에 Cloud Spanner 변경 내역 커넥터 메타데이터 테이블이 자동으로 생성됩니다. 기존 파이프라인을 업데이트할 때는 이 매개변수를 반드시 제공해야 하며, 이외의 경우에는 제공해서는 안 됩니다.
  • startTimestamp: 변경 내역을 읽는 데 사용할 시작 DateTime(https://tools.ietf.org/html/rfc3339)입니다. 예를 들면 2022-05-05T07:59:59Z입니다. 기본값은 파이프라인이 시작되는 시점의 타임스탬프입니다.
  • endTimestamp: 변경 내역을 읽는 데 사용할 종료 DateTime(https://tools.ietf.org/html/rfc3339)입니다. 예를 들면 2022-05-05T07:59:59Z입니다. 기본값은 미래의 무한대 시간입니다.
  • spannerHost: 템플릿에서 호출할 Cloud Spanner 엔드포인트입니다. 테스트에만 사용됩니다. (예: https://spanner.googleapis.com). 기본값은 https://spanner.googleapis.com입니다.
  • outputFileFormat: 출력 Cloud Storage 파일의 형식입니다. 허용되는 형식은 TEXT, AVRO입니다. 기본값은 AVRO입니다.
  • windowDuration: 데이터가 Cloud Storage에 기록되는 기간/크기입니다. 허용되는 형식은 Ns(초, 예: 5s), Nm(분, 예: 12m), Nh(시, 예: 2h)입니다. 예를 들면 5m과 같습니다. 기본값은 5m입니다.
  • rpcPriority: Cloud 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: 변경 스트림 출력용 파일 위치

다음 단계