Use event notifications to process real-time object changes

Prerequisites

You have activated Simple Message Queue (SMQ). You can activate SMQ on the SMQ product page.

Usage notes

• When an OSS operation triggers an event notification rule, OSS calls SMQ to send a notification. This call may fail. Check the Base64-encoded x-oss-event-status response header to verify delivery. A decoded value of {"Result": "Ok"} indicates success.

• Event notifications incur SMQ fees. Billing.

• Event notifications are available in specific regions.

• You can configure up to 10 event notification rules per region. To increase this limit, contact technical support.

• TS and M3U8 objects generated from Real-Time Messaging Protocol (RTMP) streams do not trigger event notification rules. LiveChannel-related operations.

How it works

When an operation on your bucket triggers an event notification rule, SMQ sends a notification to the HTTP endpoint or queue you specified.

Event types

Notification message

{
    "events": [
      {
        "eventName": "",  // The event notification type.
        "eventSource": "", // The source of the event notification. This value is fixed as "acs:oss".
        "eventTime": "", // The time when the event occurred, in ISO 8601 format.
        "eventVersion": "", // The version of the event notification. The current version is "1.0".
        "oss": {
            "bucket": {
                "arn": "", // The Alibaba Cloud Resource Name (ARN) of the bucket, in the format of "acs:oss:region:uid:bucketname".
                "name": "", // The name of the destination bucket.
                "ownerIdentity": "" // The owner of the bucket.
            }, 
            "object": {
                "deltaSize": "", // The change in the object size. For example, when a new object is created, this value is the object size. When an object is overwritten, this value is the difference in size between the new object and the old object, which can be negative.
                "eTag": "", // The ETag of the object.
                "key": "", // The object key.
                "position": "", // The starting position for an append operation. This parameter applies only to the ObjectCreated:AppendObject event. The first AppendObject request for an object starts at byte 0.
                "readFrom": "", // The starting position for a read operation. This parameter applies only to the ObjectDownloaded:GetObject event. For a non-range request, this value is 0. For a range request, this value is the starting byte of the request.
                "readTo": "", // The ending position for a read operation. This parameter applies only to the ObjectDownloaded:GetObject event. For a non-range request, this value is the object size. For a range request, this value is the ending byte of the range request plus 1.
                "size": "" // The size of the object.
                }, 
        "ossSchemaVersion": "", // The version of this schema. The current version is "1.0".
        "ruleId": "GetObject", // The ID of the matching event notification rule.
        "region": "", // The bucket's region.
        "requestParameters": {
            "sourceIPAddress": "" // The source IP address of the request.
            }, 
        "responseElements": {
            "requestId": "" // The request ID.
            }, 
        "userIdentity": {
            "principalId": "" // The UID of the user who made the request.
            }, 
        "xVars": {  // Custom parameters in the OSS upload callback feature.
            "x:callback-var1":"value1",
            "x:callback-var2":"value2"
            }
        }        
     }
  ]
}

{"events": [
      {
        "eventName": "ObjectDownloaded:GetObject",
        "eventSource": "acs:oss",
        "eventTime": "2016-07-01T11:17:30.000Z",
        "eventVersion": "1.0",
        "oss": {
            "bucket": {
                "arn": "acs:oss:cn-shenzhen:114895646818****:event-notification-test-shenzhen",
                "name": "event-notification-test-shenzhen",
                "ownerIdentity": "114895646818****"},
            "object": {
                "deltaSize": 0,
                "eTag": "0CC175B9C0F1B6468E1199E269772661",
                "key": "test",
                "readFrom": 0,
                "readTo": 1,
                "size": 1
            },
        "ossSchemaVersion": "1.0",
        "ruleId": "GetObjectRule",
        "region": "cn-shenzhen",
        "requestParameters": {
            "sourceIPAddress": "198.51.100.1"
            },
        "responseElements": {
            "requestId": "5FF16B65F05BC932307A3C3C"
            },
        "userIdentity": {
            "principalId": "114895646818****"
            },
        "xVars": {
            "x:callback-var1":"value1",
            "x:callback-var2":"value2"
            }
        }        
     }
  ]
}

Procedure

1. Log on to the OSS console.

2. In the left-side navigation pane, click Buckets. On the Buckets page, find and click the desired bucket.

3. In the left-side navigation pane, choose Data Processing > Event Notification.

4. On the Event Notification page, click Create Rule.

5. In the Create Rule panel, configure the following parameters:

   Parameter	Description
   Rule Name	Specify a name for the event notification rule. The name must be unique per region and account. It must start with a letter, can contain uppercase letters, lowercase letters, digits, and hyphens (-), and be at most 85 characters.
   Event Type	Select one or more event types. For example, select CopyObject to receive notifications when an object is created or overwritten by a copy operation. A single rule can include multiple event types. When you configure multiple rules, note the following: Rules that match the same objects cannot share event types. For example, if Rule A uses CopyObject for prefix images, Rule B for the same images prefix cannot include CopyObject. Rules that match different objects can share event types. For example, Rule A uses PutObject for prefix images and suffix .png, while Rule B uses PutObject or DeleteObject for prefix log and suffix .jpg. Important In a versioning-enabled bucket, DeleteObject or DeleteObjects events are not triggered if you omit the version ID, because the operation adds a delete marker instead of permanently removing the object. The current version becomes a previous version and a delete marker is added. Event types.
   Object Matching	Specify the target objects for the event notification. Match objects by Full Name To match an object named exampleobject.txt in the root directory of the bucket, enter exampleobject.txt. To match an object named myphoto.jpg in the destdir directory of the bucket, enter destdir/myphoto.jpg. Match objects by Prefix/Suffix To match all objects in the bucket, leave both Prefix and Suffix empty. To match all objects in the examplefolder directory, set Prefix to examplefolder/ and leave Suffix empty. To match all objects with the .jpg extension in the bucket, leave Prefix empty and set Suffix to .jpg. To match all objects with the .mp3 extension in the examplefolder directory, set Prefix to examplefolder/ and Suffix to .mp3. You can click Add Condition to create up to five object matching rules.
   Subscription Endpoint	Specify the endpoint that receives the events. Supported subscription types include HTTP and Queue.

6. Click OK.

   The event notification rule takes effect in about 10 minutes.

FAQ

Why is an event notification not triggered when I delete an object?

References

• Tutorial: Use SMQ to implement OSS event notifications

• If you cannot receive a message body at an HttpEndpoint, it might be because you are using the POST method. For a solution, see What do I do if I cannot receive a message body when I use PHP to write an HttpEndpoint interface in Simple Message Queue (formerly MNS)?

• OSS also provides an upload callback feature as an alternative for upload notifications.