SetObjectMeta--对象存储-火山引擎

文档中心

导航

对象存储

SetObjectMeta

最近更新时间：2025.04.22 16:13:54首次发布时间：2021.10.13 16:14:08

此接口用于更新已经上传对象的元数据信息。TOS 支持携带以下 6 个请求头来修改对象元数据，在下载对象或者 HEAD 对象时，这些值会设置到 HTTP 头域中返回给客户端。支持的 6 个头域：Cache-Control、Content-Disposition、Content-Encoding、Expires、Content-Type、Content-Language。
该接口会完整替换对象元数据，未在请求中指定的元数据会被删除。

注意事项

使用 SetObjectMeta 接口更新归档存储、冷归档存储和深度冷归档存储对象的元数据前，需要先恢复对象。

请求消息样式

POST /ObjectName?metadata HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: GMT Date
Authorization: authorization string
<Optional Additional Header>

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
metadata	Query	String	是	-	代表 SetObjectMeta 请求的特殊标识。
versionId	Query	String	否	57AF1A32CECB56721267	对象的版本号。标识更改指定版本的对象自定义元数据。
Content-Type	Header	String	否	text/plain	对象类型。
Cache-Control	Header	String	否	no-cache, no-store, must-revalidate	指定该对象被下载时网页的缓存行为。
Expires	Header	String	否	Mon, 04 Jul 2022 02:57:31 GMT	RFC2616 中定义的缓存失效时间。
Content-Disposition	Header	String	否	attachment; filename=123.txt	对象被下载时的名称。
Content-Encoding	Header	String	否	gzip	对象被下载时的内容编码类型。
Content-Language	Header	String	否	en-US	对象被下载时的内容语言格式。
x-tos-meta-*	Header	String	否	x-tos-meta-key: value	创建对象时，可以在 HTTP 请求中加入以 x-tos-meta-开头的消息头，用来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回消息的头中出现。
x-tos-object-expires	Header	String	否	3	为对象添加过期时间，或修改对象的过期时间，过期后，TOS 将自动删除对象。单位为天，取值说明如下：设置为正整数：对象将在指定时间过期，从对象的 Last‑Modified 时间开始计算，在到达该过期时间后的零点开始执行删除任务，例如设置 `x-tos-object-expires` 参数的值为 `3`，对象的 Last‑Modified 时间为 2024-09-26 12:00，则该对象将于 2024-09-30 00:00 过期。不设置该参数，设置为 0 或空值：永不过期，对象将持续保留在存储桶中，直至您手动删除该对象，或者配置生命周期规则将其删除。您可以通过设置该参数的值为 0 或留空的方式，使指定时间过期的对象变为永不过期。说明软链接对象不支持设置过期时间。对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。

请求元素

该请求中无请求消息元素。

响应消息头

该请求返回公共响应消息头，请参见公共参数。

响应元素

该请求响应中无消息元素。

请求示例 1

给对象添加元数据Content-Type: application/x-www-form-urlencoded 和 x-tos-meta-test: meta-test。

POST /ObjectName?metadata HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string
Content-Type: application/x-www-form-urlencoded
x-tos-meta-test: meta-test

响应示例 1

HTTP/1.1 200 OK
x-tos-id-2: f91b0c03a01300c1-a444ed0
x-tos-request-id: f91b0c03a01300c1-a444ed0
Date: Fri, 30 Jul 2021 08:05:36 GMT
server: TosServer
Content-Length: 0

请求示例 2

修改对象元数据，已经存在Content-Type: application/x-www-form-urlencoded和x-tos-meta-test: meta_test，修改为x-tos-meta-test: meta_modify。

POST /ObjectName?metadata HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string
Content-Type: application/x-www-form-urlencoded
x-tos-meta-test: meta_modify

响应示例 2

HTTP/1.1 200 OK
x-tos-id-2: 92ab6a0bb2ff0006-a444ed0
x-tos-request-id: 92ab6a0bb2ff0006-a444ed0
Date: Fri, 30 Jul 2021 08:05:36 GMT
server: TosServer
Content-Length: 0