העברות מבוססות-אירועים מ-AWS S3

השירות Storage Transfer Service יכול להאזין להתראות לגבי אירועים ב-AWS כדי להעביר באופן אוטומטי נתונים שנוספו או עודכנו במיקום המקור, לקטגוריה של Cloud Storage. מידע נוסף על היתרונות של העברות מבוססות-אירועים.

העברות מבוססות-אירועים מאזינות להתראות אירועים של Amazon S3 שנשלחות ל-Amazon SQS, כדי לדעת מתי אובייקטים בקטגוריית המקור השתנו או נוספו. מחיקות של אובייקטים לא מזוהות. מחיקה של אובייקט במקור לא מוחקת את האובייקט המשויך בקטגוריית היעד.

העברות מבוססות-אירועים תמיד משתמשות בקטגוריה של Cloud Storage כיעד.

לפני שמתחילים

כדי לתת את ההרשאות הנדרשות בקטגוריה של Cloud Storage ביעד, פועלים לפי ההוראות הבאות:

יצירת תור SQS

  1. במסוף AWS, נכנסים לדף Simple Queue Service.

  2. לוחצים על Create queue.

  3. מזינים שם לתור הזה.

  4. בקטע Access policy, בוחרים באפשרות Advanced. מוצג אובייקט 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. הם ייחודיים לכל פרויקט.

  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.

  6. מעתיקים את קטע הקוד המלא בפורמט JSON ומחליפים איתו את ה-JSON שמוצג בקטע Access policy.

  7. לוחצים על Create queue.

בסיום, שימו לב לשם המשאב של אמזון (ARN) של התור.

הפעלת התראות בקטגוריית S3

  1. נכנסים לדף S3 במסוף AWS.

  2. ברשימה Buckets, בוחרים את קטגוריית המקור.

  3. לוחצים על הכרטיסייה מאפיינים.

  4. בקטע התראות לגבי אירועים, לוחצים על יצירת התראה לגבי אירוע.

  5. צריך לתת שם לאירוע.

  6. בקטע Event types, בוחרים באפשרות All object create events.

  7. בשדה Destination בוחרים באפשרות SQS queue ובוחרים את התור שיצרתם להעברה הזו.

  8. לוחצים על שמירת השינויים.

הגדרת ההרשאות

כדי ליצור מזהה מפתח גישה ומפתח סודי, או תפקיד של זהות מאוחדת, פועלים לפי ההוראות במאמר הגדרת גישה למקור: Amazon S3.

במהלך ביצוע ההוראות, השתמשו בקובץ ה-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"
          ]
      }
  ]
}

אחרי שיוצרים את המפתח, חשוב לשים לב לפרטים הבאים:

  • לגבי משתמש, שימו לב למזהה של מפתח הגישה ולמפתח הסודי.
  • לתפקיד זהות מאוחדת, שימו לב לשם המשאב של אמזון (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"
          ]
      }
  ]
}

אחרי שיוצרים את המפתח, חשוב לשים לב לפרטים הבאים:

  • לגבי משתמש, שימו לב למזהה של מפתח הגישה ולמפתח הסודי.
  • לתפקיד של זהות מאוחדת, שימו לב לשם המשאב של Amazon‏ (ARN), שהוא בפורמט הבא: arn:aws-us-gov:iam::AWS_ACCOUNT:role/AWS_ROLE_NAME

יצירת משימת העברה

אפשר להשתמש במסוף Google Cloud , ב-Google Cloud CLI או ב-API בארכיטקטורת REST כדי ליצור משימת העברה מבוססת-אירועים.

מסוף Cloud

  1. נכנסים לדף Create transfer job במסוף Google Cloud .

    נכנסים לדף Create transfer job.

  2. בוחרים באפשרות Amazon S3 בתור סוג המקור, ובאפשרות Cloud Storage בתור היעד.

  3. בקטע Scheduling mode, בוחרים באפשרות Event-driven ולוחצים על Next step.

  4. מזינים את השם של קטגוריית S3. שם הקטגוריה הוא השם שמופיע ב-AWS Management Console. לדוגמה, my-aws-bucket.

  5. בוחרים את שיטת האימות ומזינים את המידע הנדרש, שיצרתם וציינתם בקטע הקודם.

  6. מזינים את ה-ARN של התור ב-Amazon SQS שיצרתם קודם. הוא משתמש באחד מהפורמטים הבאים:

    • לאזורים רגילים ב-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 ואת הנתיב (אופציונלי).

  9. אם רוצים, מזינים שעת התחלה ושעת סיום להעברה. אם לא תציינו שעה, ההעברה תתחיל מיד ותפעל עד שתעצרו אותה באופן ידני.

  10. מציינים את אפשרויות ההעברה. מידע נוסף זמין בדף יצירת העברות.

  11. לוחצים על יצירה.

אחרי שיוצרים את משימת ההעברה, היא מתחילה לפעול ורכיב event listener ממתין להתראות בתור של 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

מחליפים את ה-placeholders בערכים בפועל:

  • ‫S3_BUCKET_NAME: השם של קטגוריית המקור ב-Amazon S3.
  • ‫GCS_BUCKET_NAME: קטגוריה של Cloud Storage ליעד שלך.
  • ‫SOURCE_CREDS_FILE: הנתיב היחסי לקובץ מקומי במחשב שמכיל את פרטי הכניסה שלכם ל-AWS. בהתאם לשיטת האימות, הקובץ הזה צריך להכיל את המזהה של מפתח הגישה ואת המפתח הסודי, או את ה-ARN של התפקיד בזהות המאוחדת. מידע נוסף זמין במאמר הגדרת גישה למקור: Amazon S3.
  • ‫AWS_QUEUE_ARN: ה-ARN של התור ב-Amazon SQS. לדוגמה, arn:aws:sqs:us-east-1:123456789012:my-queue לאזורים רגילים של AWS או arn:aws-us-gov:sqs:us-gov-west-1:123456789012:my-gov-queue לאזורים של AWS GovCloud.
  • ‫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

כדי ליצור העברה מבוססת-אירועים באמצעות ה-API בארכיטקטורת REST, שולחים את אובייקט ה-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"
}
}

ה-placeholders בקובץ ה-JSON שלמעלה משתמשים בערכים הבאים:

  • ‫DESCRIPTION הוא תיאור של משימת ההעברה.
  • ‫PROJECT_ID הוא מזהה הפרויקט ב- Google Cloud שבו נוצרה משימת ההעברה.
  • ‫S3_BUCKET_NAME הוא השם של קטגוריית המקור ב-Amazon S3.
  • ‫AWS_ROLE_ARN הוא ה-ARN של תפקיד הזהות המאוחדת שיצרתם. לדוגמה, arn:aws:iam::1234567891011:role/aws-role-name לאזורים רגילים של AWS או arn:aws-us-gov:iam::1234567891011:role/aws-role-name לאזורים של AWS GovCloud.
  • ‫GCS_BUCKET_NAME הוא השם של קטגוריית היעד ב-Cloud Storage.
  • ‫AWS_QUEUE_ARN הוא ה-ARN של תור ה-SQS. לדוגמה, arn:aws:sqs:us-east-1:1234567891011:s3-notification-queue לאזורים רגילים ב-AWS או arn:aws-us-gov:sqs:us-gov-east-1:1234567890:event-queue לאזורים ב-AWS GovCloud.

הפרמטרים eventStreamStartTime ו-eventStreamExpirationTime הם אופציונליים. אם לא מציינים שעת התחלה, ההעברה מתחילה מיד. אם לא מציינים שעת סיום, ההעברה נמשכת עד שעוצרים אותה ידנית.

ספריות לקוח

Go

במאמר ספריות הלקוח של Storage Transfer Service מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Storage Transfer Service. למידע נוסף, קראו את מאמרי העזרה של Storage Transfer Service Go API.

כדי לבצע אימות בשירות Storage Transfer Service, עליכם להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.


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 Transfer Service מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Storage Transfer Service. למידע נוסף, קראו את מאמרי העזרה של Storage Transfer Service Java API.

כדי לבצע אימות בשירות Storage Transfer Service, עליכם להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.


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 Transfer Service מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Storage Transfer Service. למידע נוסף, קראו את מאמרי העזרה של Storage Transfer Service Node.js API.

כדי לבצע אימות בשירות Storage Transfer Service, עליכם להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.


// 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 Transfer Service מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Storage Transfer Service. למידע נוסף, קראו את מאמרי העזרה של Storage Transfer Service Python API.

כדי לבצע אימות בשירות Storage Transfer Service, עליכם להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.


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}")