257      群英

PutBucketLogging__關於Bucket的操作_API 參考_對象存儲 OSS-阿裏雲

OSS提供Bucket訪問日誌的目的是為了方便bucket的擁有者理解和分析bucket的訪問行為。OSS提供的Bucket訪問日誌不保證記錄下每一條訪問記錄。

Bucket的擁有者可以為bucket開啟訪問日誌記錄功能。這個功能開啟後，OSS將自動記錄訪問這個bucket請求的詳細信息，並按照用戶指定的規則，以小時為單位，將訪問日誌作為一個Object寫入用戶指定的bucket。 OSS提供Bucket訪問日誌的目的是為了方便bucket的擁有者理解和分析bucket的訪問行為。OSS提供的Bucket訪問日誌不保證記錄下每一條訪問記錄。

請求語法

PUT /?logging HTTP/1.1
Date: GMT Date
Content-Length：ContentLength
Content-Type: application/xml
Authorization: SignatureValue 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
    <LoggingEnabled>
        <TargetBucket>TargetBucket</TargetBucket>
        <TargetPrefix>TargetPrefix</TargetPrefix>
    </LoggingEnabled>
</BucketLoggingStatus>

請求元素(Request Elements)

存儲訪問日誌記錄的object命名規則

<TargetPrefix><SourceBucket>-YYYY-mm-DD-HH-MM-SS-UniqueString

命名規則中，TargetPrefix由用戶指定；YYYY, mm, DD, HH, MM和SS分別是該Object被創建時的阿拉伯數字的年，月，日，小時，分鍾和秒（注意位數）；UniqueString為OSS係統生成的字符串。一個實際的用於存儲OSS訪問日誌的Object名稱例子如下：

MyLog-oss-example-2012-09-10-04-00-00-0000

上例中，“MyLog-”是用戶指定的Object前綴；“oss-example”是源bucket的名稱；“2012-09-10-04-00-00”是該Object被創建時的北京時間；“0000” 是OSS係統生成的字符串。

LOG文件格式

細節分析

1. 源Bucket和目標Bucket必須屬於同一個用戶。
2. 上麵所示的請求語法中，“BucketName”表示要開啟訪問日誌記錄的bucket；“TargetBucket”表示訪問日誌記錄要存入的bucket；“TargetPrefix”表示存儲訪問日誌記錄的object名字前綴，可以為空。
3. 源bucket和目標bucket可以是同一個Bucket，也可以是不同的Bucket；用戶也可以將多個的源bucket的LOG都保存在同一個目標bucket內（建議指定不同的TargetPrefix）。
4. 當關閉一個Bucket的訪問日誌記錄功能時，隻要發送一個空的BucketLoggingStatus即可，具體方法可以參考下麵的請求示例。
5. 所有PUT Bucket Logging請求必須帶簽名，即不支持匿名訪問。
6. 如果PUT Bucket Logging請求發起者不是源bucket（請求示例中的BucketName）的擁有者，OSS返回403錯誤碼；
7. 如果源bucket不存在，OSS返回錯誤碼：NoSuchBucket。
8. 如果PUT Bucket Logging請求發起者不是目標bucket（請求示例中的TargetBucket）的擁有者，OSS返回403；如果目標bucket不存在，OSS返回錯誤碼：InvalidTargetBucketForLogging。
9. 源Bucket和目標Bucket必須屬於同一個數據中心，否則返回400錯誤，錯誤碼為：InvalidTargetBucketForLogging。
10. PUT Bucket Logging請求中的XML不合法，返回錯誤碼：MalformedXML。
11. 源bucket和目標bucket可以是同一個Bucket；用戶也可以將不同的源bucket的LOG都保存在同一個目標bucket內（注意要指定不同的TargetPrefix）。
12. 源Bucket被刪除時，對應的Logging規則也將被刪除。
13. OSS以小時為單位生成bucket訪問的Log文件，但並不表示這個小時的所有請求都記錄在這個小時的LOG文件內，也有可能出現在上一個或者下一個LOG文件中。
14. OSS生成的Log文件命名規則中的“UniqueString”僅僅是OSS為其生成的UUID，用於唯一標識該文件。
15. OSS生成一個bucket訪問的Log文件，算作一次PUT操作，並記錄其占用的空間，但不會記錄產生的流量。LOG生成後，用戶可以按照普通的Object來操作這些LOG文件。
16. OSS會忽略掉所有以“x-”開頭的query-string參數，但這個query-string會被記錄在訪問LOG中。如果你想從海量的訪問日誌中，標示一個特殊的請求，可以在URL中添加一個“x-”開頭的query-string參數。如： https://oss-example.oss-cn-hangzhou.aliyuncs.com/aliyun-logo.png https://oss-example.oss-cn-hangzhou.aliyuncs.com/aliyun-logo.png?x-user=admin OSS處理上麵兩個請求，結果是一樣的。但是在訪問LOG中，你可以通過搜索“x-user=admin”，很方便地定位出經過標記的這個請求。
17. OSS的LOG中的任何一個字段，都可能出現“-”，用於表示未知數據或對於當前請求該字段無效。
18. 根據需求，OSS的LOG格式將來會在尾部添加一些字段，請開發者開發Log處理工具時考慮兼容性的問題。
19. 如果用戶上傳了Content-MD5請求頭，OSS會計算body的Content-MD5並檢查一致性，如果不一致，將返回InvalidDigest錯誤碼。

示例

開啟bucket訪問日誌的請求示例：

PUT /?logging HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 186
Date: Fri, 04 May 2012 03:21:12 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
<LoggingEnabled>
<TargetBucket>doc-log</TargetBucket>
<TargetPrefix>MyLog-</TargetPrefix>
</LoggingEnabled>
</BucketLoggingStatus>

返回示例：

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
Date: Fri, 04 May 2012 03:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

關閉bucket訪問日誌的請求示例：

PUT /?logging HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 86
Date: Fri, 04 May 2012 04:21:12 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
</BucketLoggingStatus>

返回示例：

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
Date: Fri, 04 May 2012 04:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

最後更新：2016-11-23 17:16:07

  上一篇： PutBucketACL__關於Bucket的操作_API 參考_對象存儲 OSS-阿裏雲

  下一篇： PutBucketWebsite__關於Bucket的操作_API 參考_對象存儲 OSS-阿裏雲