Event Notifications

SMN-Enabled Event Notification

Simple Message Notification (SMN) is a reliable and extensible message notification service that can handle a huge number of messages. SMN significantly simplifies system coupling. It can automatically push messages to subscribers through emails and text messages.

OBS uses SMN to provide the event notification function. You can use SMN to send event notifications to specified subscribers to inform them in real time of critical operations (such as upload and deletion) that occur on specified buckets. For example, you can configure an event notification rule to send messages through SMN to the specified email address whenever an upload operation occurs on the specified bucket.

You can configure an event notification rule to filter objects by the object name prefix or suffix. For example, you can add an event notification rule to send notifications whenever an object with the .jpg suffix is uploaded to the specified bucket. You can also add an event notification rule to send notifications whenever an object with the images/ prefix is uploaded to the specified bucket.

Figure 1 SMN-enabled event notification

Event Types Supported by OBS

OBS can publish events of the following types. You need to specify these event types in the notification settings.

Constraints

• A configuration with no filtering attributes contained matches all prefixes and suffixes by default.
• When there are two suffixes configured, if a given string can end with both suffixes, this configuration is invalid due to suffix overlapping (for example, suffixes jpg and pg). This also works for prefixes.

Destinations Supported by OBS

OBS can send event notification messages to SMN topics. You must grant OBS the permissions to send messages to these destinations. In addition, you need to specify the URN values of these destinations in the notification configuration.

How to Enable Event Notifications

Enabling notifications is a bucket-level operation. OBS stores your event notification configuration to bucket sub-resources in the format of XML. By default, notification is not enabled for any event type. That is, the initial event notification configuration of each bucket is empty.

To enable notifications for events of specific types, you must add the corresponding XML configuration that identifies the event types you want OBS to publish and the destination where you want the notifications to be published.

• In this example, you need to publish event messages to an SMN topic. To set an SMN topic as the notification destination for specific event types, add the TopicConfiguration.

<NotificationConfiguration>
  <TopicConfiguration>
    <Id>optional-id-string</Id>
    <Topic>topic-urn</Topic>
    <Event>event-type</Event>
    <Event>event-type</Event>
     ...
  </TopicConfiguration>
   ...
</NotificationConfiguration>

Using Object Key Names to Filter Event Notifications

You can configure event notifications based on the prefix and suffix of an object key name. For example, you can set up a configuration so that a notification is published only when objects with a .jpg extension are added to a bucket.

OBS stores the notification configuration as XML. You can use the Filter element in the XML structure to define the rules for notifications to be filtered by the prefix and/or suffix of an object key name. Notification configurations that use the filter cannot define filtering rules with overlapping prefixes, overlapping suffixes, or prefix and suffix overlapping. The following are examples of notification configurations with object key name filtering:

• Example of valid notification configuration with object key name filtering

  The following information contains a configuration identifying an SMN topic to which OBS publishes events of the ObjectCreated:Put type. The events will be published each time an object that has an image prefix and a jpg suffix is PUT to a bucket.

  <NotificationConfiguration>
    <TopicConfiguration>
      <Id>01</Id>
      <Filter>
        <Object>
          <FilterRule>
            <Name>prefix</Name>
            <Value>image</Value>
          </FilterRule>
          <FilterRule>
            <Name>suffix</Name>
            <Value>jpg</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:notification</Topic>
      <Event>ObjectCreated:Put</Event>
    </TopicConfiguration>
  </NotificationConfiguration>

  The following notification configuration has multiple non-overlapping prefixes. The configuration defines the following: When objects that have a prefix of images are uploaded to buckets, event notifications will be published to topic-A; when objects that have a prefix of videos are uploaded to buckets, event notifications will be published to topic-B.

  <NotificationConfiguration>
    <TopicConfiguration>
      <Id>01</Id>
      <Filter>
        <Object>
          <FilterRule>
            <Name>prefix</Name>
            <Value>images</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-A</Topic>
      <Event>ObjectCreated:Put</Event>
    </TopicConfiguration>
    <TopicConfiguration>
      <Id>02</Id>
      <Filter>
        <Object>
          <FilterRule>
            <Name>prefix</Name>
            <Value>videos</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-B</Topic>
      <Event>ObjectCreated:Put</Event>
    </TopicConfiguration>
  </NotificationConfiguration>

  The following notification configuration has multiple non-overlapping suffixes. The configuration defines the following: Notifications will be published to topic-A for all .jpg objects PUT to buckets, and notifications will be published to topic-B for all .png objects. The suffixes .png and .jpg are not overlapping even though they have the same last letter.

  <NotificationConfiguration>
    <TopicConfiguration>
      <Id>01</Id>
      <Filter>
        <Object>
          <FilterRule>
            <Name>suffix</Name>
            <Value>.jpg</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-A</Topic>
      <Event>ObjectCreated:Put</Event>
    </TopicConfiguration>
    <TopicConfiguration>
      <Id>02</Id>
      <Filter>
        <Object>
          <FilterRule>
            <Name>suffix</Name>
            <Value>.png</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-B</Topic>
      <Event>ObjectCreated:Put</Event>
    </TopicConfiguration>
  </NotificationConfiguration>

• Examples of notification configuration with invalid prefix/suffix overlapping

  In most cases, notification configurations that use the filter cannot define filtering rules with overlapping prefixes, overlapping suffixes, or overlapping combinations of prefixes and suffixes for the same event types. (You can have overlapping prefixes if the suffixes do not overlap.) You can use overlapping object key name filtering rules with different event types. For example, you can create a notification configuration that uses the image prefix for the ObjectCreated:Put event type and the image prefix for the ObjectDeleted:* event type.

  A configuration with no filtering attributes contained matches all prefixes and suffixes by default. The following notification configuration is invalid because it contains overlapping prefixes. (The same thing would be true if suffix instead of prefix is used in this example.)

  <NotificationConfiguration>
    <TopicConfiguration>
      <Topic>urn:smn:southchina:11aa22bb:topic-A</Topic>
      <Event>ObjectCreated:*</Event>
    </TopicConfiguration>
    <TopicConfiguration>
      <Filter>
        <Object>
          <FilterRule>
            <Name>prefix</Name>
            <Value>abc</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-B</Topic>
      <Event>ObjectCreated:*</Event>
    </TopicConfiguration>
  </NotificationConfiguration>

  The following notification configuration is invalid because it contains overlapping suffixes. Two suffixes are considered overlapping if a given string can end with both suffixes. A string can end with jpg and pg. Therefore, the suffixes are overlapping. (The same is true for prefixes.)

  <NotificationConfiguration>
    <TopicConfiguration>
      <Filter>
        <Object>
          <FilterRule>
            <Name>suffix</Name>
            <Value>jpg</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-A</Topic>
      <Event>ObjectCreated:*</Event>
    </TopicConfiguration>
    <TopicConfiguration>
      <Filter>
        <Object>
          <FilterRule>
            <Name>suffix</Name>
            <Value>pg</Value>
          </FilterRule>
        </Object>
      </Filter>
      <Topic>urn:smn:southchina:11aa22bb:topic-B</Topic>
      <Event>ObjectCreated:Put</Event>
    </TopicConfiguration>
  </NotificationConfiguration>

Event Message Structure

A notification message sent by OBS to publish an event is a JSON message with the following structure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

{  
    "Records":[
        {
            "eventVersion":"", //Version number. The current version is 3.0.
            "eventSource":"", //Message source. The value is fixed to OBS.
            "eventRegion":"", //Region where the event occurs
            "eventTime":"", //Time when an event occurs, in the ISO-8601 format, for example, 2020-07-10T09:24:11.418Z
            "eventName":"", //Name of the event that triggers the notification
            "userIdentity":{
                "ID":"" //Billing ID of the user who triggers the event
            },
            "requestParameters":{
                "sourceIPAddress":"" //Source IP address of the request
            },
            "responseElements":{
                "x-obs-request-id":"", //ID of the request
                "x-obs-id-2":"" ///Special characters for locating problems
            },
            "obs":{
                "Version":"1.0",
                "configurationId":"", //Name of the event notification rule in OBS that matches the event
                "bucket":{
                    "name":"examplebucket",
                    "ownerIdentity":{
                        "ID":"" //Account ID of the bucket owner
                    },
                    "bucket":"" //Bucket name
                },
               "object":{
                    "key":"", //Object name
                    "eTag":"", //ETag of the object
                    "size": , //Object size
                    "versionId":"null", //Version ID of the object
                    "sequencer":""  //Identifier that defines the event sequence of a specific object
                }
            }
        }
    ]
}

Note the following:

• You can use the responseElements key-value to trace OBS requests. Both x-obs-request-id and x-obs-id-2 can be used to trace a single request. Their value is the one returned by OBS in the response to the request.
• The obs key-value contains information about the bucket and object involved in the event. Note that the object key name is URL-encoded. For example, TEST/Chinese.jpg is changed to TEST%2F%E4%B8%AD+%E6%96%87%2F.jpg.
  

  During secondary development, if you use the OBS SDK to download the object, you need to decode the URL-coded object name and then call the API for download. If a web browser is used to access the object, decoding is not required.

• The sequencer key-value determines the sequence of events. Generally, event notifications do not arrive in the order that the events occurred. However, notifications from events for creating objects (PUT) and deleting objects (DELETE) contain a sequencer, which can be used to determine the order of events for a given object key. If you compare the hexadecimal sequencer strings of two event notifications on the same object key, the event notification with the greater sequencer value is the event that occurred later.
  

  1. The sequencer cannot be used to determine the sequence for events on different object keys.
  2. The event sequence indicated by sequencer is for reference only, which does not work for highly reliable systems

How to Use

You can configure SMN notifications using OBS Console or APIs.