文件元信息是对文件(Object)的属性描述,包括HTTP标准属性(HTTP Header)和用户自定义元数据(User Meta)两种。其中,HTTP Header可用于自定义HTTP请求的策略,用户自定义元数据可用于标识文件的用途或属性等。您可以通过set-meta命令为已上传的文件(Object)设置、修改或者删除文件元信息。

说明
  • 本文各命令行示例均基于Linux 64位系统,其他系统请将命令开头的./ossutil64替换成对应的Binary名称。详情请参见命令行工具ossutil快速入门
  • 通过set-meta命令设置或更新文件元信息后,您可以通过stat命令查看文件元信息。更多信息,请参见stat

命令格式

./ossutil64 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。
--exclude 不包含任何符合指定条件的Object。

设置或更新元信息

在以下未包含--update选项的使用示例中,如果未指定header:value#header:value...选项,则仅保留以X-Oss-Meta-开头的自定义元信息,且不更改其Value值。对于HTTP Header信息,ossutil将进入交互模式并要求您确认是否继续保留。

  • 示例一:为单个Object设置或更新元信息

    • 将examplebucket中exampleobject.txt的读写权限设置为私有(private)。
      ./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Object-Acl:private 
    • 将examplebucket中exampleobject.txt的指定版本存储类型(X-Oss-Storage-Class)设置为标准存储(Standard)。
      ./ossutil64 set-meta oss://examplebucket/exampleobject.txt X-Oss-Storage-Class:Standard --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

      有关获取Object版本的具体操作,请参见ls

    • 将examplebucket中exampleobject.txt的读写权限ACL更新为公共读(public-read)。
      ./ossutil64 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(私有)。

      ./ossutil64 set-meta oss://examplebucket/src Cache-Control:no-cache#X-Oss-Object-Acl:private -r                             
    • 为与指定过滤条件匹配的Object修改元信息
      • 结合-r-u选项,将examplebucket中目录desfolder下所有文件类型为.jpg的Object的存储类型修改为低频访问类型(IA)。
        ./ossutil64 set-meta oss://examplebucket/desfolder/ X-Oss-Storage-Class:IA --include "*.jpg" -u -r                                        
      • 结合-r-u选项,将examplebucket中目录desfolder下文件名包含abc且文件类型不为.jpg.txt的Object的存储类型修改为归档存储(Archive)。
        ./ossutil64 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(私有),并开启快照。

        ./ossutil64 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值必须为空。

    ./ossutil64 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值必须为空。

      ./ossutil64 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的元信息,命令如下:
./ossutil64 set-meta oss://testbucket/testobject.jpg X-Oss-Object-Acl:private  -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

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