You may want to monitor changes to objects in Object Storage Service (OSS) for various purposes, such as real-time processing, synchronization, listening, business logic triggers, and logging. You can configure event notification rules to monitor objects and receive notifications. This way, you can take appropriate action at the earliest opportunity.
Prerequisites
Simple Message Queue (SMQ) is activated. You can activate SMQ on the SMQ product page.
Usage notes
Event notifications require OSS and SMQ to work in a coordinated manner. When an operation is performed on your OSS resources, an event notification rule is triggered for SMQ to send a message. SMQ may fail to be triggered to send a message. You can check the value (Base64-encoded) of the x-oss-event-status header in the response to determine whether SMQ is triggered. If the decoded value of the x-oss-event-status header is {"Result": "Ok"}, SMQ is triggered. If the decoded value of the x-oss-event-status header is not {"Result": "Ok"}, SMQ is not triggered.
You are charged by SMQ when you use the event notification feature. For more information, see Billing.
You can configure event notification rules for objects in buckets that are located in the following regions: China (Hangzhou), China (Shanghai), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Shenzhen), China (Chengdu), China (Hong Kong), US (Silicon Valley), US (Virginia), Japan (Tokyo), Singapore, Australia (Sydney) Closing Down, Indonesia (Jakarta), Philippines (Manila), Germany (Frankfurt), and UK (London).
You can configure up to 10 event notification rules in a region.
Notifications are not triggered for TS and M3U8 objects that are generated by stream ingest over Real-Time Messaging Protocol (RTMP). For more information about stream ingest over RTMP, see Overview.
How it works
If an operation performed on your OSS resources triggers an event notification rule, SMQ sends a notification about the operation to the specified HTTP server or SMQ queue. The following figure shows the process in detail.
Events
The ObjectCreatedGroup, ObjectDownloadedGroup, and ObjectRemovedGroup events are supported only in the following regions: China (Hong Kong), US (Silicon Valley), US (Virginia), Germany (Frankfurt), Australia (Sydney) Closing Down, Singapore, and UK (London).
Event type | Description | Event name in a notification |
PutObject | An object is created or overwritten by using simple upload. | ObjectCreated:PutObject |
PostObject | An object is created or overwritten by using form upload. | ObjectCreated:PostObject |
CopyObject | An object is created or overwritten by copying an object. | ObjectCreated:CopyObject |
InitiateMultipartUpload | A multipart upload task is initiated. | ObjectCreated:InitiateMultipartUpload |
UploadPart | An object is created or overwritten by using multipart upload. | ObjectCreated:UploadPart |
UploadPartCopy | An object is created or overwritten by using multipart copy. | ObjectCreated:UploadPartCopy |
CompleteMultipartUpload | A multipart upload task is complete. | ObjectCreated:CompleteMultipartUpload |
AbortMultipartUpload | A multipart upload task is canceled and uploaded parts are deleted. | ObjectRemoved:AbortMultipartUpload |
AppendObject | An object is created or appended by using append upload. | ObjectCreated:AppendObject |
GetObject | An object is obtained by using simple download. | ObjectDownloaded:GetObject |
DeleteObject | An object is deleted. | ObjectRemoved:DeleteObject |
DeleteObjects | Multiple objects are deleted. | ObjectRemoved:DeleteObjects |
ObjectReplication:ObjectCreated | An object is created in a data replication task. | ObjectReplication:ObjectCreated |
ObjectReplication:ObjectRemoved | An object is deleted in a data replication task. | ObjectReplication:ObjectRemoved |
ObjectReplication:ObjectModified | An object is overwritten in a data replication task. | ObjectReplication:ObjectModified |
ObjectCreatedGroup | An object creation or overwrite operation is performed. | The event name in a notification can be any event that starts with ObjectCreated:, depending on the upload method that you select. For example, when an object is uploaded by using an OSS SDK by performing simple upload, the event name in a notification is ObjectCreated:PutObject. When an object is uploaded in the OSS console, the event name in a notification is ObjectCreated:PostObject. |
ObjectDownloadedGroup | An object download operation is performed. | The event name in a notification can be any event that starts with ObjectDownloaded:, depending on the download method that you select. For example, when an object is downloaded by performing simple upload, the event name in a notification is ObjectDownloaded:GetObject. |
ObjectRemovedGroup | An object deletion operation is performed. | The event name in a notification can be any event that starts with ObjectRemoved:, depending on the deletion method that you select. For example, when an object is deleted, the event name in a notification is ObjectRemoved:DeleteObject. When multiple objects are deleted at a time, the event name in a notification is ObjectRemoved:DeleteObjects. |
FinishRestore | An object restoration operation is complete. The event type supports only Cold Archive and Deep Cold Archive objects. | ObjectRestore:FinishRestore |
Event notifications
The content of OSS event notifications is Base64-encoded. After the content is decoded, the content is in the JSON format. The following sample code provides an example of the decoded event notification content:
{"events": [
{
"eventName": "", // The event name.
"eventSource": "", // The source that triggers the event notification rule. Valid value: acs:oss.
"eventTime": "", // The time when the event occurred. The time is a timestamp in the ISO 8601 standard.
"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 following format: acs:oss:region:uid:bucketname.
"name": "", // The name of the bucket that contains the objects to which the event notification rule applies.
"ownerIdentity": "" // The owner of the bucket.
},
"object": {
"deltaSize": "", // The size difference between the new object and the original object. If an object is created, the value of this parameter indicates the size of the object. If an object is overwritten, the value indicates the difference between the sizes of the new object and the original object. The value may be negative.
"eTag": "", // The ETag value of the object.
"key": "", // The name of the object.
"position": "", // The position from which the AppendObject operation starts. This parameter applies only to the ObjectCreated:AppendObject event. The first AppendObject operation on an object starts from byte 0 of the object.
"readFrom": "", // The position from which the GetObject operation starts. This parameter applies only to the ObjectDownloaded:GetObject event. If the GetObject operation is not performed by range, the value of this parameter is 0. Otherwise, the value refers to the position of the byte from which the GetObject operation starts.
"readTo": "", // The position at which the GetObject operation ends. This parameter applies only to the ObjectDownloaded:GetObject event. If the GetObject operation is not performed by range, the value of this parameter is the object size. Otherwise, the value refers to the position of the first byte after the byte at which the GetObject operation ends.
"size": "" // The size of the object.
},
"ossSchemaVersion": "", // The version of the schema. The current value is 1.0.
"ruleId": "GetObject", // The ID of the event notification rule that is triggered by the event.
"region": "", // The region in which the bucket is located.
"requestParameters": {
"sourceIPAddress": "" // The source IP address from which the request is sent.
},
"responseElements": {
"requestId": "" // The ID of the request.
},
"userIdentity": {
"principalId": "" // The UID of the requester.
},
"xVars": { // The custom parameters of an OSS callback.
"x:callback-var1":"value1",
"x:vallback-var2":"value2"
}
}
}
]
}
The following sample code provides an example of an event notification:
{"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:vallback-var2":"value2"
}
}
}
]
}
Procedure
Log on to the OSS console.
In the left-side navigation pane, click Buckets. On the Buckets page, find and click the desired bucket.
In the left-side navigation tree, choose Data Processing > Event Notification.
On the Event Notification page, click Create Rule.
In the Create Rule panel, configure the parameters that are described in the following table.
Parameter
Description
Rule Name
Specify the name of the event notification rule.
The name of an event notification rule must be unique in a region within an Alibaba Cloud account. The name must start with a letter and can contain only letters, digits, and hyphens (-). The name cannot exceed 85 characters in length.
Event Type
Select one or more events from the drop-down list. For example, if you want to receive a notification when a specific object is created or overwritten by copying an object, select CopyObject.
You can configure an event notification rule for a specific object and specify multiple events that can trigger the rule. You can also configure multiple event notification rules for an object. When you configure multiple event notification rules, take note of the following items:
If multiple event notification rules apply to the same object, the events configured in these rules must be different. For example, if you select CopyObject for Event Type when you create an event notification rule for objects whose names contain the
images
prefix, you cannot select CopyObject for Event Type when you create another event notification rule that applies to objects whose names contain the same prefix.If multiple event notification rules apply to different objects, the values of this parameter in these rules can be the same or different. For example, if you select PutObject for Event Type when you create an event notification rule for objects whose names contain the
images
prefix and the.png
extension, you can select PutObject or DeleteObject for Event Type when you create another event notification rule for objects whose names contain thelog
prefix and the.jpg
extension.
ImportantIf you delete an object from a versioning-enabled bucket without specifying a version ID, the event notification rule for the DeleteObject or DeleteObjects event is not triggered. In this case, no version of the object is deleted. The current version of the object is stored as a previous version and a delete marker is added to the object.
For more information about object operations that can trigger events, see Events.
Resource Description
Specify the objects to which you want to apply the event notification rule.
Select Full Name to apply the rule to an object whose name is the same as the specified name.
To create a rule that applies to an object named exampleobject.txt in the root directory of the bucket, enter exampleobject.txt.
To create a rule that applies to an object named myphoto.jpg in the destdir directory within the root directory of the bucket, enter destdir/myphoto.jpg.
Select Prefix/Suffix to apply the rule to objects whose names contain a specific prefix and extension.
To create a rule that applies to all objects in the bucket, leave Prefix and Suffix empty.
To create a rule that applies to all objects in the examplefolder directory within the root directory of the bucket, set Prefix to examplefolder/ and leave Suffix empty.
To create a rule that applies to all JPG objects in the bucket, leave Prefix empty and set Suffix to .jpg.
To create a rule that applies to all MP3 objects in the examplefolder directory within the root directory of the bucket, set Prefix to examplefolder/ and Suffix to .mp3.
To add another Resource Description entry, click Add. You can specify up to five Resource Description entries in an event notification rule.
Endpoint
Specify the endpoint to which event notifications are sent. Valid value: HTTP and Queue.
HTTP: Specify an HTTP endpoint. Example:
http://198.51.100.1:8080
. For more information about how to obtain an HTTP endpoint, see Manage topics and HttpEndpoint.Queue: Enter the name of an SMQ queue. For more information about how to create a queue, see Create a queue.
To add more endpoints or queues, click Add. You can specify up to five Endpoint entries in an event notification rule.
Click OK.
After you configure an event notification rule, the rule takes effect after approximately 10 minutes.
FAQ
References
You can configure event notification rules to monitor specific objects in OSS and receive notifications about object changes. For more information, see Tutorial: Use SMQ to send notifications of OSS events.
If you fail to receive the body of a notification message by calling the HttpEndpoint operation, the reason could be that you used the POST method. To resolve the issue, see What do I do if I am unable to receive the HTTP body when I write the HttpEndpoint operation in PHP?
You can use the upload callback feature of OSS to implement upload callbacks. For more information, see Upload callbacks.