此页面由 Cloud Translation API 翻译。

XML API 的 HTTP 标头和查询字符串参数

Cloud Storage XML API 使用多个标准 HTTP 标头以及几个扩展（自定义）HTTP 标头。多种 HTTP 方法也支持查询字符串参数。下文介绍了标头和参数。

HTTP 标头和查询字符串参数摘要

XML API 使用以下标准 HTTP 标头：

请求	响应	两者皆有
授权内容 - MD5 主机 If-Match If-Modified-Since If-None-Match If-Unmodified-Since	ETag Last-Modified 位置	缓存控制内容-处置内容编码内容-语言内容长度内容范围内容类型日期范围传输编码

XML API 使用以下扩展程序（自定义）HTTP 标头：

请求	响应	两者皆有
X-goog-acl x-goog-api-version x-goog-bucket-retention-period x-goog-content-length-range x-goog-content-sha256 x-goog-copy-source x-goog-copy-source-generation x-goog-copy-source-if-generation-match x-goog-copy-source-if-match x-goog-copy-source-if-metageneration-match x-goog-copy-source-if-modified-since x-goog-copy-source-if-none-match x-goog-copy-source-if-unmodified-since x-goog-date x-goog-encryption-key x-goog-encryption-kms-key-name x-goog-if-generation-match x-goog-if-metageneration-match x-goog-metadata-directive x-goog-project-id x-goog-resumable x-goog-user-project	x-goog-component-count x-goog-expiration x-goog-generation x-goog-metageneration x-goog-stored-content-encoding x-goog-stored-content-length	x-goog-custom-time x-goog-encryption-algorithm x-goog-encryption-key-sha256 x-goog-hash x-goog-meta- x-goog-storage-class

XML API 使用以下查询字符串参数：

访问密钥 ID
Acl
动作
帐单
撰写
Cors
defaultObjectAcl
分隔符
编码类型
加密
encryptionConfig
世代
生成标记

生命周期位置
日志记录
标记
标记
最大键数
项目项数量上限
前缀
response-content-disposition
响应-内容类型
状态
storageClass
标记

upload_id [上传 ID]
用户名
userProject 类的构造函数
版本控制
版本
网站配置
X-Goog 算法
X-Goog-Credential
X-Goog-Date
X-Goog-Expires
X-Goog-SignedHeaders
X-Goog-Signature

标准 HTTP 标头

授权

包含用于验证请求的字符串的字符串。

有效值	身份验证标识符 ( `Bearer` \| `GOOG1` \| `AWS`)，后跟以下内容之一：有效的 OAuth 2.0 令牌访问密钥签名
示例	`Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s- ...`
详细信息	如需详细了解如何使用此标头，请参阅身份验证。注意：如果您的请求是通过代理路由的，您可能需要与网络管理员联系，以确保包含凭据的 `Authorization` 标头为不会被代理删除。如果没有 `Authorization` 标头，您会收到 `MissingSecurityHeader` 错误，请求将被拒绝。如需详细了解如何通过代理服务器访问 Cloud Storage，请参阅问题排查主题。

Cache-Control

用于指定缓存控制设置的请求和响应标头。

有效值	任何有效的缓存控制值（请参阅规范）。
示例	`Cache-Control: public, max-age=6000`
详细信息	您应仅为所有匿名用户可访问的对象指定缓存控制。如需匿名访问，对象的 ACL 必须向 `AllUsers` 授予 `READ` 或 `FULL_CONTROL` 权限。如果某个对象对所有匿名用户均可访问，而您未指定缓存控制设置，则 Cloud Storage 会应用 3600 秒的缓存控制设置。通过 XML 传送时，Cloud Storage 会遵循对象的元数据设置中的缓存控制。

Content-Disposition

请求和响应标头，用于指定有关正在传输的数据的表示信息。

有效值	任何有效的内容处置值（请参阅规范）。
示例	`Content-Disposition: attachment; filename=FILENAME`
详细信息	如果您在上传对象时设置 Content-Disposition 标头，那么该网址将在下载时提供（并随后由网络浏览器和其他 HTTP 客户端解读）。Content-Disposition 的常见用途是将其设置为 `attachment;filename=FILENAMEt`，这通常使网络浏览器打开“另存为...”对话框。

Content-Encoding

用于指定对象的压缩算法的请求和响应标头。

有效值	任何有效的压缩算法（请参阅规范）。
示例	`Content-Encoding: gzip`
详细信息	Cloud Storage 不会压缩或解压缩对象。如果您使用此标头指定压缩类型算法（例如 `deflate`），则 Cloud Storage 将保留标头，但不会压缩或解压缩对象。

Content-Language

内容的 ISO 639-1 语言代码。

有效值	如需语言代码列表，请参阅语言名称代码代码的 ISO 639-1 列。
示例	`Content-Language: en`

内容长度

请求或响应正文的长度（以字节为单位）。

有效值	任何大于或等于 0 的值。
示例	`Content-Length: 1234`
详细信息	所有请求使用分块传输编码的请求除外（请参阅规范）。如果您不使用分块传输编码，并且请求中不包含 `Content-Length` 标头，则请求将失败，并且 Cloud Storage 将会返回 411 长度要求状态代码。

内容 - MD5

请求正文的 MD5 摘要。

有效值	有效的 MD5 摘要。
示例	`Content-MD5: iB94gawbwUSiZy5FuruIOQ==`
详细信息	请参阅规范。 Cloud Storage 可以使用它来检查 `PUT` 操作的完整性。

内容范围

指定字节范围的请求或响应标头。

有效值任何有效的字节范围。

示例 Content-Range: bytes 456-987/1234

详细信息

当响应在响应中时，Content-Range 标头表示因包含 Range 标头的请求而导致返回的字节数范围。

作为可续传上传请求的一部分使用时，Content-Range 可用于查询上传内容的当前位置，或作为起点作为起点在当前请求中上传的数据块。

字节范围（含）；也就是说，bytes 0-999 表示文件或对象中的前 1000 个字节。

如需了解更多详情，尤其是下载响应，请参阅规范。

Content-Type

请求或响应的 MIME 类型。

有效值	任何有效的 MIME 类型（请参阅规范）。
示例	`Content-Type: text/html`
详细信息	如果您在上传对象时未指定内容类型，则 Cloud Storage 系统会在传送对象时默认为 `application/octet-stream`。

日期

请求或响应的日期和时间。

有效值	以传统 HTTP 格式表示的日期和时间（请参阅规范）。
示例	`Date: Wed, 16 Jun 2010 11:11:11 GMT`
详细信息	用于创建签名网址使用 V2 签名流程，此格式应采用传统 HTTP 格式；请参阅规范的 7.1.2 节中下载 Google 健身应用。使用 V4 签名流程时，应采用 ISO 8601 基本格式 `YYYYMMDD'T'HHMMSS'Z'`。

ETag

包含正在访问的对象的实体标记的响应标头。

有效值	用引号引起来的字符串。如需了解详情，请参阅哈希和 ETag：最佳做法。
示例	`ETag: "39a59594290b0f9a30662a56d695b71d"` `ETag: "-CKicn4fknbUCEAE="`
详细信息	请参阅规范。

主机

用于指定 Cloud Storage 的 URI 的请求标头。

有效值	URI 的有效格式。
示例	`Host: storage.googleapis.com`
详细信息	如需详细了解有效 URI，请参阅请求端点和主机规范。

If-Match

用于指定实体标记 (ETag) 的请求标头。

有效值	有效的实体标记。
示例	`If-Match: "881f7881ac1bc144a2672e45babb8839"`
详细信息	只能指定一个实体标记（不用英文逗号分隔实体标记列表）。您可以将此标头与 HEAD Object 和 GET Object 方法一起使用。如果您使用此标头指定的 ETag 与对象的 ETag 相同，则返回元数据或对象。如果您使用此标头指定的 ETag 与对象的 ETag 不同，则系统不会返回元数据或对象，并且 Cloud Storage 会返回一个412 前提条件失败错误代码。有关详情，请参阅规范。

If-Modified-Since

用于指定日期和时间的请求标头。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`If-Modified-Since: Fri, 19 Feb 2010 22:04:23 GMT`
详细信息	您可以将此标头与 HEAD 对象和 GET 对象方法结合使用。如果修改对象的时间晚于此标头指定的日期和时间，系统将返回元数据或对象。如果某个对象的修改时间早于您使用此标头指定的日期和时间，则不会返回元数据或对象，并且 Cloud Storage 会返回 304 Not Modified状态代码。如需详细了解 If-Modified-Since 标头，请参阅规范。如需详细了解 HTTP 日期格式，请参阅规范第 7.1.1.2 节。

If-None-Match

用于指定实体标记 (ETag) 的请求标头。

有效值	有效的实体标记。
示例	`If-None-Match: "881f7881ac1bc144a2672e45babb8839"`
详细信息	您可以将此标头与 HEAD 对象和 GET 对象方法结合使用。如果您使用此标头指定的 ETag 与对象的 ETag 不同，则返回元数据或对象。如果您使用此标头指定的 ETag 与对象的 ETag 相同，则不会返回元数据或对象，并且 Cloud Storage 会返回 304 Not Modified 状态代码。有关详情，请参阅规范。

If-Unmodified-Since

用于指定日期和时间的请求标头。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`If-Unmodified-Since: Fri, 19 Feb 2010 22:04:23 GMT`
详细信息	您可以将此标头与 HEAD 对象和 GET 对象方法结合使用。如果对象的修改时间晚于您使用此标题指定的日期，则系统会返回元数据或对象。如果该对象的修改时间晚于此标头指定的日期，则不会返回元数据或对象，并且 Cloud Storage 会返回一个412 前提条件失败错误代码。如需详细了解 If-Unmodified-Since 标头，请参阅规范。如需详细了解 HTTP 日期格式，请参阅规范第 7.1.1.2 节。

上次修改时间

包含对象上次修改日期和时间的响应标头。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`Last-Modified: Fri, 19 Feb 2010 22:04:23 GMT`
详细信息	如需详细了解 Last-Modified 标头，请参阅规范。如需详细了解 HTTP 日期格式，请参阅规范第 7.1.1.2 节。

位置

响应标头有多种用途：

为启动可续传上传，系统会为您提供可续传上传的会话 URI。
为响应基于 Cookie 的身份验证请求，它将为您提供请求的唯一 Web 来源响应网址。
针对位于 www.googleapis.com/download 之外的网址发出的 JSON API 下载请求，提供可进行下载的 JSON API 网址的重定向。

有效值	任何有效的 URI。
示例	`Location: https://example.storage.googleapis.com/?upload_id=tvA0...rot`
详细信息	启动可续传上传时，系统会返回 `Location` 响应标头。

范围

一个请求标头，用于指示您要返回的字节数范围，以及一个标头，用于指示已上传到 Cloud Storage 系统的字节数范围。

有效值任何连续的字节数范围。

示例 Range: bytes=0-1999（前 2000 个字节）
Range: bytes=-2000（最后 2000 个字节）
Range: bytes=2000-（从 2000 到文件结尾）

详细信息

在对象数据请求中作为标头加入时，系统只会返回该对象的指定字节范围，这在恢复中断的上传时非常有用。有效且成功的请求会导致 206 Partial Content 响应代码。请注意，在某些情况下，range 请求标头会被忽略。

当作为与可续传上传关联的响应返回时，Range 表示当前上传的字节数。您后续可以使用此信息来继续上传。

字节范围包含边界值。例如，bytes=0-999 表示文件或对象中的前 1000 个字节。如需详细了解此标头，请参阅规范。

传输编码

请求和响应标头，用于指定是否已将传输编码应用于邮件正文。

有效值	`chunked`
示例	`Transfer-Encoding: chunked`
详细信息	此标头指定请求或响应的消息正文是否已分块。如果该值为 true，则服务器为一系列数据块提供内容，最后一段数据块长度为零。如果您指定了 `Transfer-Encoding: Chunked`，则无需指定 `Content-Length`。如果您事先不知道消息正文的长度（例如进行流式上传时），这样做会很有用。如需详细了解 Transfer-Encodings，请参阅规范。如需详细了解分块传输编码，请参阅规范。

扩展（自定义）HTTP 标头

X-goog-acl

在您上传或创建 ACL（预设）ACL 时，将向存储分区中应用预定义（预设）ACL 的请求标头。

有效值	对于存储分区：`project-private`、`private`、`public-read`、`public-read-write`、`authenticated-read` 对于对象：`project-private`、`private`、`bucket-owner-read`、`bucket-owner-full-control`、`public-read`、`authenticated-read`
示例	`x-goog-acl: private`
详细信息	如果用户在未指定对象的情况下创建对象或创建存储分区，系统会应用 `private` ACL。如需详细了解预定义 ACL，请参阅访问权限控制。

x-goog-api-version

此标头已弃用，未使用。

x-goog-bucket-retention-period

向新存储分区添加保留政策的请求标头。

有效值	介于 1 到 1355,760,000 之间的整数。
示例	`x-goog-bucket-retention-period: 32000`
详细信息	此请求标头只能在创建新存储分区时使用。包含此标头后，新存储分区会获得一项解锁的保留政策，其时长（以秒为单位）取决于此标头的值（以秒为单位）。

x-goog-component-count

响应标头，指示构成复合对象的组件数量。

有效值	大于或等于 1 的整数。
示例	`x-goog-component-count: 32`
详细信息	仅在访问的对象是复合对象时，才会返回此响应标头。标头返回构成对象的组件数量。

x-goog-content-length-range

PUT 请求标头。使用此标志时，仅当请求的内容大小超出标头指定范围时，Cloud Storage 才会接受请求。

有效值	一个 `MIN,MAX` 对
示例	`x-goog-content-length-range: 0,256`
详细信息	内容大小的值包括值和值（以字节为单位）。如果请求的内容的大小符合指定范围，则系统会根据需要传送内容。如果请求的内容的大小超出指定范围，则请求会失败并返回响应中的 `400 Bad Request` 代码。如果在 `PUT` 以外的请求中使用 `x-goog-content-length-range`，则以静默方式忽略标头。

x-goog-content-sha256

包含请求正文的哈希值的请求标头。

有效值	小写十六进制编码、SHA-256 哈希或 `UNSIGNED-PAYLOAD`
示例	`x-goog-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`
详细信息	对于使用 Authorization 标头中的 signature 的请求，必须提供此标头。 `x-goog-content-sha256` 必须与您在规范化请求的负载部分中使用的值一致。

x-goog-copy-source

用于指定复制操作源存储分区和对象的请求标头。

有效值 /BUCKET_NAME/OBJECT_NAME 路径

示例 x-goog-copy-source: travel-maps/paris.jpg

详细信息

此请求标头指定源对象的路径。有效路径必须包含存储分区和对象（用斜杠 (/) 分隔）。请注意，源对象路径必须是法定网址，因此通常应为百分号编码。

您必须对源对象具有 READ 权限，并且对目标存储分区至少具有 WRITE 权限，才能使用此标头。

如果源对象和目标对象相同（包括世代），则副本将被视为元数据更新。要详细了解如何控制更新/替换行为，请参阅 x-goog-metadata-directive。

x-goog-copy-source-generation

用于指定要复制的对象的生成的请求标头。

有效值	任何正数（64 位）
示例	`x-goog-copy-source-generation: 1360044097839000`
详细信息	此请求标头可与 x-goog-copy-source 搭配使用，用于指定要从中复制对象的生成。如果没有 x-goog-copy-source 标头，该标头无效。如果源对象没有如此生成，Cloud Storage 将返回 404 Not Found 状态代码。如果源对象和目标对象相同（包括世代），则副本将被视为元数据更新。如需详细了解控制更新/替换行为，请参阅 x-goog-metadata-directive。

x-goog-copy-source-if-generation-match

仅当源对象 x-goog-generation 与指定值匹配时，系统才会执行指定相应复制请求的请求标头。此标头仅在与 x-goog-copy-source 配合使用时有效。

有效值	任何正数（64 位）
示例	`x-goog-copy-source-if-generation-match: 1360044097835000`
详细信息	仅当包含指定的世代时，此请求标头才可用于有条件地复制源对象。如果世代不匹配，Cloud Storage 将返回 412 Precondition Failed 错误代码。如需了解详情，请参阅使用对象版本。

x-goog-copy-source-if-match

用于指定复制操作条件的请求标头。

有效值	实体标记 (ETag)
示例	`x-goog-copy-source-if-match: 53fc311c15eda0a031809982ccf92aac`
详细信息	您只能指定一个实体标记（不用英文逗号分隔的实体标记列表）。只有在您使用 `x-goog-copy-source` 请求标头执行复制操作时，才能使用此请求标头。如果您使用此请求标头指定的 ETag 与源对象的 ETag 匹配，则复制操作会继续进行。如果 ETag 不匹配，Cloud Storage 将返回 412 Precondition Failed 错误代码。

x-goog-copy-source-if-metageneration-match

仅当源对象的 metageneration 与该标头的值匹配时，才允许使用指定相应请求的请求标头。

有效值任何正数（64 位）

示例 x-goog-copy-source-if-metageneration-match: 4

详细信息

如果源对象元数据世代与 x-goog-copy-source-if-metageneration-match 标头匹配，则请求将成功完成，Google Cloud Storage 将返回 HTTP 200 OK 状态。如果元数据世代不匹配，Cloud Storage 将返回 412 Precondition Failed 错误代码。

此值只能与 x-goog-copy-source-if-generation-match 或 x-goog-copy-source-generation 一起使用试图使用该方法，那么即便缺少这两种代码，都会导致 HTTP 400 BadRequest 参数的错误代码无效。

如需了解详情，请参阅使用对象版本。

x-goog-copy-source-if-modified-since

用于指定复制操作条件的请求标头。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`x-goog-copy-source-if-modified-since: Fri, 19 Feb 2010 14:05:04 GMT`
详细信息	只有在使用 `x-goog-copy-source` 请求标头执行复制操作时，此请求标头才会使用。如果您指定的日期和时间早于源对象的 `Last-Modified` 日期，则系统会复制该对象。如果日期和时间晚于，则 Cloud Storage 会返回一个 412 Precondition Failed 错误代码。如需详细了解 If-Modified-Since HTTP 标头（除复制源以外，它适用于此使用场景），请参阅规范。如需详细了解 HTTP 日期格式，请参阅规范第 7.1.1.2 节

x-goog-copy-source-if-none-match

用于指定复制操作条件的请求标头。

有效值	实体标记 (ETag)
示例	`x-goog-copy-source-if-none-match: 53fc311c15eda0a031809982ccf92aac`
详细信息	只有在使用 `x-goog-copy-source` 请求标头执行复制操作时，此请求标头才会使用。如果您使用此请求标头指定的 ETag 与源对象的 ETag 不匹配，则复制操作会继续进行。如果 ETag 匹配，Cloud Storage 将返回 412 Precondition Failed 错误代码。如需详细了解 If-None-Match HTTP 标头（除复制源以外，该用例适用于此用例），请参阅规范。

x-goog-copy-source-if-unmodified-since

用于指定复制操作条件的请求标头。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`x-goog-copy-source-if-unmodified-since: Fri, 19 Feb 2010 14:05:04 GMT`
详细信息	只有在使用 `x-goog-copy-source` 请求标头执行复制操作时，此请求标头才会使用。如果您指定的日期和时间晚于源对象的 `Last-Modified` 日期，则系统会复制该对象。如果日期和时间早于先前时间，Cloud Storage 将返回 412 Precondition Failed 错误代码。如需详细了解 If-Unmodified-Since HTTP 标头（除复制源以外，它适用于此用例），请参阅规范。如需详细了解 HTTP 日期格式，请参阅规范第 7.1.1.2 节。

x-goog-custom-time

自定义时间戳对象元数据的请求和响应标头。

有效值	采用 RFC 3339 格式表示的日期和时间。
示例	`x-goog-custom-time: 2020-04-12T23:20:50.52Z`
详细信息	您可以在对象 PUT 或 POST 请求期间添加此标头。您在标题中指定的值会随对象一起存储，当您对对象发出 GET 或 HEAD 请求时，响应标头中会返回响应。对象的自定义时间通常与对象生命周期管理结合使用。

x-goog-date

用于指定经过身份验证的请求时间戳的请求标头。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`x-goog-date: Fri, 19 Feb 2010 14:05:04 GMT`
详细信息	用于创建签名网址使用 V2 签名流程，此格式应采用传统 HTTP 格式；请参阅规范的 7.1.2 节中下载 Google 健身应用。使用 V4 签名流程时，应采用 ISO 8601 基本格式 `YYYYMMDD'T'HHMMSS'Z'`。

x-goog-encryption-algorithm

用于指定需使用的加密算法的请求和响应标头。

有效值	`AES256`
示例	`x-goog-encryption-algorithm: AES256`
详细信息	系统会在您提供客户提供的加密密钥时使用此请求和响应标头。

x-goog-encryption-key

用于指定 AES-256 加密密钥的请求标头。

有效值	有效的 AES-256 加密密钥的 RFC 4648 Base64 编码字符串
示例	`x-goog-encryption-key: NwbyGGmcKAX4FxGpOERG2Ap33m5NVOgmXznSGTEvG0I=`
详细信息	系统会在您提供客户提供的加密密钥时使用此请求标头。

x-goog-encryption-key-sha256

用于指定加密密钥的 SHA256 哈希值的请求和响应标头。

有效值	用于加密密钥的 SHA256 哈希值的 RFC 4648 Base64 编码字符串
示例	`x-goog-encryption-key-sha256: +eBzkZBt1Mj2CZx69L3c8yXoZB6DtRLlSvXMJB9JGIQ=`
详细信息	系统会在您提供客户提供的加密密钥时使用此请求标头。

x-goog-encryption-kms-key-name

用于指定 Cloud KMS 加密密钥的请求标头。

有效值	Cloud KMS 加密密钥资源。
示例	`x-goog-encryption-kms-key-name: projects/my-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key`
详细信息	如果您想要通过客户管理的加密密钥对特定对象进行加密，则可以使用此请求标头。

x-goog-expiration

响应标头，用于根据生命周期配置指定何时访问所访问对象的时间。

有效值	以传统 HTTP 格式表示的日期和时间。
示例	`x-goog-expiration: Tue, 25 June 2013 00:00:00 GMT`
详细信息	对于满足启用了生命周期管理的存储分区中的对象，系统仅返回此响应标头。如需了解详情，请参阅对象生命周期行为。

x-goog-generation

一个响应标头，用于指示您正在访问的对象数据版本。

有效值	任何正数（64 位）
示例	`x-goog-generation: 1360044097835000`
详细信息	每当创建或替换对象时，Cloud Storage 都会自动为该对象分配一个世代。每当替换对象数据时，世代都会发生变化。但是，不同对象世代之间没有已定义的关系。如需了解详情，请参阅使用对象版本。

x-goog-if-generation-match

仅当对象的 x-goog-generation 与该标头的值匹配时，才允许使用用于指定相应请求的请求标头。

有效值零个或任意正数（64 位值）

示例 x-goog-if-generation-match: 1360044097835000

详细信息

如果对象世代与 x-goog-if-generation-match 标头匹配，则请求将成功完成，Google Cloud Storage 将返回 HTTP 200 OK 状态。如果世代不匹配，Google Cloud Storage 将返回 HTTP 412 Precondition Failed 错误代码。

如果将 x-goog-if-generation-match 标头设置为 0，则只有在对象当前不存在时，Google Cloud Storage 才会执行指定的请求。例如，您可以执行 PUT 请求以使用 x-goog-if-generation-match 创建新对象，并且仅当对象尚不存在当前版本时才会创建该对象。如果该对象已存在，请求将被中止。

如需了解详情，请参阅使用对象版本。

x-goog-if-metageneration-match

仅当对象的 x-goog-metageneration 与该标头的值匹配时，才允许使用用于指定相应请求的请求标头。

有效值任何正数（64 位）

示例 x-goog-if-metageneration-match: 4

详细信息

如果对象元数据世代与 x-goog-if-metageneration-match 标头匹配，则请求将成功完成，Google Cloud Storage 将返回 HTTP 200 OK 状态。如果 metageneration 不匹配，Cloud Storage 将返回 HTTP 412 Precondition Failed 错误代码。

此请求标头只能与 x-goog-if-generation-match 标头搭配使用，以确保对您所生成对象的更新确实会对元数据进行更新因此，您可以安全地执行读取-修改-写入操作。

如需了解详情，请参阅使用对象版本。

x-goog-metadata-directive

指定复制操作期间元数据处理的请求标头。

请注意，如果存在，则永远不会复制对象 ACL（如果存在）。如果适用，新对象会收到 x-goog-acl 请求标头中指定的 ACL 或为包含新对象的存储分区设置的默认对象 ACL。

有效值 COPY | REPLACE

示例 x-goog-metadata-directive: REPLACE

详细信息

仅与 x-goog-copy-source 请求标头一起使用。默认值为 COPY。

如果指定 COPY，则源对象的元数据将应用于新创建的对象。

如果指定 REPLACE，该操作会将请求中提供的元数据应用于新创建的对象。

复制此类对象时，它会重写源对象，您必须添加 x-goog-metadata-directive: REPLACE。在所有其他情况下，标头都是可选的。

x-goog-metageneration

一个响应标头，用于指示您正在访问的对象元数据的版本。

有效值	任何正数（64 位）
示例	`x-goog-metageneration: 1`
详细信息	每当创建或替换对象时，Cloud Storage 都会自动分配 1 元世代。每当对象元数据更新（ACL 更新或其他元数据更新）时，metageneration 都会增加。这意味着较大的元世代始终意味着更新版本的对象元数据。但是，不同对象在不同世代之间没有已定义的关系，甚至没有相同对象的世代。对象的每个世代都有自己的元世代版本，其生成仅适用于其世代。如需了解详情，请参阅使用对象版本。

x-goog-hash

用于表示对象 MD5 和/或 CRC32C 和 base64 编码的校验和的请求和响应标头。作为对上传请求的请求标头，提供的哈希将根据 Cloud Storage 计算的值进行验证。

有效值	值为 `md5=BASE64_ENCODED_MD5` 或 `crc32c=BASE64_ENCODED_CRC32C`。以大端字节字节顺序指定 CRC32c 值。另请注意，HTTP 将以英文逗号分隔的标头值视为具有相同键的独立标头。
示例	`x-goog-hash: crc32c=n03x6A==` `x-goog-hash: md5=Ojk9c3dhfxgoKVVHYwFbHQ==` `x-goog-hash: crc32c=n03x6A==,md5=Ojk9c3dhfxgoKVVHYwFbHQ==`
详细信息	Cloud Storage 为所有非复合对象存储 MD5 哈希。 CRC32C 适用于所有对象。

x-goog-meta-

请求和响应标头，可让您定义对象的自定义元数据。

有效值任何有效的标头名称。

示例 x-goog-meta-reviewer: jane

详细信息

如需使用此标头，您可以将自定义标头名称附加到 x-goog-meta- 前缀，然后将标头及其关联值添加到 PUT 或 POST 请求中。例如，如果您的对象与多个项目相关联，您可以通过创建多个请求标头将项目特定信息添加到对象元数据中，例如：x-goog-meta-project-name， x-goog-meta-project-number 和 x-goog-meta-project-manager。然后，您可以在 PUT 或 POST 请求中为这些请求标头设置值，如以下示例所示：


PUT /kitten.jpg HTTP/1.1
Host: my-bucket.storage.googleapis.com
Date: Wed, 17 Jun 2020 11:11:11 GMT
Content-Type: image/jpg
Content-Length: 554
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ
x-goog-meta-project-name: Sales Projections
x-goog-meta-project-number: 878973
x-goog-meta-project-manager: W. Loman

x-goog-meta- 标头随对象一起存储，当您对对象执行 GET 或 HEAD 请求时，响应标头将始终返回。使用标题作为自定义元数据会产生费用，如价格和支持中所述。

注意：所有自定义标头及其关联值只能包含可打印的 US-ASCII 字符。

注意：我们建议您将自定义标头的总大小限制为 KB。

x-goog-project-id

用于指定您正在使用的项目的请求标头。

有效值	任何有效的项目编号或名称。
示例	`x-goog-project-id: 000111222333` `x-goog-project-id: my-project-name` `x-goog-project-id: example.com:my-google-apps-for-work-project-name`
详细信息	此请求标头指示 Cloud Storage 在哪个项目中创建存储分区或列出哪些项目。如果您已设置默认项目以进行互操作访问，则任务对于这些任务是可选的。

x-goog-resumable

启动可续传上传操作的请求标头。

有效值	开始
示例	`x-goog-resumable: start`
详细信息	此请求标头会通知 Cloud Storage 系统您要启动可续传上传。该标头只能用于 POST Object 请求，且只能用于进行可续传上传。

x-goog-storage-class

指示对象的存储类别的请求和响应标头。

有效值	`STANDARD`，`NEARLINE`，`COLDLINE`，`ARCHIVE`，`MULTI_REGIONAL`，`REGIONAL`
示例	`x-goog-storage-class: NEARLINE`
详细信息	此标头可以包含在 `PUT Object` 和 `POST Object` 请求中，以便将对象设置为关联存储分区的默认存储类别以外的对象。标头包含在所有 `GET Object` 响应中。

x-goog-stored-content-encoding

一个响应标头，用于指示存储在 Cloud Storage 中的对象的内容编码，不受任何服务器驱动的协商影响，可能针对对象的各项请求而发生。

有效值	对象上传或 `identity` 中指定的内容编码。
示例	`x-goog-stored-content-encoding: gzip`
详细信息	如果上传时未进行内容编码，则此标头的值为 `identity`。

x-goog-stored-content-length

响应标头，指示存储在 Cloud Storage 中的对象的内容长度（以字节为单位），与针对对象的单个请求而可能进行的任何服务器驱动的协商无关。

有效值	零或大于零的任何字节值。
示例	`x-goog-stored-content-length: 350`
详细信息	无

x-goog-user-project

一个请求标头，用于指定与请求关联的访问费用相关联的用户项目。

有效值	现有 Google Cloud 项目的项目 ID
示例	`x-goog-user-project: my-project`
详细信息	标头中指定的项目需要为与请求关联的费用付费。例如，当向启用了请求者付款的存储分区发出请求时，系统会使用此标头。

查询字符串参数

本部分介绍的查询字符串参数示例中，系统不会显示 URI，但假定相对于 storage.googleapis.com。如请求端点中所述，您还可以将主机名指定为主机名的一部分，例如 BUCKET-NAME.storage.googleapis.com。如果您要将存储分区指定为主机名的一部分，则请勿将存储分区名称包含在 URI 路径中。例如，以下代码相当于获取对象的 ACL：

https://storage.googleapis.com/BUCKET-NAME/object-name?acl
https://BUCKET-NAME.storage.googleapis.com/object-name?acl

访问密钥 ID

查询字符串参数，可帮助您确定要更新或删除的 HMAC 密钥。

有效值	与 HMAC 密钥关联的访问 ID。
示例	`/?Action=UpdateAccessKey&AccessKeyId=GOOG1EXAMPLE&Status=Inactive` `/?Action=DeleteAccessKey&AccessKeyId=GOOG1EXAMPLE`
详细信息	借助 `AccessKeyId` 查询字符串参数，您可以指定或删除哪些 HMAC 密钥。您必须将 `AccessKeyId` 与 `Action` 查询参数结合使用。如需了解如何检索 HMAC 密钥的访问 ID，请参阅获取 HMAC 密钥信息。

acl

查询字符串参数，可用于检索或更改存储分区或对象的访问控制列表。

有效值	无
示例	`/BUCKET_NAME?acl` `/BUCKET_NAME/OBJECT_NAME?acl`
详细信息	对于以下请求，此为可选操作：PUT Bucket、PUT Object、GET Bucket、GET Object。如果要发送 PUT 请求，则必须在请求正文中包含 XML 文档，用于指定要应用的 ACL。使用此查询参数时，您不能使用其他任何子资源。

操作

查询字符串参数，可用于确定要执行的 HMAC 密钥操作。

有效值	`ListAccessKeys`、`CreateAccessKey`、`UpdateAccessKey`、`DeleteAccessKey`
示例	`/?Action=ListAccessKeys`
详细信息	`Action` 查询字符串参数允许您指定要执行的 HMAC 密钥操作：`list`、`create`、`update` 或 `delete`。

billing

查询字符串参数，可用于为存储分区启用、停用或检查请求者付款功能的状态。

有效值	在请求正文中：`Enabled`、`Disabled`。
示例	`/BUCKET_NAME?billing`
详细信息	对于以下请求，该键是可选的：`GET Bucket`、`PUT Bucket`。在 `GET Bucket` 请求中使用时，请求者付款功能的当前状态会在响应正文中返回。用于`PUT Bucket`请求正文应包含`<BillingConfiguration>`元素来指定是否启用或停用该功能。如需详细了解如何使用 XML API 设置请求者付款功能，请参阅设置存储分区请求者付款。

compose

查询字符串参数，允许您将现有对象序列组合成新的复合对象（仅用于 XML API）。

有效值	无
示例	`/BUCKET_NAME/OBJECT_NAME?compose`
详细信息	对于 PUT Object 请求，此为可选项。您必须在请求正文中提供 ComposeRequest XML 文档。使用此查询参数时，您不能使用任何其他子资源。

cors

查询字符串参数，可用于检索或更改存储分区的跨源资源共享 (CORS) 功能。

有效值	无
示例	`/BUCKET_NAME?cors`
详细信息	对于以下请求，此为可选操作：PUT Bucket、GET Bucket。如果要发送 PUT 请求，则必须在请求正文中包含 XML 文档，用于指定要应用的 CORS。使用此查询参数，不得使用任何其他子资源。

defaultObjectAcl

查询字符串参数，可用于检索或更改存储分区的默认对象访问控制列表。

有效值	无
示例	`/BUCKET_NAME?defaultObjectAcl`
详细信息	对于 PUT Bucket 和 GET Bucket 请求，此为可选项。如果发送 PUT 请求，则必须在请求正文中包含 XML 文档，用于指定默认应用于存储分区的新对象的 ACL。使用此查询参数，不得使用任何其他子资源。如需了解详情，请参阅设置默认对象 ACL。

delimiter

用于在 GET Bucket 请求期间限制对象列表的字符或字符集。

有效值任何 Unicode 字符或字符。

示例 /?delimiter=/

详细信息

delimiter 可简化使用类目录命名方案的对象列表。指定此标志时，系统会返回名称不包含分隔符的对象，就像它们在响应的 Contents 元素中一样。如果对象名称包含分隔符，则对象名称中的一部分（包括并包括分隔符）将出现在响应的 CommonPrefixes 元素中。

您可以结合使用 delimiter 和 prefix 参数。在这种情况下，prefix 将结果限制为名称与 prefix 匹配的对象。

delimiter 通常设置为 /，但可为任意字符序列。有关如何使用 delimiter 的示例，请参阅分隔符示例。

编码类型

查询字符串参数，可响应对象列出请求的响应对象名称。

有效值	`url`
示例	`/bucket?encoding-type=url`
详细信息	在存储分区中列出对象时，可选。包含在请求中时，返回的对象名称将进行网址编码。如果您的任何对象名称包含 XML 1.0 无法解析的 Unicode 字符，这将非常有用。

加密

查询字符串参数，可用于检索对象的加密信息。

有效值	无
示例	`/object?encryption`
详细信息	对于 GET Object 请求，此为可选项。查询对象使用客户提供的加密密钥进行加密时，加密算法和密钥的 SHA-256 会在 `Encryption` 元素中返回。如果查询的对象是由 CMEK 进行加密，Cloud Key Management Service 密钥资源将在 `Encryption` 元素中返回。在其他所有情况下，系统会返回空的 `Encryption` 元素。使用此查询参数，不得使用任何其他子资源。

encryptionConfig

查询字符串参数，可用于设置或检索存储分区使用的默认 CMEK。

有效值	无
示例	`/bucket?encryptionConfig`
详细信息	对于 GET 存储分区请求，此为可选项。如果查询存储分区设置了默认的 CMEK ，则密钥资源的名称会在 `EncryptionConfiguration` 元素中返回。对于 PUT Bucket 请求，此为可选项。当请求在请求正文中包含客户管理的加密密钥资源时，该密钥将成为存储分区的默认加密密钥。如果请求包含空的 `EncryptionConfiguration` 元素，系统会从存储分区中移除任何现有的默认密钥。

世代

该值指示要提取哪个对象的世代。

有效值	任何正数（64 位）
示例	`?generation=1360887759327000`
详细信息	`generation` 查询字符串参数可用于指定操作对象的版本。

生成标记

此值表示您希望开始创建对象列表的世代编号。

有效值	任何正数（64 位）
示例	`?generation-marker=1360887759327000`
详细信息	`generation-marker` 查询字符串参数是版本化分区上分页页面的起点。必须与 `marker` 结合使用，以便明确指定对象以及之后开始列表的位置。任何高于指定 `generation-marker` 的对象版本（包括具有更高版本的当前版本）在对象列表中返回，就像字典顺序大于`marker`。

生命周期

查询字符串参数，允许您检索或更改存储分区的生命周期管理政策。

有效值	无
示例	`/BUCKET_NAME?lifecycle`
详细信息	对于以下请求，此为可选操作：PUT Bucket、GET Bucket。如果要发送 PUT 请求，则必须在请求正文中包含指定生命周期配置的 XML 文档。使用此查询参数时，您不能使用任何其他子资源。

位置

查询字符串参数，允许您检索存储分区的位置限制条件。

有效值	无
示例	`/BUCKET_NAME?location`
详细信息	对于以下请求，该键是可选的：GET 存储分区。

日志记录

查询字符串参数，可用于检索或更改存储分区的日志记录配置。

有效值	无
示例	`/BUCKET_NAME?logging`
详细信息	对于以下请求，此为可选操作：PUT Bucket, GET Bucket。如果要发送 PUT 请求，则必须在请求正文中包含用于指定日志记录配置的 XML 文档。使用此查询参数，不得使用任何其他子资源。

记号笔

一个字符串，用于指示要启动对象列表的位置。

有效值	任意字符串。
示例	`?marker=test`
详细信息	`marker` 查询字符串参数是一个 Unicode 字符串，用于指定您希望对象从何处开始执行的对象。返回的对象列表是指字典顺序大于 `marker` 的对象。

标记

页面令牌，可让您列出 HMAC 密钥的后续页面。

有效值	如果 `IsTruncated` 为 `true`，则上一个 `list` 响应中提供的字符串。
示例	`?Action=ListAccessKeys&Marker=AERPALERN/NEXT/TOKEN`
详细信息	`Marker` 查询字符串参数是一个连续令牌，用于在列出给定项目的 HMAC 密钥时用于对大型结果集进行分页。如果 `IsTruncated` 在之前的 `list` 响应中为 `true`，请在后续 `list` 请求中使用提供的 `Marker` 令牌，直到 `IsTruncated` `false`。您必须将 `Marker` 与 `Action` 查询参数结合使用。如需了解详情，请参阅 GET HMAC 密钥。

最大键数

此标志表示一个整数，用于限制单个结果“页”中返回的对象数量。

有效值	任何大于 0 的数字。
示例	`?max-keys=100`
详细信息	`max-keys` 查询字符串参数是一个整数，用于指定您希望对象列表中返回的最大对象数。如果请求可以返回超出 `max-keys` 允许的对象，则 `IsTruncated` 响应元素将包含 `True` 值。

项目项数量上限

一个整数，用于限制单个结果页面中返回的 HMAC 密钥的数量。

有效值	任何大于 0 的数字。
示例	`?Action=ListAccessKeys&MaxItems=100`
详细信息	`MaxItems` 查询字符串参数是一个整数，用于指定单个结果页面中返回的 HMAC 密钥的数量上限。如果请求可以返回超过 `MaxItems` 允许的键，则 `IsTruncated` 响应元素将包含 `true` 值。您必须将 `MaxItems` 与 `Action` 查询参数结合使用。服务返回的结果可能低于指定的最大值。

prefix

将对象列表限制为仅具有特定前缀的对象列表。

有效值	任何有效的前缀。
示例	?prefix=/europe/france
详细信息	`prefix` 查询字符串参数是一个 Unicode 字符串，用于限制列表名称以指定的 `prefix` 值开头的对象。可以将 `prefix` 查询字符串参数与 `delimiter` 查询字符串参数结合使用，以创建较小的对象子集。

response-content-disposition

查询字符串参数，允许针对经过身份验证的 GET 请求替换内容处置。

有效值	返回的用于编码的网址编码标头，而不是底层对象的内容处置。
示例	`?response-content-disposition=attachment%3B%20filename%3D%22foo%22`
详细信息	允许经过身份验证的 GET 请求替换标头中返回的内容处置。有关详情，请参阅规范。

响应-内容类型

查询字符串参数，允许针对经过身份验证的 GET 请求替换内容类型。

有效值	返回的网址编码标头，而非底层对象的内容类型。
示例	`?response-content-type=text%2Fhtml`
详细信息	允许经过身份验证的 GET 请求替换标头中返回的内容处置。有关详情，请参阅规范。

状态

查询字符串参数，可用于启用或停用 HMAC 密钥。

有效值	`InactiveActive`
示例	`?Action=UpdateAccessKey&AccessKeyId=GOOG1EXAMPLE&Status=Inactive`
详细信息	通过 `Status` 查询字符串参数，您可以更改 `Active` 和 `Inactive` 之间的 HMAC 密钥的状态。您必须将 `Status` 与 `Action` 和 `AccessKeyId` 查询参数结合使用。

storageClass

查询字符串参数，可用于设置或检索存储分区的存储类别。

有效值	在请求正文中：`STANDARD`、`NEARLINE`、`ARCHIVE`、`COLDLINE`、`MULTI_REGIONAL`、`REGIONAL`、`DURABLE_REDUCED_AVAILABILITY`
示例	`/BUCKET_NAME?storageClass`
详细信息	对于以下请求，该键是可选的：`GET Bucket`、`PUT Bucket`。在 `GET Bucket` 请求中使用时，指定存储分区的存储类别会在响应正文中返回。在 `PUT Bucket` 请求中使用时，请求正文应包含用于指定您要分配给存储分区的存储类别的 `<StorageClass>` 元素。如需详细了解如何使用 XML API 设置存储分区的存储类别，请参阅设置存储分区存储类别。

标记

查询字符串参数，可用于设置或检索应用于存储分区的标签。

有效值	在请求正文中：以 `key:value` 对形式提供的标签。
示例	`/BUCKET_NAME?tagging`
详细信息	对于以下请求，该键是可选的：`GET Bucket`、`PUT Bucket`。在 `GET Bucket` 请求中使用时，应用于指定存储分区的标签将在响应正文中返回。在 `PUT Bucket` 请求中使用时，请求正文应包含用于指定您要应用于存储分区的标签的 `<Tagging>` 元素。如需详细了解如何使用 XML API 应用标签，请参阅设置存储分区标签。

upload_id [上传 ID]

查询字符串参数，用于指定可续传上传操作的上传 ID。upload_id 是会话 URI 的一部分，但您应该保存整个会话 URI，因为它可以唯一地定义后续后续上传操作的请求 URI。会话 URI 从 Location 响应标头获取。

有效值任何有效的上传 ID。

示例 /?upload_id=tvA0ExBntDaOKdxL46u1NkHxNb...B2Uowrot HTTP/1.1

详细信息

上传 ID 的有效期为一周。我们建议您在获得上传 ID 后立即执行可续传上传，并在发生中断后立即恢复中断的上传。

如果您在请求中使用了过期的上传 ID，将会收到 404（未找到）状态代码。在这种情况下，您必须重新启动可续传上传操作，获得新的上传 ID，然后使用新的上传 ID 从头开始上传。

上传 ID 会绑定到创建它时所用的位置，因此如果您在一个位置创建并在另一个位置使用，则您的性能将会受到影响。

上传 ID 是一个 Bearer 令牌，这意味着该令牌拥有的身份验证器充当身份验证器。因此，您应小心谨慎，不要泄露上传 ID。

用户名

查询字符串参数，允许您标识要为其创建、更新或列出 HMAC 密钥的服务帐号。

有效值	有效的服务帐号电子邮件地址。
示例	`/?Action=CreateAccessKey&UserName=serviceAccount@proj.iam.gserviceaccount.com`
详细信息	如需创建 HMAC 密钥或更新与项目关联的密钥，可以选择使用 `UserName`。您必须将 `UserName` 与 `Action` 查询参数结合使用。

userProject 类的构造函数

查询字符串参数，用于指定与请求关联的访问费用结算项目 ID。

有效值	任何有效的项目 ID。
示例	`?userProject=example-project`
详细信息	此参数中指定的项目是与请求关联的费用。例如，在向已启用请求者付款功能的存储分区发出请求时，系统会使用 `userProject`。通常，需要项目 ID 的 XML 请求应在 `x-goog-user-project` 标头中（而不是 `userProject` 参数）提供一个。

版本控制

查询字符串参数，可用于检索或更改存储分区的版本控制配置。

有效值	无
示例	`/OBJECT_NAME?versioning`
详细信息	对于以下请求，此为可选操作：PUT Bucket, GET Bucket。如果发送 PUT 请求，则必须在请求正文中包含 XML 文档，用于指定要应用的版本控制配置。使用此查询参数时，您不能使用其他任何子资源。

版本

查询字符串参数，允许您检索启用了版本控制的存储分区中的所有对象。

有效值	无
示例	`/BUCKET_NAME?versions=True`
详细信息	对于以下请求，该键是可选的：GET 存储分区。

网站配置

查询字符串参数，可用于检索或更改存储分区的网站配置。

有效值	无
示例	`/BUCKET_NAME?websiteConfig`
详细信息	对于以下请求，此为可选操作：PUT Bucket, GET Bucket。如果要发送 PUT 请求，则必须在请求正文中包含 XML 文件，用于指定要应用的网站配置。使用此查询参数时，您不能使用其他任何子资源。

X-Goog 算法

一个查询字符串参数，用于确定 V4 签名网址算法。

有效值	`GOOG4-RSA-SHA256` `GOOG4-HMAC-SHA256` `AWS4-HMAC-SHA256`
详细信息	专门用于 V4 签名请求，例如签名网址。

X-Goog-Credential

用于确定要使用的凭据类型的查询字符串参数。

有效值	`Service_Account_Email/Date/Region/goog4_request` `Google_HMAC_Access_Key_ID/Date/Region/goog4_request` `AWS_HMAC_Access_Key_ID/Date/Region/aws4_request`
示例	使用 Google 服务帐号： `example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central-1%2Fstorage%2Fgoog4_request` 使用 HMAC： `GOOGTS7C7FUP3AIRVJTE2BCD%2F20181026%2Fus-central-1%2Fstorage%2Fgoog4_request`
详细信息	专门用于 V4 签名请求，例如签名网址。

X-Goog-Date（查询参数）

签名网址可以使用的日期和时间。

有效值	任何日期：YYYYMMDD'T'HHMMSS'Z'
示例	`?X-Goog-Date=20181026T181309Z`
详细信息	使用的格式为 ISO 8601 基本格式 YYYYMMDD'T'HHMMSS'Z'。

X-Goog-Expires

查询字符串参数，用于确定 V4 签名网址的有效时长。

有效值	最长 1 秒，包含 604800 秒
示例	`?X-Goog-Expires=900`
详细信息	签名网址的有效时长，按 X-Goog-Date 中的值（以秒为单位）衡量。最大值为 7 天或 604800 秒。

X-Goog-SignedHeaders

查询字符串参数，用于确定在 V4 签名网址中签名的标头。

有效值	唯一必需的标头为 host。任何使用 V4 签名网址签名的标头都必须在此列表中。
示例	`?X-Goog-SignedHeaders=host` `?X-Goog-SignedHeaders=host,x-goog-acl`
详细信息	使用签名网址的请求中必须包含的标头。

X-Goog-Signature

包含 V4 签名网址签名的查询字符串参数。

有效值	签名网址的签名。
示例	?X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7
详细信息	允许使用此签名网址来请求访问指定资源的身份验证字符串。