您可通过在消息服务MNS上创建事件通知规则,并且以消息的方式主动推送到指定的接收端,来关注阿里云OSS指定资源上产生的事件。简言之,阿里云OSS通过消息服务MNS实现事件通知(回调)。本文介绍OSS事件通知的适用场景、使用需知、规则注意事项等信息,并举例说明OSS事件通知的具体使用方法。

适用场景

  • 如果您授权其他人可以对您的资源(Bucket)进行某些操作,且希望关注这些操作,则可创建对应规则,使得这些操作发生时,能够主动通知到您。
  • 如果您需要统计操作,也可通过事件通知的方式进行数据分析、查看一段时间内某个操作发生的次数,据此来分析您的业务最近有什么样的发展趋势。此外,您也可以将这些事件通知的消息继续导入其他服务(例如:EMR)来进一步进行您自定义的分析。
  • 您也可以通过事件通知监控您的资源上发生的某些操作的QPS等指标。

使用需知

OSS事件通知流程如下:

OSS事件通知
  1. 创建事件通知规则。
    • 事件通知规则只能由主账号创建。
    • 事件通知规则创建完成后,约10分钟生效。
    • 在没有其他规则的情况下,默认规则匹配所有资源上的所有事件。
    • 在有其他规则并且也有默认规则的情况下,不匹配其他规则的事件会匹配默认规则。
    • 事件通知规则只能创建和删除,目前不支持更新。

    如果您简单的想关注自己所有Bucket上产生的所有事件,可以简单的创建一条默认规则就可以了,即默认事件通知,请参见通过默认规则使用OSS事件通知

    注意 如果仅有默认规则,则默认规则会匹配所有Bucket上产生的所有事件,但一旦创建了其他规则后,默认规则的语义就变成了不匹配其他规则的情况下产生的事件通知才会匹配默认规则。
  2. 请求OSS资源。

    OSS支持将相关操作产生的事件通知到指定的接收端。其中:

    • 不会触发事件通知的操作
      • 失败的操作目前不会触发事件通知。
      • 同步产生的操作不会触发事件通知。
    • 会触发事件通知的操作
      • Lifecycle产生的操作会触发事件通知。
      • 镜像回写会触发两个事件:ObjectDownloaded:GetObject(由于文件还未拉取,因此etag等信息为空)和ObjectCreated:PutObject。
    • 自定义参数
      • OSS事件通知还支持自定义参数,在消息中将您的合法自定义参数放在xVars字段中。自定义参数方法与OSS的Callback保持一致,请参见Callback
  3. 请求返回值

    在请求OSS进行相关操作时,事件通知通过在返回的Response中增加Header来描述触发事件通知的结果,不会影响原定接口的返回值。如果没有匹配事件通知的规则,则不会增加Header;如果匹配到了,不管事件通知是否触发成功,都会增加这个Header。Header格式如下:

    • key:x-oss-process-status
    • value:经过Base64编码,解码后为:
      {
          "code":"Success",  //此次触发事件通知的结果,如果成功,则为Success,否则为Fail,需要注意的是,Success只表示OSS将消息发送到了主题中,并不代表主题将消息推送到了Endpoint
          "message":"NotificationSucceed",   //此次操作的详细描述,如果失败,此处会说明失败的原因
          "type":"EventNotification",   //操作类型,事件通知统一为"EventNotification",判断的时候需要先判断此类型
          "version":"1.0"
      }

    示例如下:

    x-oss-process-status: 'ewogICAgImNvZGUiOiAiU3VjY2VzcyIsCiAgICAibWVzc2FnZSI6ICJOb3RpZmljYXRpb25TdWNjZWVkIiwKICAgICJ0eXBlIjogIkV2ZW50Tm90aWZpY2F0aW9

事件通知中消息推送的相关介绍请参见推送类型

OSS事件类型

OSS支持的事件类型包括:

  • ObjectCreated:PutObject
  • ObjectCreated:PostObject
  • ObjectCreated:CopyObject
  • ObjectCreated:InitiateMultipartUpload
  • ObjectCreated:UploadPart
  • ObjectCreated:UploadPartCopy
  • ObjectCreated:CompleteMultipartUpload
  • ObjectCreate:AppendObject
  • ObjectDownload:GetObject
  • ObjectRemove:DeleteObject
  • ObjectRemove:DeleteObjects
  • ObjectRemoved:AbortMultipartUpload

OSS事件通知消息格式

  • OSS的事件通知消息内容是经过Base64编码的,解码后是JSON格式,格式如下:
    {
        "events":[
            {
                "eventName":"",  //事件通知类型
                "eventSource":"",  //消息源,固定为"acs:oss"
                "eventTime":"",  //事件时间,格式为ISO-8601
                "eventVersion":"",  //版本号,目前为"1.0"
                "oss":{
                    "bucket":{
                        "arn":"",  //Bucket的唯一标识符,格式为"acs:oss:region:uid:bucket"
                        "name":"",  //Bucket名称
                        "ownerIdentity":""   //Bucket的owner
                    },
                    "object":{
                        "deltaSize":,  //Object大小的变化量,比如新增一个文件,这个值就是文件大小,如果是覆盖一个文件,这个值就是新文件与旧文件的差值,因此可能为负数
                        "eTag":"",  //Object的etag,与GetObject()请求返回的ETag头的内容相同
                        "key":"",  //Object名称
                        "position":, //可变项,只有在ObjectCreated:AppendObject事件中才有,表示此次请求开始append的位置,注意是从0开始
                        "readFrom":,  //可变项,只有在ObjectDownloaded:GetObject事件中才有,表示文件开始读取的位置,如果不是Range请求,则此项为0,否则则是Range请求的开始字节,注意是从0开始
                        "readTo":,  //可变项,只有在ObjectDownloaded:GetObject事件中才有,表示文件最后读取的位置,如果不是Range请求,则此项为文件的大小,否则则是Range请求的结束字节增1
                        "size":   //object大小
                    },
                    "ossSchemaVersion":"",  //此字段域的版本号,目前为"1.0"
                    "ruleId":""   //此事件匹配的规则ID
                },
                "region":"",  //Bucket所在的地域
                "requestParameters":{
                    "sourceIPAddress":""  //请求的源IP
                },
                "responseElements":{
                    "requestId":""  //请求对应的Request ID
                },
                "userIdentity":{
                    "principalId":""  //请求发起者的UID
                },
                "xVars":{  //OSS的Callback功能中的自定义参数
                    "x:callback-var1":"value1",
                    "x:vallback-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:114893010724****:event-notification-test-shenzhen",
                        "name":"event-notification-test-shenzhen",
                        "ownerIdentity":"114893010724****"
                    },
                    "object":{
                        "deltaSize":0,
                        "eTag":"0CC175B9C0F1B6A831C399E269772661",
                        "key":"test",
                        "readFrom":0,
                        "readTo":1,
                        "size":1
                    },
                    "ossSchemaVersion":"1.0",
                    "ruleId":"GetObjectRule"
                },
                "region":"cn-shenzhen",
                "requestParameters":{
                    "sourceIPAddress":"140.205.**.**"
                },
                "responseElements":{
                    "requestId":"5776514AF09A9E654242****"
                },
                "userIdentity":{
                    "principalId":"114893010724****"
                },
                "xVars":{
                    "x:callback-var1":"value1",
                    "x:vallback-var2":"value2"
                }
            }
        ]
    }

后续步骤

基于本文了解了OSS通知事件规则和流程后,您可参见以下文档执行具体的操作。