Chuyển tới nội dung chính

S3 Event Notifications

1. Tổng quan​

S3 Event Notifications tự động gửi thông báo khi object trong bucket được tạo, bị xóa hoặc chịu các thao tác được hỗ trợ khác. Vietnix Cloud S3 Storage triển khai theo đúng chuẩn API notification của AWS S3, vì vậy các ứng dụng đã tích hợp S3 notification trên AWS có thể tái sử dụng nguyên vẹn.

Khi có sự kiện, hệ thống gửi HTTP POST với payload JSON tới endpoint đã đăng ký cho topic — thường trong khoảng một giây. Hệ thống cũng hỗ trợ đích Kafka và AMQP; vui lòng liên hệ Vietnix để được tư vấn.

2. Cách hoạt động​

Quá trình thiết lập thông báo bao gồm phần việc của Khách hàng và Vietnix:

Công việcĐơn vị thực hiện
Chuẩn bị endpoint nhận JSON qua HTTP/HTTPSKhách hàng
Tạo topic thông báo trên cụm lưu trữVietnix
Gắn topic vào bucket qua S3 APIKhách hàng
  • Topic do Vietnix tạo. Không thể tự tạo topic qua S3 API hay portal; vui lòng gửi yêu cầu qua kênh hỗ trợ của Vietnix để nhận topic ARN.
  • Topic ARN có dạng arn:aws:sns::<s3_user_id>:<topic_name>.
  • Sau khi nhận ARN, thực hiện gắn ARN vào bucket bằng API chuẩn của S3 (put-bucket-notification-configuration) với bất kỳ công cụ tương thích S3 nào, chẳng hạn AWS CLI hoặc SDK.

3. Các bước thiết lập​

3.1. Bước 1 — Chuẩn bị endpoint nhận thông báo​

Endpoint cần đáp ứng các yêu cầu sau:

  • Có thể truy cập từ internet — dịch vụ thông báo sẽ chủ động kết nối tới endpoint.
  • Tiếp nhận request POST với body JSON (Content-Type: application/json).
  • Phản hồi mã 2xx kịp thời.

Lưu ý:

  • Xác thực nguồn gửi: allowlist IP nguồn 45.115.16.7 và/hoặc kiểm tra token opaqueData trong mỗi payload (xem Bước 2).
  • Chuyển đổi payload khi cần: body thông báo theo cấu trúc event message của AWS S3 (xem mục 5). Đối với dịch vụ yêu cầu định dạng riêng (ví dụ nền tảng chat như Discord, Slack, Teams), cần bổ sung một relay trung gian để chuyển đổi JSON sự kiện S3 sang định dạng tương ứng.

3.2. Bước 2 — Yêu cầu Vietnix tạo topic​

Để yêu cầu tạo topic, vui lòng liên hệ hỗ trợ Vietnix và cung cấp:

  • Tên bucket
  • Endpoint nhận thông báo (URL HTTPS, Kafka hoặc AMQP)
  • Các loại sự kiện cần nhận (xem mục 4)
  • (Tùy chọn) chuỗi bí mật dùng để xác thực thông báo

Vietnix tiến hành tạo topic và gửi lại:

  • TopicArn — ví dụ arn:aws:sns::1234abcd:myevents
  • Opaque token — chuỗi bí mật đã cung cấp; xuất hiện trong mọi thông báo ở trường opaqueData.
ghi chú
  • Tên topic chỉ dùng chữ và số.
  • Không đặt chuỗi bí mật trong query string của URL endpoint — hệ thống thông báo tách query thành các tham số riêng. Thay vào đó, cung cấp chuỗi bí mật dưới dạng opaque data và kiểm tra giá trị này trong payload.

3.3. Bước 3 — Gắn topic vào bucket​

Gắn topic ARN vào bucket bằng put-bucket-notification-configuration:

aws s3api put-bucket-notification-configuration \
  --bucket your-bucket-name \
  --endpoint-url https://s3.vn-hcm-1.vietnix.cloud \
  --notification-configuration '{"TopicConfigurations":[{"TopicArn":"arn:aws:sns::<s3_user_id>:<topic_name>","Events":["s3:ObjectCreated:*","s3:ObjectRemoved:*"]}]}'

3.4. Bước 4 — Kiểm tra cấu hình​

aws s3api get-bucket-notification-configuration \
  --bucket your-bucket-name \
  --endpoint-url https://s3.vn-hcm-1.vietnix.cloud

3.5. Bước 5 — Kiểm thử thông báo​

Tải lên một object nhỏ (ví dụ bằng aws s3 cp) và xác nhận endpoint nhận được request POST. Thời gian gửi thường khoảng 1 giây; request đầu tiên ngay sau khi thay đổi cấu hình có thể mất vài giây.

3.6. Bước 6 — Tắt thông báo​

Gửi cấu hình rỗng:

aws s3api put-bucket-notification-configuration \
  --bucket your-bucket-name \
  --notification-configuration '{}' \
  --endpoint-url https://s3.vn-hcm-1.vietnix.cloud

4. Các loại sự kiện được hỗ trợ​

Sự kiệnKích hoạt khi
s3:ObjectCreated:*Object được tạo: Put, Post, Copy, CompleteMultipartUpload
s3:ObjectRemoved:*Object bị xóa: Delete, DeleteMarkerCreated
s3:ObjectLifecycle:Expiration:*Lifecycle rule khiến object hết hạn
s3:ObjectAcl:PutACL của object thay đổi
Sự kiện replicationCác sự kiện liên quan đến replication của bucket

5. Payload của thông báo​

{
  "Records": [{
    "eventId": "gpDqi41qbcwFMJwDPbRyDyHCs5PpX35Q",
    "opaqueData": "",
    "eventVersion": "2.1",
    "eventSource": "aws:s3",
    "eventTime": "2026-10-06T08:25:25Z",
    "awsRegion": "vn-hcm-1",
    "eventName": "ObjectCreated:Put",
    "userIdentity": { "principalId": "<s3_user_id>" },
    "requestParameters": { "sourceIPAddress": "10.64.0.252" },
    "responseElements": { "x-amz-request-id": "800000000000003100041e392832974d", "x-amz-id-2": "" },
    "s3": {
      "s3SchemaVersion": "1.0",
      "configurationId": "54661ba9-5527-4c67-af5c-d05351f472cd",
      "bucket": { "name": "your-bucket-name", "ownerIdentity": { "principalId": "<s3_user_id>" }, "arn": "arn:aws:s3:::your-bucket-name" },
      "object": { "key": "path/to/object.txt", "size": 40, "eTag": "143771125efae0940efcaf09db235578", "versionId": "null", "sequencer": "00065D27BD8F017D" }
    }
  }]
}

Trường opaqueData chứa token được đặt khi tạo topic (rỗng nếu không cấu hình token).

Request được gửi kèm các header sau:

  • User-Agent: ostor-sns-service/1.0
  • Content-Type: application/json

6. Lưu ý quan trọng và giới hạn​

  • Thông báo không được ký (sign). Cần xác thực bằng cách allowlist IP nguồn 45.115.16.7 và/hoặc kiểm tra giá trị opaqueData trong payload.
  • Webhook cần trả về mã 2xx kịp thời. Nếu endpoint trả lỗi (ví dụ 500), sự kiện không được gửi lại và bị mất. Các sự kiện chưa kịp gửi cũng bị mất nếu dịch vụ thông báo khởi động lại. Trường hợp không được phép mất sự kiện, cần đối chiếu định kỳ bằng ListObjects.
  • sourceIPAddress trong payload là IP nội bộ của gateway, không phải IP của client.
  • awsRegion là vn-hcm-1 (region của cụm S3).
  • Xóa một object không tồn tại không sinh sự kiện.
  • Webhook chậm hoặc không phản hồi không làm chậm quá trình upload. Khi kiểm thử với endpoint treo 30 giây, thời gian upload vẫn khoảng 0,4 giây.
  • Request đầu tiên ngay sau khi thay đổi cấu hình thông báo có thể chậm vài giây; các request sau được gửi bình thường.

7. Khuyến nghị​

  • Xác thực mọi thông báo bằng token opaqueData trước khi xử lý.
  • Phản hồi 2xx ngay lập tức và xử lý sự kiện bất đồng bộ để tránh timeout khi gửi.
  • Dự phòng khả năng mất sự kiện: nếu sự kiện quan trọng với nghiệp vụ, cần đối chiếu định kỳ (ví dụ ListObjects) để phát hiện các object bị sót thông báo.
  • Giới hạn webhook chỉ cho IP nguồn 45.115.16.7 của Vietnix.
  • Kiểm thử trên bucket staging trước khi áp dụng cho dữ liệu production.

8. Tìm hiểu thêm​

  • Quản lý Bucket: Tìm hiểu cách quản lý bucket S3 trên Vietnix Cloud.
  • Object Lock: Bảo vệ object bằng cơ chế lưu giữ WORM.
  • AWS CLI: Kết nối AWS CLI tới Vietnix Cloud S3 Storage.