OSS事件通知

通過建立事件通知規則，輕量訊息佇列（原 MNS）可以將Object Storage Service (OSS)指定資源上產生的事件以訊息的方式主動推送到指定的接收端。本文介紹Object Storage Service事件通知的背景資訊、適用情境、事件類型、訊息格式及操作步驟。

背景資訊

如下圖所示，如果您建立了事件通知規則，當您在請求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:`為首碼的事件。說明未來新增事件中，此項預設涵蓋新增的符合要求的事件，例如新增ObjectCreated:test類型，匹配成功並投遞。
ObjectDownloaded（下載檔案）	ObjectDownloaded:GetObject	通過簡單下載擷取檔案。
ObjectModified（修改檔案）	ObjectModified:UpdateObjectMeta	調用UpdateObjectMeta介面修改某個對象的屬性。
	ObjectModified:ChangeStorageClass	通過生命週期規則轉換儲存類型。說明僅華南3（廣州）地區支援該事件。
	ObjectModified:*	任意以`ObjectModified:`為首碼的事件。說明未來新增事件中，此項預設涵蓋新增的符合要求的事件，例如新增ObjectModified:test類型，匹配成功並投遞。
ObjectRemoved（刪除檔案）	ObjectRemoved:DeleteObject	刪除單個檔案。詳情請參見DeleteObject。
	ObjectRemoved:DeleteObjects	刪除多個檔案。詳情請參見DeleteMultipleObjects。
	ObjectRemoved:AbortMultipartUpload	取消分區上傳任務並刪除對應的分區。詳情請參見AbortMultipartUpload。
	ObjectRemoved:*	任意以`ObjectRemoved:`為首碼的事件。說明未來新增事件中，此項預設涵蓋新增的符合要求的事件，例如新增ObjectRemoved:test類型，匹配成功並投遞。
ObjectReplication（複製檔案）	ObjectReplication:ObjectCreated	資料複製過程涉及的寫入操作。
	ObjectReplication:ObjectRemoved	資料複製過程涉及的刪除操作。
	ObjectReplication:ObjectModified	資料複製過程涉及的覆蓋操作。
	ObjectReplication:*	任意以`ObjectReplication:`為首碼的事件。說明未來新增事件中，此項預設涵蓋新增的符合要求的事件，例如新增 ObjectReplication:test 類型，匹配成功並投遞。
ObjectRestore（恢複檔案）	ObjectRestore:FinishRestore	對象恢複完成，將對象從冷歸檔中恢複到可訪問的狀態。該事件類型僅支援冷Archive Storage、深度冷Archive Storage類型的Object。

訊息格式

Object Storage Service的事件通知訊息內容是經過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）時，需要建立隊列，您也可以在事件規則建立後進行訂閱新增。

登入輕量訊息佇列（原 MNS）控制台。
在左側導覽列，選擇队列模型 > 队列列表。
在頂部功能表列，選擇地區。
在队列列表頁面，單擊创建队列。
在创建队列面板配置以下參數，然後單擊确定。
- 名称：隊列名稱。
- 消息最大长度：發送到隊列的訊息體的最大長度。
- 长轮询时间：當隊列中沒有訊息時，該隊列的ReceiveMessage請求的最大等待時間長度。
- 消息可见性超时时间：訊息從隊列中取出後從Active狀態變成Inactive狀態後的期間。
- 消息保存时长：訊息在隊列中的最長存活時間。從發送到隊列開始經過此參數指定的時間後，不論訊息是否被取出都將被刪除。
- 消息延时时间：發送到隊列的所有訊息將延後此參數指定的時間後被消費。
- 启用日志功能：是否開啟日誌管理功能。
队列列表頁面目標隊列已建立。

（可選）步驟二：建立Bucket

若已存在需要的Bucket，本步驟可跳過。

登入OSS管理主控台。
在左側導覽列，單擊Bucket列表。
在Bucket列表頁面，單擊建立Bucket。
在建立 Bucket面板，配置Bucket參數，然後單擊確定。
- Bucket 名稱：輸入event-notification-test。
- 地區：跟隊列所在的地區保持一致。
- 阻止公用訪問：不開通
- 讀寫權限：選擇公用讀寫。
  說明
  其他配置項請保持預設。

步驟三：建立自訂規則

建立一個新規則後，輕量訊息佇列（原 MNS）會自動建立一個主題，並且以指定的Endpoint建立訂閱。您可以在輕量訊息佇列（原 MNS）控制台查看和管理這些主題與訂閱（例如建立新的訂閱）。

登入輕量訊息佇列（原 MNS）控制台。
在左側導覽列，單擊事件通知。
在頂部功能表列，選擇地區。
在事件通知頁面，單擊Object Storage Service頁簽，然後單擊建立規則。
在建立規則-Object Storage Service面板，進行以下配置，然後單擊確定。
- 名稱：輸入規則名稱。
- 事件類型：選擇事件類型。
- 匹配規則：設定匹配規則。
  說明
  匹配規則可以是全名、首碼、尾碼以及前尾碼，不同規則不能有交集。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。
- 接收終端：選擇隊列，輸入步驟一中建立的隊列名稱。