從 AWS S3 進行事件驅動轉移

Storage 移轉服務可監聽 AWS 中的事件通知,自動將來源位置中新增或更新的資料,移轉至 Cloud Storage bucket。進一步瞭解事件導向移轉作業的優點。

事件導向移轉作業會監聽傳送至 Amazon SQS 的 Amazon S3 事件通知,瞭解來源 bucket 中的物件何時遭到修改或新增。系統不會偵測物件刪除作業;刪除來源物件時,不會刪除目的地 bucket 中的相關聯物件。

事件導向移轉作業一律會使用 Cloud Storage bucket 做為目的地。

事前準備

請按照操作說明,授予目的地 Cloud Storage bucket 的必要權限:

建立 SQS 佇列

  1. 前往 AWS 控制台的「Simple Queue Service」頁面。

  2. 按一下「Create queue」(建立佇列)。

  3. 輸入這個佇列的名稱。

  4. 在「存取權政策」部分,選取「進階」。系統會顯示 JSON 物件。

    標準 AWS 區域

    {
      "Version": "2008-10-17",
      "Id": "\_\_default\_policy\_ID",
      "Statement": [
        {
          "Sid": "\_\_owner\_statement",
          "Effect": "Allow",
          "Principal": {
            "AWS": "01234567890"
          },
          "Action": [
            "SQS:*"
          ],
          "Resource": "arn:aws:sqs:us-west-2:01234567890:test"
        }
      ]
    }

    AWS GovCloud 區域

    {
      "Version": "2008-10-17",
      "Id": "\_\_default\_policy\_ID",
      "Statement": [
        {
          "Sid": "\_\_owner\_statement",
          "Effect": "Allow",
          "Principal": {
            "AWS": "01234567890"
          },
          "Action": [
            "SQS:*"
          ],
          "Resource": "arn:aws-us-gov:sqs:us-gov-west-1:01234567890:test"
        }
      ]
    }

    複製 AWS 和 Resource 的值。每個專案的 ID 都不相同。

  5. 將上一步中 AWS 和 Resource 的特定值貼到下列 JSON 程式碼片段中:

    標準 AWS 區域

    {
    "Version": "2012-10-17",
    "Id": "example-ID",
    "Statement": [
      {
        "Sid": "example-statement-ID",
        "Effect": "Allow",
        "Principal": {
          "Service": "s3.amazonaws.com"
        },
        "Action": "SQS:SendMessage",
        "Resource": "RESOURCE",
        "Condition": {
          "StringEquals": {
            "aws:SourceAccount": "AWS"
          },
          "ArnLike": {
            "aws:SourceArn": "arn:aws:s3:::S3_BUCKET_NAME"
          }
        }
      }
    ]
    }

    AWS GovCloud 區域

    {
    "Version": "2012-10-17",
    "Id": "example-ID",
    "Statement": [
      {
        "Sid": "example-statement-ID",
        "Effect": "Allow",
        "Principal": {
          "Service": "s3.amazonaws.com"
        },
        "Action": "SQS:SendMessage",
        "Resource": "RESOURCE",
        "Condition": {
          "StringEquals": {
            "aws:SourceAccount": "AWS"
          },
          "ArnLike": {
            "aws:SourceArn": "arn:aws-us-gov:s3:::S3_BUCKET_NAME"
          }
        }
      }
    ]
    }

    將 S3_BUCKET_NAME 替換為 S3 來源 bucket 的名稱。

  6. 複製這段完整的 JSON 程式碼片段,並用來取代「Access policy」(存取權政策) 區段中顯示的 JSON。

  7. 按一下「Create queue」(建立佇列)。

完成後,請記下佇列的 Amazon Resource Name (ARN)。

啟用 S3 值區的通知功能

  1. 前往 AWS 控制台的「S3」S3頁面。

  2. 在「Buckets」(值區) 清單中,選取來源值區。

  3. 選取「屬性」分頁標籤。

  4. 在「Event notifications」(事件通知) 專區,按一下「Create event notification」(建立事件通知)。

  5. 指定這個事件的名稱。

  6. 在「Event types」(事件類型) 部分,選取「All object create events」(所有物件建立事件)。

  7. 在「Destination」(目的地) 部分,選取「SQS queue」(SQS 佇列),然後選取您為這項移轉作業建立的佇列。

  8. 按一下 [儲存變更]。

設定權限

請按照「設定來源存取權:Amazon S3」中的操作說明,建立存取金鑰 ID 和私密金鑰,或聯合身分角色。

按照操作說明操作時,請在系統指示您指定自訂角色或自訂信任政策時,使用下列 JSON:

標準 AWS 區域

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "sqs:DeleteMessage",
              "sqs:ChangeMessageVisibility",
              "sqs:ReceiveMessage",
              "s3:GetObject",
              "s3:ListBucket"
          ],
          "Resource": [
              "arn:aws:s3:::S3_BUCKET_NAME",
              "arn:aws:s3:::S3_BUCKET_NAME/*",
              "AWS_QUEUE_ARN"
          ]
      }
  ]
}

建立後,請記下下列資訊:

  • 記下使用者的存取金鑰 ID 和密鑰。
  • 如果是聯合身分角色,請記下 Amazon Resource Name (ARN),格式如下: arn:aws:iam::AWS_ACCOUNT:role/AWS_ROLE_NAME

AWS GovCloud 區域

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "sqs:DeleteMessage",
              "sqs:ChangeMessageVisibility",
              "sqs:ReceiveMessage",
              "s3:GetObject",
              "s3:ListBucket"
          ],
          "Resource": [
              "arn:aws-us-gov:s3:::S3_BUCKET_NAME",
              "arn:aws-us-gov:s3:::S3_BUCKET_NAME/*",
              "AWS_QUEUE_ARN"
          ]
      }
  ]
}

建立後,請記下下列資訊:

  • 記下使用者的存取金鑰 ID 和密鑰。
  • 如果是聯合身分角色,請記下 Amazon Resource Name (ARN),格式如下:arn:aws-us-gov:iam::AWS_ACCOUNT:role/AWS_ROLE_NAME

建立移轉工作

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API 建立事件式移轉工作。

Cloud 控制台

  1. 前往 Google Cloud 控制台的「Create transfer job」(建立移轉工作) 頁面。

    前往「Create transfer job」(建立移轉工作)

  2. 選取「Amazon S3」做為來源類型,並選取「Cloud Storage」做為目的地。

  3. 在「Scheduling mode」(排程模式) 中選取「Event-driven」(事件導向),然後點選「Next step」(下一步)。

  4. 輸入 S3 bucket 名稱。bucket 名稱是 AWS 管理控制台中顯示的名稱。例如:my-aws-bucket。

  5. 選取驗證方式,並輸入上一節建立及記下的必要資訊。

  6. 輸入先前建立的 Amazon SQS 佇列 ARN。格式如下:

    • 標準 AWS 區域:arn:aws:sqs:AWS_REGION:AWS_ACCOUNT:AWS_QUEUE_NAME
    • AWS GovCloud 區域:arn:aws-us-gov:sqs:AWS_REGION:AWS_ACCOUNT:AWS_QUEUE_NAME
  7. 視需要定義篩選器,然後點選「下一步」。

  8. 選取目的地 Cloud Storage bucket,並視需要選取路徑。

  9. (選用) 輸入轉移作業的開始和結束時間。如未指定時間,移轉作業會立即開始,並持續執行,直到手動停止為止。

  10. 指定任何轉移選項。詳情請參閱「建立移轉作業」頁面。

  11. 點選「建立」。

建立後,轉移工作會開始執行,事件監聽器會等待 SQS 佇列的通知。工作詳細資料頁面會顯示每小時的一項作業,並包含每項工作轉移的資料詳細資料。

gcloud

如要使用 Google Cloud CLI 建立事件導向移轉工作,請使用 gcloud transfer jobs create 指令和 --event-stream-name 旗標:

gcloud transfer jobs create \
  s3://S3_BUCKET_NAME \
  gs://GCS_BUCKET_NAME \
  --source-creds-file=SOURCE_CREDS_FILE \
  --event-stream-name=AWS_QUEUE_ARN \
  --event-stream-starts=EVENT_STREAM_STARTS \
  --event-stream-expires=EVENT_STREAM_EXPIRES

將預留位置替換為實際值:

  • S3_BUCKET_NAME:Amazon S3 來源 bucket 的名稱。
  • GCS_BUCKET_NAME:目的地 Cloud Storage bucket。
  • SOURCE_CREDS_FILE:本機檔案的相對路徑,該檔案包含 AWS 憑證。視驗證方式而定,這個檔案應包含存取金鑰 ID 和密鑰,或聯合身分角色 ARN。詳情請參閱「設定來源存取權:Amazon S3」。
  • AWS_QUEUE_ARN:Amazon SQS 佇列的 ARN。例如,標準 AWS 區域為 arn:aws:sqs:us-east-1:123456789012:my-queue,AWS GovCloud 區域則為 arn:aws-us-gov:sqs:us-gov-west-1:123456789012:my-gov-queue。
  • EVENT_STREAM_STARTS:開始監聽事件的時間,使用 %Y-%m-%dT%H:%M:%S%z 日期時間格式 (例如 2020-04-12T06:42:12+04:00)。如未設定,工作會在成功提交建立工作指令後,開始執行並監聽事件。
  • EVENT_STREAM_EXPIRES:停止監聽事件的時間。如未設定,工作會持續執行,直到手動停止為止。

如需支援欄位的完整清單,請參閱 gcloud transfer jobs create 參考資料。

REST

如要使用 REST API 建立事件導向移轉作業,請將下列 JSON 物件傳送至 transferJobs.create 端點:

{
"description": "DESCRIPTION",
"status": "ENABLED",
"projectId": "PROJECT_ID",
"transferSpec": {
  "awsS3DataSource": {
    "bucketName": "S3_BUCKET_NAME",
    "roleArn": "AWS_ROLE_ARN"
  },
  "gcsDataSink": {
    "bucketName": "GCS_BUCKET_NAME"
  }
},
"eventStream": {
  "name": "AWS_QUEUE_ARN",
  "eventStreamStartTime": "2022-12-02T01:00:00+00:00",
  "eventStreamExpirationTime": "2023-01-31T01:00:00+00:00"
}
}

上述 JSON 中的預留位置會使用下列值:

  • DESCRIPTION 是轉移工作的說明。
  • PROJECT_ID 是建立移轉工作的 Google Cloud 專案 ID。
  • S3_BUCKET_NAME 是 Amazon S3 來源 bucket 的名稱。
  • AWS_ROLE_ARN 是您建立的聯合身分角色 ARN。例如,標準 AWS 區域為 arn:aws:iam::1234567891011:role/aws-role-name,AWS GovCloud 區域則為 arn:aws-us-gov:iam::1234567891011:role/aws-role-name。
  • GCS_BUCKET_NAME 是 Cloud Storage 目的地 bucket 的名稱。
  • AWS_QUEUE_ARN 是 SQS 佇列的 ARN。例如,標準 AWS 區域為 arn:aws:sqs:us-east-1:1234567891011:s3-notification-queue,AWS GovCloud 區域則為 arn:aws-us-gov:sqs:us-gov-east-1:1234567890:event-queue。

eventStreamStartTime 和 eventStreamExpirationTime 為選用項目。如果省略開始時間,移轉作業會立即開始;如果省略結束時間,移轉作業會持續進行,直到手動停止為止。

用戶端程式庫

Go

如要瞭解如何安裝及使用 Storage 移轉服務的用戶端程式庫,請參閱「Storage 移轉服務用戶端程式庫」。詳情請參閱 Storage 移轉服務 Go API 參考文件。

如要向 Storage 移轉服務進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


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

	// The name of the source AWS S3 bucket.
	// s3SourceBucket := "my-source-bucket"

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

	// The Amazon Resource Name (ARN) of the AWS SNS queue to subscribe the event driven transfer to.
	// sqsQueueARN := "arn:aws:sqs:us-east-1:1234567891011:s3-notification-queue"

	// The AWS access key credential, should be accessed via environment variable for security
	awsAccessKeyID := os.Getenv("AWS_ACCESS_KEY_ID")

	// The AWS secret key credential, should be accessed via environment variable for security
	awsSecretKey := os.Getenv("AWS_SECRET_ACCESS_KEY")

	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_AwsS3DataSource{
					AwsS3DataSource: &storagetransferpb.AwsS3Data{
						BucketName: s3SourceBucket,
						AwsAccessKey: &storagetransferpb.AwsAccessKey{
							AccessKeyId:     awsAccessKeyID,
							SecretAccessKey: awsSecretKey,
						}},
				},
				DataSink: &storagetransferpb.TransferSpec_GcsDataSink{
					GcsDataSink: &storagetransferpb.GcsData{BucketName: gcsSinkBucket}},
			},
			EventStream: &storagetransferpb.EventStream{Name: sqsQueueARN},
			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", s3SourceBucket, gcsSinkBucket, sqsQueueARN, resp.Name)
	return resp, nil
}

Java

如要瞭解如何安裝及使用 Storage 移轉服務的用戶端程式庫,請參閱「Storage 移轉服務用戶端程式庫」。詳情請參閱 Storage 移轉服務 Java API 參考文件。

如要向 Storage 移轉服務進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


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

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

    // The name of the source AWS bucket to transfer data from
    String s3SourceBucket = "yourS3SourceBucket";

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

    // The ARN of the SQS queue to subscribe to
    String sqsQueueArn = "arn:aws:sqs:us-east-1:1234567891011:s3-notification-queue";

    createEventDrivenAwsTransfer(projectId, s3SourceBucket, gcsSinkBucket, sqsQueueArn);
  }

  public static void createEventDrivenAwsTransfer(
      String projectId, String s3SourceBucket, String gcsSinkBucket, String sqsQueueArn)
      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()) {

      // The ID used to access your AWS account. Should be accessed via environment variable.
      String awsAccessKeyId = System.getenv("AWS_ACCESS_KEY_ID");

      // The Secret Key used to access your AWS account. Should be accessed via environment
      // variable.
      String awsSecretAccessKey = System.getenv("AWS_SECRET_ACCESS_KEY");

      TransferTypes.TransferJob transferJob =
          TransferTypes.TransferJob.newBuilder()
              .setProjectId(projectId)
              .setTransferSpec(
                  TransferTypes.TransferSpec.newBuilder()
                      .setAwsS3DataSource(
                          TransferTypes.AwsS3Data.newBuilder()
                              .setBucketName(s3SourceBucket)
                              .setAwsAccessKey(
                                  TransferTypes.AwsAccessKey.newBuilder()
                                      .setAccessKeyId(awsAccessKeyId)
                                      .setSecretAccessKey(awsSecretAccessKey))
                              .build())
                      .setGcsDataSink(
                          TransferTypes.GcsData.newBuilder().setBucketName(gcsSinkBucket)))
              .setStatus(TransferTypes.TransferJob.Status.ENABLED)
              .setEventStream(TransferTypes.EventStream.newBuilder().setName(sqsQueueArn).build())
              .build();

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

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

Node.js

如要瞭解如何安裝及使用 Storage 移轉服務的用戶端程式庫,請參閱「Storage 移轉服務用戶端程式庫」。詳情請參閱 Storage 移轉服務 Node.js API 參考文件。

如要向 Storage 移轉服務進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


// 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'

// AWS S3 source bucket name
// s3SourceBucket = 'my-s3-source-bucket'

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

// The ARN of the SQS queue to subscribe to
// sqsQueueArn = 'arn:aws:sqs:us-east-1:1234567891011:s3-notification-queue'

// AWS Access Key ID. Should be accessed via environment variable for security.
// awsAccessKeyId = 'AKIA...'

// AWS Secret Access Key. Should be accessed via environment variable for security.
// awsSecretAccessKey = 'HEAoMK2.../...ku8'

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

/**
 * Creates an event driven transfer that tracks an SQS queue.
 */
async function createEventDrivenAwsTransfer() {
  const [transferJob] = await client.createTransferJob({
    transferJob: {
      projectId,
      status: 'ENABLED',
      transferSpec: {
        awsS3DataSource: {
          bucketName: s3SourceBucket,
          awsAccessKey: {
            accessKeyId: awsAccessKeyId,
            secretAccessKey: awsSecretAccessKey,
          },
        },
        gcsDataSink: {
          bucketName: gcsSinkBucket,
        },
      },
      eventStream: {
        name: sqsQueueArn,
      },
    },
  });

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

createEventDrivenAwsTransfer();

Python

如要瞭解如何安裝及使用 Storage 移轉服務的用戶端程式庫,請參閱「Storage 移轉服務用戶端程式庫」。詳情請參閱 Storage 移轉服務 Python API 參考文件。

如要向 Storage 移轉服務進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from google.cloud import storage_transfer


def create_event_driven_aws_transfer(
    project_id: str,
    description: str,
    source_s3_bucket: str,
    sink_gcs_bucket: str,
    sqs_queue_arn: str,
    aws_access_key_id: str,
    aws_secret_access_key: str,
):
    """Create an event driven transfer between two GCS buckets that tracks an AWS SQS queue"""

    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 an SQS queue'

    # AWS S3 source bucket name
    # source_s3_bucket = 'my-s3-source-bucket'

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

    # The ARN of the SQS queue to subscribe to
    # pubsub_id = 'arn:aws:sqs:us-east-1:1234567891011:s3-notification-queue'

    # AWS Access Key ID. Should be accessed via environment variable for security purposes.
    # aws_access_key_id = 'AKIA...'

    # AWS Secret Access Key. Should be accessed via environment variable for security purposes.
    # aws_secret_access_key = 'HEAoMK2.../...ku8'

    transfer_job_request = storage_transfer.CreateTransferJobRequest(
        {
            "transfer_job": {
                "project_id": project_id,
                "description": description,
                "status": storage_transfer.TransferJob.Status.ENABLED,
                "transfer_spec": {
                    "aws_s3_data_source": {
                        "bucket_name": source_s3_bucket,
                        "aws_access_key": {
                            "access_key_id": aws_access_key_id,
                            "secret_access_key": aws_secret_access_key,
                        },
                    },
                    "gcs_data_sink": {
                        "bucket_name": sink_gcs_bucket,
                    },
                },
                "event_stream": {
                    "name": sqs_queue_arn,
                },
            },
        }
    )

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