Cloud Storage의 이벤트 기반 전송

Storage Transfer Service는 Google Cloud의 이벤트 알림을 리슨하여 Cloud Storage 버킷에 추가 또는 업데이트된 데이터를 자동으로 전송할 수 있습니다. 이벤트 기반 전송의 이점에 대해 자세히 알아보세요.

Cloud Storage의 이벤트 기반 전송은 Pub/Sub 알림을 사용하여 소스 버킷의 객체가 수정되거나 추가된 시점을 확인합니다. 객체 삭제는 감지되지 않습니다. 소스에서 객체를 삭제해도 대상 버킷에 있는 연결된 객체는 삭제되지 않습니다.

이벤트 기반 전송은 항상 Cloud Storage 버킷을 대상으로 사용합니다.

권한 구성

  1. 프로젝트의 Storage Transfer Service 서비스 에이전트 이름을 찾습니다.

    1. googleServiceAccounts.get 참조 페이지로 이동하세요.

      이 메서드 사용해 보기라는 제목의 대화형 패널이 열립니다.

    2. 패널의 요청 매개변수에 프로젝트 ID를 입력합니다. 여기에서 지정하는 프로젝트는 Storage Transfer Service 관리를 위해 사용 중인 프로젝트여야 하고, 이 프로젝트는 소스 버킷의 프로젝트와 다를 수 있습니다.

    3. 실행을 클릭합니다.

    서비스 에이전트의 이메일이 accountEmail 값으로 반환됩니다. 이 값을 복사합니다.

    서비스 에이전트의 이메일에는 project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com 형식이 사용됩니다.

  2. Storage Transfer Service 서비스 에이전트에 Pub/Sub Subscriber 역할을 부여합니다.

    Cloud 콘솔

    콘솔을 통한 액세스 제어의 안내에 따라 Storage Transfer Service 서비스에 Pub/Sub Subscriber 역할을 부여합니다. Google Cloud 역할은 주제, 구독 또는 프로젝트 수준에서 부여할 수 있습니다.

    gcloud CLI

    정책 설정의 안내에 따라 다음 바인딩을 추가합니다.

    {
      "role": "roles/pubsub.subscriber",
      "members": [
        "serviceAccount:project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com"
    }

Pub/Sub 구성

  1. Cloud Storage에서 Pub/Sub를 사용하기 위한 기본 요건을 충족했는지 확인합니다.

  2. 소스 Cloud Storage 버킷에 대한 Pub/Sub 알림을 만듭니다.

    콘솔에서는 Pub/Sub 알림을 관리할 수 없습니다. Google Cloud 대신 gcloud CLI 또는 사용 가능한 클라이언트 라이브러리 중 하나를 사용하세요.

    gcloud storage buckets notifications create gs://SOURCE_BUCKET_NAME --topic=TOPIC_NAME
  3. 주제에 대한 pull 구독을 만듭니다. 전송 작업마다 별도의 정기 결제를 만들어야 합니다.

    다음 예는 가져오기 구독을 만드는 Google Cloud CLI 명령어를 보여줍니다. 콘솔 안내 및 클라이언트 라이브러리 코드는 풀 정기 결제 만들기를 참고하세요.

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_NAME --ack-deadline=300

전송 작업 만들기

REST API 또는 Google Cloud 콘솔을 사용하여 이벤트 기반 전송 작업을 만들 수 있습니다.

전송 작업 이름에 개인 식별 정보(PII) 또는 보안 데이터와 같은 민감한 정보를 포함하지 마세요. 리소스 이름은 다른 리소스 이름으로 전파될 수 있으며 Google Cloud 프로젝트 외부의 Google 내부 시스템에 노출될 수 있습니다.

Cloud 콘솔

  1. Google Cloud 콘솔에서 전송 작업 만들기 페이지로 이동합니다.

    전송 작업 만들기로 이동

  2. Cloud Storage를 소스와 대상으로 선택합니다.

  3. 예약 모드이벤트 기반을 선택하고 다음 단계를 클릭합니다.

  4. 이 전송의 소스 버킷을 선택합니다.

  5. 이벤트 스트림 섹션에서 다음과 같이 구독 이름을 입력합니다.

    projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID

  6. 원하는 경우 필터를 정의한 후 다음 단계를 클릭합니다.

  7. 이 전송의 대상 버킷을 선택합니다.

  8. 원하는 경우 전송 시작 시간과 종료 시간을 입력합니다. 시간을 지정하지 않으면 전송이 즉시 시작되고 수동으로 중지할 때까지 실행됩니다.

  9. 전송 옵션을 지정합니다. 자세한 내용은 전송 만들기 페이지에서 확인할 수 있습니다.

  10. 만들기를 클릭합니다.

일단 생성되면 전송 작업이 시작되고 이벤트 리스너가 Pub/Sub 구독에서 알림을 기다립니다. 작업 세부정보 페이지에는 시간당 하나의 작업이 표시되며 각 작업에 전송되는 데이터에 대한 세부정보가 포함됩니다.

REST

REST API를 사용하여 이벤트 기반 전송을 만들려면 다음 JSON 객체를 transferJobs.create 엔드포인트로 전송합니다.

transfer_job {
  "description": "YOUR DESCRIPTION",
  "status": "ENABLED",
  "projectId": "PROJECT_ID",
  "transferSpec" {
    "gcsDataSource" {
      "bucketName": "GCS_SOURCE_NAME"
    },
    "gcsDataSink": {
        "bucketName": "GCS_SINK_NAME"
    }
  }
  "eventStream" {
    "name": "projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID",
    "eventStreamStartTime": "2022-12-02T01:00:00+00:00",
    "eventStreamExpirationTime": "2023-01-31T01:00:00+00:00"
  }
}

eventStreamStartTimeeventStreamExpirationTime은 선택사항입니다. 시작 시간을 생략하면 전송이 즉시 시작되고, 종료 시간을 생략하면 전송이 수동으로 중지될 때까지 계속됩니다.

클라이언트 라이브러리

Go

Storage Transfer Service용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Storage Transfer Service 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Storage Transfer Service Go API 참고 문서를 참조하세요.

Storage Transfer Service에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


func createEventDrivenGCSTransfer(w io.Writer, projectID string, gcsSourceBucket string, gcsSinkBucket string, pubSubId string) (*storagetransferpb.TransferJob, error) {
	// Your Google Cloud Project ID.
	// projectID := "my-project-id"

	// The name of the source GCS bucket.
	// gcsSourceBucket := "my-source-bucket"

	// The name of the GCS bucket to transfer objects to.
	// gcsSinkBucket := "my-sink-bucket"

	// The Pub/Sub topic to subscribe the event driven transfer to.
	// pubSubID := "projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID"

	ctx := context.Background()
	client, err := storagetransfer.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storagetransfer.NewClient: %w", err)
	}
	defer client.Close()

	req := &storagetransferpb.CreateTransferJobRequest{
		TransferJob: &storagetransferpb.TransferJob{
			ProjectId: projectID,
			TransferSpec: &storagetransferpb.TransferSpec{
				DataSource: &storagetransferpb.TransferSpec_GcsDataSource{
					GcsDataSource: &storagetransferpb.GcsData{BucketName: gcsSourceBucket}},
				DataSink: &storagetransferpb.TransferSpec_GcsDataSink{
					GcsDataSink: &storagetransferpb.GcsData{BucketName: gcsSinkBucket}},
			},
			EventStream: &storagetransferpb.EventStream{Name: pubSubId},
			Status:      storagetransferpb.TransferJob_ENABLED,
		},
	}
	resp, err := client.CreateTransferJob(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("failed to create transfer job: %w", err)
	}

	fmt.Fprintf(w, "Created an event driven transfer job from %v to %v subscribed to %v with name %v", gcsSourceBucket, gcsSinkBucket, pubSubId, resp.Name)
	return resp, nil
}

Java

Storage Transfer Service용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Storage Transfer Service 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Storage Transfer Service Java API 참고 문서를 참조하세요.

Storage Transfer Service에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


import com.google.storagetransfer.v1.proto.StorageTransferServiceClient;
import com.google.storagetransfer.v1.proto.TransferProto;
import com.google.storagetransfer.v1.proto.TransferTypes;

public class CreateEventDrivenGcsTransfer {
  public static void main(String[] args) throws Exception {
    // Your Google Cloud Project ID
    String projectId = "your-project-id";

    // The name of the GCS AWS bucket to transfer data from
    String gcsSourceBucket = "your-gcs-source-bucket";

    // The name of the GCS bucket to transfer data to
    String gcsSinkBucket = "your-gcs-sink-bucket";

    // The ARN of the PubSub queue to subscribe to
    String sqsQueueArn = "projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID";

    createEventDrivenGcsTransfer(projectId, gcsSourceBucket, gcsSinkBucket, sqsQueueArn);
  }

  public static void createEventDrivenGcsTransfer(
      String projectId, String gcsSourceBucket, String gcsSinkBucket, String pubSubId)
      throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources,
    // or use "try-with-close" statement to do this automatically.
    try (StorageTransferServiceClient storageTransfer = StorageTransferServiceClient.create()) {

      TransferTypes.TransferJob transferJob =
          TransferTypes.TransferJob.newBuilder()
              .setProjectId(projectId)
              .setTransferSpec(
                  TransferTypes.TransferSpec.newBuilder()
                      .setGcsDataSource(
                          TransferTypes.GcsData.newBuilder().setBucketName(gcsSourceBucket))
                      .setGcsDataSink(
                          TransferTypes.GcsData.newBuilder().setBucketName(gcsSinkBucket)))
              .setStatus(TransferTypes.TransferJob.Status.ENABLED)
              .setEventStream(TransferTypes.EventStream.newBuilder().setName(pubSubId).build())
              .build();

      TransferTypes.TransferJob response =
          storageTransfer.createTransferJob(
              TransferProto.CreateTransferJobRequest.newBuilder()
                  .setTransferJob(transferJob)
                  .build());

      System.out.println(
          "Created a transfer job between from "
              + gcsSourceBucket
              + " to "
              + gcsSinkBucket
              + " subscribed to "
              + pubSubId
              + " with name "
              + response.getName());
    }
  }
}

Node.js

Storage Transfer Service용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Storage Transfer Service 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Storage Transfer Service Node.js API 참고 문서를 참조하세요.

Storage Transfer Service에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


// Imports the Google Cloud client library
const {
  StorageTransferServiceClient,
} = require('@google-cloud/storage-transfer');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of the Google Cloud Platform Project that owns the job
// projectId = 'my-project-id'

// Google Cloud Storage source bucket name
// gcsSourceBucket = 'my-gcs-source-bucket'

// Google Cloud Storage destination bucket name
// gcsSinkBucket = 'my-gcs-destination-bucket'

// The subscription ID to a Pubsub queue to track
// pubsubId = 'projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID'

// Creates a client
const client = new StorageTransferServiceClient();

/**
 * Creates an event driven transfer that tracks a Pubsub subscription.
 */
async function createEventDrivenGcsTransfer() {
  const [transferJob] = await client.createTransferJob({
    transferJob: {
      projectId,
      status: 'ENABLED',
      transferSpec: {
        gcsDataSource: {
          bucketName: gcsSourceBucket,
        },
        gcsDataSink: {
          bucketName: gcsSinkBucket,
        },
      },
      eventStream: {
        name: pubsubId,
      },
    },
  });

  console.log(
    `Created an event driven transfer from '${gcsSourceBucket}' to '${gcsSinkBucket}' with name ${transferJob.name}`
  );
}

createEventDrivenGcsTransfer();

Python

Storage Transfer Service용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Storage Transfer Service 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Storage Transfer Service Python API 참고 문서를 참조하세요.

Storage Transfer Service에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


from google.cloud import storage_transfer


def create_event_driven_gcs_transfer(
    project_id: str,
    description: str,
    source_bucket: str,
    sink_bucket: str,
    pubsub_id: str,
):
    """Create an event driven transfer between two GCS buckets that tracks a PubSub subscription"""

    client = storage_transfer.StorageTransferServiceClient()

    # The ID of the Google Cloud Platform Project that owns the job
    # project_id = 'my-project-id'

    # A description of this job
    # description = 'Creates an event-driven transfer that tracks a pubsub subscription'

    # Google Cloud Storage source bucket name
    # source_bucket = 'my-gcs-source-bucket'

    # Google Cloud Storage destination bucket name
    # sink_bucket = 'my-gcs-destination-bucket'

    # The Pubsub Subscription ID to track
    # pubsub_id = 'projects/PROJECT_NAME/subscriptions/SUBSCRIPTION_ID'

    transfer_job_request = storage_transfer.CreateTransferJobRequest(
        {
            "transfer_job": {
                "project_id": project_id,
                "description": description,
                "status": storage_transfer.TransferJob.Status.ENABLED,
                "transfer_spec": {
                    "gcs_data_source": {
                        "bucket_name": source_bucket,
                    },
                    "gcs_data_sink": {
                        "bucket_name": sink_bucket,
                    },
                },
                "event_stream": {
                    "name": pubsub_id,
                },
            },
        }
    )

    result = client.create_transfer_job(transfer_job_request)
    print(f"Created transferJob: {result.name}")

이벤트 기반 전송 모니터링

이벤트 기반 전송을 만들면 Storage Transfer Service에서 전송 작업을 만듭니다. 시작 시간에 도달하면 전송 작업이 시작되고 이벤트 리스너가 Pub/Sub 큐의 알림을 기다립니다.

전송 작업은 in progress 상태로 약 24시간 동안 실행됩니다. 24시간이 지나면 작업이 완료되고 새 작업이 시작됩니다. 전송 작업의 종료 시간에 도달하거나 작업이 수동으로 중지될 때까지 24시간마다 새 작업이 생성됩니다.

작업이 완료되도록 예약되었을 때 파일 전송이 진행 중인 경우 파일이 완전히 전송될 때까지 현재 작업이 진행된 상태로 유지됩니다. 새 작업이 시작되고 이전 작업이 완료될 때까지 두 작업이 동시에 실행됩니다. 이 기간 동안 감지된 모든 이벤트는 새 작업에서 처리합니다.

현재 작업 및 완료된 작업을 보려면 다음 단계를 따르세요.

Google Cloud 콘솔

  1. Google Cloud 콘솔에서 Storage Transfer Service 페이지로 이동합니다.

    Storage Transfer Service로 이동

  2. 작업 목록에서 모두 탭 또는 클라우드 간을 선택합니다.

  3. 전송의 작업 ID를 클릭합니다. 예약 모드 열에는 모든 이벤트 기반 전송과 일괄 전송이 표시됩니다.

  4. 작업 탭을 선택합니다. 현재 작업에 관한 세부정보가 표시되고 완료된 작업은 실행 기록 표에 나열됩니다. 완료된 작업을 클릭하여 자세한 내용을 확인합니다.

gcloud

작업 진행 상태를 실시간으로 모니터링하려면 gcloud transfer jobs monitor를 사용합니다. 응답에는 현재 작업, 작업 시작 시간, 전송된 데이터 양, 건너뛴 바이트, 오류 수가 표시됩니다.

gcloud transfer jobs monitor JOB_NAME

현재 작업 이름을 가져오는 방법은 다음과 같습니다.

gcloud transfer jobs describe JOB_NAME --format="value(latestOperationName)"

현재 작업 및 완료된 작업을 나열하려면 다음 단계를 따르세요.

gcloud transfer operations list --job-names=JOB_NAME

작업에 대한 세부정보를 보려면 다음 단계를 따르세요.

gcloud transfer operations describe OPERATION_NAME