通过创建事件通知规则,轻量消息队列(原 MNS)可以将对象存储 OSS(Object Storage Service)指定资源上产生的事件以消息的方式主动推送到指定的接收端。本文介绍对象存储OSS事件通知的背景信息、适用场景、事件类型、消息格式及操作步骤。
背景信息
如下图所示,如果您创建了事件通知规则,当您在请求OSS进行相关操作时,轻量消息队列(原 MNS)将OSS指定资源上产生的事件以消息的方式推送到接收端。
在请求OSS进行相关操作时,事件通知通过在返回的Response中增加Header来描述触发事件通知的结果,不会影响原定接口的返回值。如果没有匹配事件通知的规则,则不会增加Header;如果匹配成功,不管事件通知是否触发成功,都会增加这个Header。Header格式如下:
x-oss-process-status: 'ewogICAgImNvZGUiOiAiU3VjY2VzcyIsCiAgICAibWVzc2FnZSI6ICJOb3RpZmljYXRpb25TdWNjZWVkIiwKICAgICJ0eXBlIjogIkV2ZW50Tm90aWZpY2F****'
key:x-oss-process-status
value:经过Base64编码,解码后为:
{ "code":"Success", //此次触发事件通知的结果。如果成功,返回Success,否则为Fail。Success表示OSS将消息发送到了主题,并不代表主题将消息推送到了Endpoint。 "message":"NotificationSucceed", //此次操作的详细描述。如果失败,此处会说明失败的原因。 "type":"EventNotification", //操作类型。事件通知的操作类型统一为EventNotification。 "version":"1.0" }
更多消息推送的内容,请参见推送类型。
适用场景
当您授权其他用户对您的资源(Bucket)进行某些操作的权限,且希望关注这些操作,可以通过创建规则,在这些操作发生时主动通知您。
通过事件通知的方式进行数据分析、查看一段时间内某个操作发生的次数,分析您的业务最近的发展趋势。您还可以将这些事件通知的消息导入其他服务,例如EMR,进一步进行自定义分析。
通过事件通知监控您的资源上发生的某些操作的QPS等指标。
事件类型
分组 | 类型 | 说明 |
ObjectCreated(创建文件) | ObjectCreated:PutObject | Put方法上传文件。详情请参见PutObject。 |
ObjectCreated:PostObject | Post方法上传文件。详情请参见PostObject。 | |
ObjectCreated:CopyObject | 拷贝文件。详情请参见 CopyObject。 | |
ObjectCreated:AppendObject | 追加写方式上传文件。详情请参见AppendObject。 | |
ObjectCreated:InitiateMultipartUpload | 初始化分片上传任务。详情请参见 InitiateMultipartUpload。 | |
ObjectCreated:UploadPart | 分片上传文件。详情请参见UploadPart。 | |
ObjectCreated:UploadPartCopy | 分片拷贝文件。详情请参见UploadPartCopy。 | |
ObjectCreated:CompleteMultipartUpload | 完成分片上传。详情请参见CompleteMultipartUpload。 | |
ObjectCreated:PutSymlink | 为文件创建软链接。详情请参见PutSymlink。 | |
ObjectCreated:* | 任意以 说明 未来新增事件中,此项默认涵盖新增的符合要求的事件,例如新增ObjectCreated:test类型,匹配成功并投递。 | |
ObjectDownloaded(下载文件) | ObjectDownloaded:GetObject | 通过简单下载获取文件。 |
ObjectModified(修改文件) | ObjectModified:UpdateObjectMeta | 调用UpdateObjectMeta接口修改某个对象的属性。 |
ObjectModified:ChangeStorageClass | 通过生命周期规则转换存储类型。 说明 仅华南3(广州)地域支持该事件。 | |
ObjectModified:* | 任意以 说明 未来新增事件中,此项默认涵盖新增的符合要求的事件,例如新增ObjectModified:test类型,匹配成功并投递。 | |
ObjectRemoved(删除文件) | ObjectRemoved:DeleteObject | 删除单个文件。详情请参见DeleteObject。 |
ObjectRemoved:DeleteObjects | 删除多个文件。详情请参见DeleteMultipleObjects。 | |
ObjectRemoved:AbortMultipartUpload | 取消分片上传任务并删除对应的分片。详情请参见AbortMultipartUpload。 | |
ObjectRemoved:* | 任意以 说明 未来新增事件中,此项默认涵盖新增的符合要求的事件,例如新增ObjectRemoved:test类型,匹配成功并投递。 | |
ObjectReplication(复制文件) | ObjectReplication:ObjectCreated | 数据复制过程涉及的写入操作。 |
ObjectReplication:ObjectRemoved | 数据复制过程涉及的删除操作。 | |
ObjectReplication:ObjectModified | 数据复制过程涉及的覆盖操作。 | |
ObjectReplication:* | 任意以 说明 未来新增事件中,此项默认涵盖新增的符合要求的事件,例如新增 ObjectReplication:test 类型,匹配成功并投递。 | |
ObjectRestore(恢复文件) | ObjectRestore:FinishRestore | 对象恢复完成,将对象从冷归档中恢复到可访问的状态。该事件类型仅支持冷归档存储、深度冷归档存储类型的Object。 |
消息格式
对象存储OSS的事件通知消息内容是经过Base64编码的,解码后是JSON格式,示例代码如下所示。
{
"events":[
{
"eventName":"ObjectDownloaded:GetObject",
"eventSource":"acs:oss",
"eventTime":"2016-07-01T11:17:30.000Z",
"eventVersion":"1.0",
"oss":{
"bucket":{
"arn":"acs:oss:cn-shenzhen:123456789098****:event-notification-test-shenzhen",
"name":"event-notification-test-shenzhen",
"ownerIdentity":"123456789098****"
},
"object":{
"deltaSize":0,
"eTag":"0CC175B9C0F1B6A831C399E26977****",
"key":"test",
"readFrom":0,
"readTo":1,
"size":1
},
"ossSchemaVersion":"1.0",
"ruleId":"GetObjectRule"
},
"region":"cn-shenzhen",
"requestParameters":{
"sourceIPAddress":"140.205.XX.XX"
},
"responseElements":{
"requestId":"5776514AF09A9E654242****"
},
"userIdentity":{
"principalId":"123456789098****"
},
"xVars":{
"x:callback-var1":"value1",
"x:vallback-var2":"value2"
}
}
]
}
参数解释如下所示。
参数 | 描述 |
eventName | 事件类型。 |
eventSource | 事件源。 |
eventTime | 事件产生的时间。 |
eventVersion | 事件协议的版本。 |
oss | OSS事件内容。 |
bucket | bucket参数内容。 |
arn | Bucket的唯一标识符。 |
name | Bucket的名称。 |
ownerIdentity | 创建Bucket的用户ID。 |
object | Object参数内容。 |
deltaSize | Object的大小变化量。 |
eTag | Object的内容。对于Put Object请求创建的Object,ETag值是其内容的MD5值;对于其他方式创建的Object,ETag值是基于一定计算规则生成的唯一值,但不是其内容的MD5值。ETag值可以用于检查Object内容是否发生变化。 |
key | Object的名称。 |
readFrom | 文件开始读取的位置。 |
readTo | 文件最后读取的位置 |
size | Object的大小。 |
ossSchemaVersion | OSS模式的版本号。 |
ruleId | 事件匹配的规则ID。 |
region | Bucket所在的地域。 |
requestParameters | 请求参数值。 |
sourceIPAddress | 请求的源IP。 |
responseElements | 返回参数值。 |
requestId | 请求对应的Request ID。 |
userIdentity | 用户信息。 |
principalId | 请求发起者的UID。 |
xVars | OSS的Callback功能中的自定义参数。 |
注意事项
事件通知规则创建完成后,约10分钟生效。
系统会自动为新建的规则创建主题,主题可能产生费用,详情请参见计费说明。
事件通知规则支持创建和删除,暂时不支持修改。
(可选)步骤一:创建队列
当下游订阅为队列(Queue) 时,需要创建队列,您也可以在事件规则创建后进行订阅新增。
在左侧导航栏,选择 。
在顶部菜单栏,选择地域。
在队列列表页面,单击创建队列。
在创建队列面板配置以下参数,然后单击确定。
名称:队列名称。
消息最大长度:发送到队列的消息体的最大长度。
长轮询时间:当队列中没有消息时,该队列的ReceiveMessage请求的最大等待时长。
消息可见性超时时间:消息从队列中取出后从Active状态变成Inactive状态后的持续时间。
消息保存时长:消息在队列中的最长存活时间。从发送到队列开始经过此参数指定的时间后,不论消息是否被取出都将被删除。
消息延时时间:发送到队列的所有消息将延后此参数指定的时间后被消费。
启用日志功能:是否开启日志管理功能。
队列列表页面目标队列已创建。
(可选)步骤二:创建Bucket
若已存在需要的Bucket,本步骤可跳过。
登录OSS管理控制台。
在左侧导航栏,单击Bucket列表。
在Bucket列表页面,单击创建Bucket。
在创建 Bucket面板,配置Bucket参数,然后单击确定。
Bucket 名称:输入event-notification-test。
地域:跟队列所在的地域保持一致。
阻止公共访问:不开通
读写权限:选择公共读写。
说明其他配置项请保持默认。
步骤三:创建自定义规则
创建一个新规则后,轻量消息队列(原 MNS)会自动创建一个主题,并且以指定的Endpoint创建订阅。您可以在轻量消息队列(原 MNS)控制台查看和管理这些主题与订阅(例如创建新的订阅)。
在左侧导航栏,单击事件通知。
在顶部菜单栏,选择地域。
在事件通知页面,单击对象存储OSS页签, 然后单击创建规则。
在创建规则-对象存储OSS面板,进行以下配置,然后单击确定。
名称:输入规则名称。
事件类型:选择事件类型。
匹配规则:设置匹配规则。
说明匹配规则可以是全名、前缀、后缀以及前后缀,不同规则不能有交集。OSS资源包括Bucket和Object,通过“/”连接。例如:资源movie/hello.avi由Bucket(movie)和Object(hello.avi)组成。
全名:movie/hello.avi。
前缀:
movie/hello:movie中以hello为前缀的Object。
movie/:Bucket名称为movie的所有的Object。
mov:Bucket名称前缀为mov的所有Object。
后缀:.avi:所有Bucket中以.avi为后缀的Object。
前后缀:前缀movie/,后缀.avi:movie中所有以.avi为后缀的Object。
接收终端:选择队列,输入步骤一中创建的队列名称。
步骤四:上传Object
登录OSS管理控制台。
在左侧导航栏,单击Bucket列表。
在Bucket列表页面,单击Bucket名称列下的目标Bucket。
选择 ,然后单击上传文件。
在上传文件面板,配置文件上传目录和文件ACL,单击上传文件。更多配置参数信息,请参见使用OSS控制台上传文件。
状态列显示:上传成功。
步骤五:接收消息
在左侧导航栏,选择 。
在顶部菜单栏,选择地域。
在队列列表页面,找到目标队列,在其右侧操作列选择 。
在队列收发消息快速体验页面的接收消息区域,单击接收消息。
接收消息区域显示队列的消息列表。
在消息列表中,找到目标消息,在其右侧操作列单击详情,在消息详情对话框中查看消息内容。