set-meta(管理文件元数据)

文件元数据是对文件(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)设置为冷归档存储(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/
    • 相同目录下

  • 返回结果

    以上操作成功后,返回结果中将包含设置或更新文件元数据所用时长,示例如下:

    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****

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