全部產品
Search
文件中心

Object Storage Service:set-meta(管理檔案中繼資料)

更新時間:Jul 31, 2024

檔案中繼資料是對檔案(Object)的屬性描述,包括HTTP標準屬性(HTTP Header)和使用者自訂中繼資料(User Meta)兩種。其中,HTTP Header可用於自訂HTTP請求的策略,使用者自訂中繼資料可用於標識檔案的用途或屬性等。您可以通過set-meta命令為已上傳的檔案(Object)設定、修改或者刪除檔案中繼資料。

注意事項

  • 要為單個檔案設定中繼資料,您必須具有oss:GetObjectoss:PutObjectoss:GetObjectVersionoss:GetObjectAcl許可權;要批量為檔案設定中繼資料,您必須具有oss:GetObjectoss:PutObjectoss:GetObjectVersionoss:ListObjects許可權。具體操作,請參見為RAM使用者授權自訂的權限原則

  • 從ossutil 1.6.16版本開始,命令列中Binary名稱支援直接使用ossutil,您無需根據系統重新整理Binary名稱。如果您的ossutil版本低於1.6.16,則需要根據系統重新整理Binary名稱。更多資訊,請參見命令列工具ossutil命令參考

  • 通過set-meta命令設定或更新檔案中繼資料後,您可以通過stat命令查看檔案中繼資料。更多資訊,請參見stat

命令格式

ossutil set-meta oss://bucketname[/prefix] 
[header:value#header:value...]
[--update]
[--delete] 
[-r,--recursive] 
[-f, --force]
[--object-file, <value>]
[--snapshot-path, <value>]
[--disable-ignore-error]
[--version <value>]
[--include <value>]
[--exclude <value>]

參數及選項說明如下:

配置項

說明

bucketname

Bucket名稱。

prefix

Bucket下的資源,例如目錄、檔案等。

header:value#header:value...

以索引值對的形式標識中繼資料。其中,Header不區分大小寫,但Value區分大小寫。如果需要設定多組中繼資料,則各組中繼資料之間以井號(#)串連。例如Cache-Control:no-cache#Expires:2022-10-12T00:00:00.000Z

當前可選的Header列表如下:

Headers:
      Expires(time.RFC3339:2006-01-02T15:04:05Z07:00)
      X-Oss-Object-Acl
      Origin
      X-Oss-Storage-Class
      Content-Encoding
      Cache-Control
      Content-Disposition
      Accept-Encoding
      X-Oss-Server-Side-Encryption
      Content-Type
      以及以X-Oss-Meta-開頭的header

關於Header的用法,請參見管理檔案中繼資料

--update

更新檔案中繼資料。該選項可簡寫為-u,且不能與--delete選項同時使用。

--delete

刪除檔案中繼資料。該選項不能與--update選項同時使用。

-r,--recursive

如果指定該選項時,ossutil將為所有與prefix匹配的檔案設定中繼資料。如果不指定該選項,則ossutil只為指定檔案設定中繼資料。

-f, --force

強制操作,不進行詢問提示。

--object-file

該選項用於大量設定、更新或刪除多個Object的中繼資料。使用該選項的步驟如下:

  1. 您需要指定.txt或者XML格式的本地檔案,並在本地檔案中換行填寫所有待設定、更新或刪除中繼資料的Object。

  2. ossutil讀取本地檔案中的所有Object,然後對這些Object進行中繼資料的設定、更新或刪除操作。

說明

當其中一個Object操作出現錯誤時,ossutil會將該Object的錯誤資訊記錄到report檔案,並繼續設定其他Object的中繼資料。成功操作的Object資訊不會被記錄到report檔案中。

--snapshot-path

如果指定該選項,則只對本次操作的Object產生快照。如果操作的Object已經存在快照資訊,則忽略本次操作。

說明

該選項需結合-r,--recursive--object-file選項使用。

--disable-ignore-error

大量操作時不忽略錯誤。

--version-id

Object的指定版本。僅適用於已開啟或暫停版本控制狀態Bucket下的Object。

--include

包含符合指定條件的所有Object。

更多資訊,請參見include和exclude選項

--exclude

不包含任何符合指定條件的Object。

更多資訊,請參見include和exclude選項

設定或更新中繼資料

在以下未包含--update選項的使用樣本中,如果未指定header:value#header:value...選項,則僅保留以X-Oss-Meta-開頭的自訂中繼資料,且不更改其Value值。對於HTTP Header資訊,ossutil將進入互動模式並要求您確認是否繼續保留。

  • 樣本一:為單個Object設定或更新中繼資料

    • 將examplebucket中exampleobject.txt的讀寫權限設定為私人(private)。

      ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:private 
    • 將examplebucket中exampleobject.txt的指定版本儲存類型(X-Oss-Storage-Class)設定為標準儲存(Standard)。

      ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:Standard --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
    • 將examplebucket中exampleobject.txt的指定版本儲存類型(X-Oss-Storage-Class)設定為冷Archive Storage(ColdArchive)。

      ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:ColdArchive --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
      說明

      set-meta執行期間,儲存類型不會變化。執行完成後,儲存類型才會變化。

      有關擷取Object版本的具體操作,請參見ls

    • 將examplebucket中exampleobject.txt的讀寫權限ACL更新為公用讀取(public-read)。

      ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:public-read --update

      使用--update選項時僅更新目標Object中與指定Header匹配的中繼資料,並替換為該Header對應的Value值,其中Value值可以為空白。Value置空時,表示保留原有的Value資訊。例如,該樣本表示僅將名為exampleobject.txt的Object的讀寫權限更新為public-read,Object的其他中繼資料保留不變。

  • 樣本二:為相同目錄下的多個Object大量設定或更新中繼資料

    為多個Object同時設定或修改中繼資料時,如果其中一個Object操作出現錯誤,ossutil會將該Object的錯誤資訊記錄到ossutil_output目錄下的report檔案中。成功操作的Object資訊不會記錄到該report檔案。

    • 為與指定首碼匹配的Object設定中繼資料

      結合-r選項,將examplebucket中與指定首碼src匹配的所有Object的緩衝行為(Cache-Control)修改為no-cache(不直接使用緩衝),讀寫權限(x-oss-object-acl)修改為private(私人)。

      ossutil set-meta oss://examplebucket/src Cache-Control:no-cache#X-Oss-Object-Acl:private -r                             
    • 為與指定過濾條件匹配的Object修改中繼資料

      • 結合-r-u選項,將examplebucket中目錄desfolder下所有檔案類型為.jpg的Object的儲存類型修改為低頻訪問類型(IA)。

        ossutil set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:IA --include "*.jpg" -u -r                                        
      • 結合-r-u選項,將examplebucket中目錄desfolder下檔案名稱包含abc且檔案類型不為.jpg.txt的Object的儲存類型修改為Archive Storage(Archive)。

        ossutil set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:Archive --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -u -r
      重要

      通過set-meta命令對大於100 MB的冷歸檔或者深度冷Archive Storage類型Object進行儲存類型轉換時,可能會出現因伺服器逾時導致轉換操作失敗的問題。因此,當您需要對大於100 MB的冷歸檔或者深度冷Archive Storage類型Object進行儲存類型轉換時,請使用cp命令。

  • 樣本三:為相同或不同目錄下的多個Object設定或更新中繼資料

    • 不同目錄下

      當您需要為Bucket中的多個Object設定或更新中繼資料,這些Object歸屬於Bucket的不同目錄下,例如exampleobject1.jpg位於examplebucket根目錄下,exampleobject2.png位於examplebucket的dir1/目錄下,exampleobject3.txt位於examplebucket的dir2/目錄下。此時,您需要按照以下步驟設定或更新多個Object的中繼資料。

      1. 將待設定或更新中繼資料的多個Object寫入本地檔案localfile.txt。

        exampleobject1.jpg
        dir1/exampleobject2.png
        dir2/exampleobject3.txt
      2. 為多個指定Object設定或更新中繼資料。

        結合--object-file選項將examplebucket中多個Object的緩衝行為(Cache-Control)修改為no-cache(不直接使用緩衝),讀寫權限(x-oss-object-acl)修改為private(私人),並開啟快照。

        ossutil set-meta oss://examplebucket Cache-Control:no-cache#X-Oss-Object-Acl:private --update --object-file localfile.txt --snapshot-path dir/
    • 相同目錄下

      • 方法一

        參考不同目錄下的操作樣本為相同目錄下的多個Object設定或更新中繼資料。

      • 方法二:

        參考樣本二為相同目錄下的多個Object設定或更新中繼資料。

  • 返回結果

    以上操作成功後,返回結果中將包含設定或更新檔案中繼資料所用時間長度,樣本如下:

    0.106852(s) elapsed

刪除自訂中繼資料

重要

結合--delete選項僅支援刪除以X-Oss-Meta-開頭的自訂中繼資料。

  • 樣本一:刪除單個Object的自訂中繼資料

    刪除examplebucket中exampleobject.txt包含的以X-Oss-Meta-開頭的自訂中繼資料,其中Value值必須為空白。

    ossutil set-meta oss://examplebucket/exampleobject.txt X-Oss-Meta-Createdby  --delete
  • 樣本二:大量刪除多個Object的自訂中繼資料

    大量刪除多個Object的自訂中繼資料步驟如下:

    1. 將待刪除自訂中繼資料的Object名稱寫入本地檔案localfile.txt。

      exampleobject1.jpg
      dir1/exampleobject2.png
      dir2/exampleobject3.txt
    2. 刪除多個Object的自訂中繼資料。

      結合--object-file選項大量刪除examplebucket中多個Object包含的以X-Oss-Meta-開頭的自訂中繼資料,其中Value值必須為空白。

      ossutil set-meta oss://examplebucket X-Oss-Meta-Location --delete --object-file localfile.txt --snapshot-path dir/
  • 返回結果

    以上操作成功後,返回結果中將包含刪除自訂中繼資料所用時間長度,樣本如下:

    0.106846(s) elapsed

通用選項

當您需要通過命令列工具ossutil切換至另一個地區的Bucket時,可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令列工具ossutil切換至另一個阿里雲帳號下的Bucket時,可以通過-i選項指定該帳號的AccessKey ID,並通過-k選項指定該帳號的AccessKey Secret。

例如您需要為另一個阿里雲帳號下,華東2(上海)地區下目標儲存空間testbucket下的testobject.jpg檔案設定讀寫權限ACL為private的中繼資料,命令如下:

ossutil set-meta oss://testbucket/testobject.jpg X-Oss-Object-Acl:private  -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

關於此命令的其他通用選項的更多資訊,請參見通用選項