对象存储 OSS：set-meta（管理文件元数据）

注意事项

• 要为单个文件设置元数据，您必须具有oss:GetObject、oss:PutObject、oss:GetObjectVersion和oss:GetObjectAcl权限；要批量为文件设置元数据，您必须具有oss:GetObject、oss:PutObject、oss:GetObjectVersion和oss: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>]

参数及选项说明如下：

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

设置或更新元数据

在以下未包含--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）设置为冷归档存储（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）。

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

    重要

    通过set-meta命令对大于100 MB的冷归档或者深度冷归档存储类型Object进行存储类型转换时，可能会出现因服务器超时导致转换操作失败的问题。因此，当您需要对大于100 MB的冷归档或者深度冷归档存储类型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

删除自定义元数据

• 示例一：删除单个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。

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

关于此命令的其他通用选项的更多信息，请参见通用选项。