Event Types Supported by OBS

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

Destinations Supported by OBS

OBS can send event notification messages to the following destinations. You must grant the OBS 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, for example,

• publishing 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 set event notification by 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 for OBS to publish events of the ObjectCreated:Put type to. 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 imageprefix for the ObjectDeleted:* event type.

  Configuration information that does not contain the filter attribute 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:

• If you want to trace the request by following up with the OBS support, the responseElements key value is useful. Both x-obs-request-id and x-obs-id-2 help OBS to trace the individual request. These values are the same as those returned by the OBS in response to your original request.
• The key values provide information about the bucket and object involved in the event. The object key name value is URL-encoded, for example, the key name TEST/Chinese .jpg is encoded to TEST%2F%E4%B8%AD+%E6%96%87%2F.jpg.
  

  During secondary development, if you want to download this object using SDK, you need to decode the object key name from the URL-encoded format, and then call the API for downloading. If you use a browser to access the object, decoding is not required.

• The sequencer key provides a way to determine the sequence of events. Event notifications are not guaranteed to arrive in the sequence that the events occurred. However, notifications from events that create objects (PUTs) and delete objects contain a sequencer, which can be used to determine the sequence of events for a given object key. If you compare the hexadecimal sequencer strings from two event notifications on the same object key, you will find that the event notification with the greater sequencer value is the later event.
  

  1. The sequencer cannot be used to determine the sequence for events on different object keys.
  2. The value of sequencer is for reference only, and cannot be used in highly reliable systems