대상 Cloud Storage 버킷이 Datastream과 동일한 프로젝트에 있으면 Datastream API를 사용 설정하면 충분합니다.
다른 프로젝트의 버킷에 작성하는 경우 Datastream과 연결된 서비스 계정에 이 버킷에 액세스할 수 있는 권한을 부여해야 합니다.
서비스 계정에 사용되는 이메일 주소를 가져옵니다. Google Cloud 콘솔 홈페이지에서 프로젝트 번호를 찾으면 됩니다. 서비스 계정의 이메일 주소는 service-[project_number]@gcp-sa-datastream.iam.gserviceaccount.com입니다.
이 이메일 주소에 대상 버킷에 쓸 수 있는 필수 권한(일반적으로 roles/storage.objectViewer, roles/storage.objectCreator 및 roles/storage.legacyBucketReader 권한)을 부여합니다.
대상 버킷 및 프리픽스 지정
스트림 구성에 프로젝트 이름, 버킷 이름, 파일 프리픽스(선택사항)를 제공하여 데이터가 작성되는 위치를 지정합니다.
쓰기 동작
지정된 스트림에 대한 데이터는 제공된 버킷 또는 파일 프리픽스([bucket]/[prefix]/[object name]/yyyy/mm/dd/hh/mm/[filename(idempotent)])에 작성됩니다.
데이터베이스 소스 경로의 객체 이름은 스키마 이름 다음에 테이블 이름(밑줄 '_'로 구분됨)입니다.
경로의 타임스탬프(hh/mm)는 이벤트 메타데이터의 소스 타임스탬프입니다.
백필 이벤트의 경우 타임스탬프는 백필 태스크가 시작된 시간(일반적으로 스트림이 시작되었거나 백필이 수동으로 트리거된 시간)을 나타냅니다.
CDC 이벤트의 경우 타임스탬프는 소스에서 레코드가 변경된 시간을 나타냅니다.
파일은 최대 파일 크기 또는 최대 제한 시간 중 먼저 도달하는 시점마다 순환됩니다. Datastream API를 사용하여 최대 파일 크기와 최대 제한 시간 값을 조정할 수 있습니다.
경우에 따라, 특히 스트림이 처음 실행될 때 백필과 CDC가 겹쳐 중복 이벤트가 발생할 수 있습니다. Datastream이 현재 데이터베이스 로그 파일(스트림이 시작되기 전에 생성)에서 읽기를 시작하면 이 로그 파일에는 백필에서 캡처하는 일부 이벤트도 포함됩니다. 이는 예상되는 동작이며 필요한 경우 이벤트 메타데이터를 사용하여 중복 이벤트를 제거할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eEnabling the Datastream API is necessary for writing to a Cloud Storage bucket, and if the bucket is in a different project, the Datastream service account needs permissions to access it.\u003c/p\u003e\n"],["\u003cp\u003eYou can define the destination for the streamed data by specifying the project name, bucket name, and an optional file prefix in the stream configuration.\u003c/p\u003e\n"],["\u003cp\u003eData is written to the bucket at a specific path format based on bucket, prefix, object name, and source event timestamps, with file rotation occurring when maximum file size, timeout, or source schema change is met.\u003c/p\u003e\n"],["\u003cp\u003eDuplicate events may occur during the initial stream setup when backfill and CDC overlap, but these can be filtered out using the event metadata.\u003c/p\u003e\n"],["\u003cp\u003eThe maximum event size for streaming data into Cloud Storage is 100 MB, and you can adjust the maximum file size and maximum timeout values using the Datastream API.\u003c/p\u003e\n"]]],[],null,["# Configure a Cloud Storage destination\n\nThis page describes how to configure Datastream to write data to a\nCloud Storage bucket.\n\nCloud Storage is a service for storing data in Google Cloud. You store the\ndata as objects, in containers called *buckets* . When you stream to\nCloud Storage, Datastream organizes data by object name and\ntimestamp. You can then consume your data using the Cloud Storage API.\nFor more information, see [About Cloud Storage buckets](/storage/docs/buckets).\n\nEnable the API\n--------------\n\nEnabling the Datastream API is sufficient when the destination Cloud Storage bucket is in the same project as Datastream.\n\nIf you're writing to a bucket in a different project, then you must give the [service account](https://cloud.google.com/docs/authentication#service_accounts) associated with the Datastream permission to access the bucket.\n\n1. Obtain the email address used for the service account. To do so, find the **Project number** in the Google Cloud console home page. The email address of the service account will be `service-[project_number]@gcp-sa-datastream.iam.gserviceaccount.com`.\n2. Give this email address the required permissions to write to the destination bucket (typically the `roles/storage.objectViewer`, `roles/storage.objectCreator` and `roles/storage.legacyBucketReader` permissions).\n\nSpecify the destination bucket and prefix\n-----------------------------------------\n\nProvide the project name, bucket name, and optional file prefix in the stream configuration to determine where the data is written.\n\nWrite behavior\n--------------\n\n- The data for a given stream is written to the provided bucket or file prefix at: `[bucket]/[prefix]/[object name]/yyyy/mm/dd/hh/mm/[filename(idempotent)]`.\n- The object name in the path for database sources is the schema name followed by the table name (separated by an underscore '_').\n- The timestamp in the path (hh/mm) is the source timestamp from the event metadata.\n - For backfill events, the timestamp represents the time when the backfill task was started (typically when the stream was started, or when backfill was manually triggered).\n - For CDC events, the timestamp represents when the record was changed on the source.\n- Files are rotated whenever either the maximum file size or maximum timeout is reached, whichever comes first. You can adjust the maximum file size and maximum timeout values using the [Datastream API](/datastream/docs/reference/rest/v1/projects.locations.streams#gcsdestinationconfig).\n- Additionally, files are rotated each time a source schema change is detected (For example, a new column is added.).\n- There can be multiple files within the same path for the same minute.\n- Consuming the data can be done according to the [Cloud Storage API](/storage/docs/json_api/v1).\n- The maximum event size when you stream data into Cloud Storage is 100 MB.\n\nIn some cases, most commonly when a stream first starts running, there is an overlap between backfill and CDC, resulting in duplicate events. This happens when Datastream starts reading from the current database log file (which was created before the stream was started), and this log file includes some events that are also captured by the backfill. This is anticipated behavior, and duplicate events can be eliminated using the [event metadata](/datastream/docs/events-and-streams#events), if necessary.\n\nWhat's next\n-----------\n\n- Learn how to [stream changes to data in near real-time with Datastream](/datastream/docs/quickstart-change-streaming-to-gcs)."]]
