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 授予 READFULL_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-privateprivatepublic-readpublic-read-writeauthenticated-read

对于对象:project-privateprivatebucket-owner-readbucket-owner-full-controlpublic-readauthenticated-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-matchx-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_MD5crc32c=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-namex-goog-meta-project-numberx-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

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

有效值 STANDARDNEARLINECOLDLINEARCHIVEMULTI_REGIONALREGIONAL
示例 x-goog-storage-class: NEARLINE
详细信息 此标头可以包含在 PUT ObjectPOST 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 密钥。您必须将 AccessKeyIdAction 查询参数结合使用。如需了解如何检索 HMAC 密钥的访问 ID,请参阅获取 HMAC 密钥信息

acl

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

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

操作

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

有效值 ListAccessKeysCreateAccessKeyUpdateAccessKeyDeleteAccessKey
示例 /?Action=ListAccessKeys
详细信息 Action 查询字符串参数允许您指定要执行的 HMAC 密钥操作:listcreateupdatedelete

billing

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

有效值 在请求正文中:EnabledDisabled
示例 /BUCKET_NAME?billing
详细信息 对于以下请求,该键是可选的:GET BucketPUT 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 元素中。

您可以结合使用 delimiterprefix 参数。在这种情况下,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 密钥的后续页面。

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

最大键数

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

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

项目项数量上限

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

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

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 查询字符串参数,您可以更改 ActiveInactive 之间的 HMAC 密钥的状态。您必须将 StatusActionAccessKeyId 查询参数结合使用。

storageClass

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

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

标记

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

有效值 在请求正文中:以 key:value 对形式提供的标签。
示例 /BUCKET_NAME?tagging
详细信息 对于以下请求,该键是可选的:GET BucketPUT 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。您必须将 UserNameAction 查询参数结合使用。

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
详细信息 允许使用此签名网址来请求访问指定资源的身份验证字符串。