规范化请求

规范化请求定义用户在向 Cloud Storage 发送经 V4 签名身份验证的请求(例如签名网址)时必须包含的请求元素。如果您要发送 V2 签名网址,请参阅 V2 签名流程

概览

规范化请求是一个字符串,表示向 Cloud Storage 发出的特定 HTTP 请求。您可以将规范化请求和加密密钥(如 RSA 密钥)一起使用,以创建签名,然后将其作为身份验证包含在实际请求中。

规范化请求包括 HTTP 谓词、查询字符串参数、应在实际请求中使用的标头,以及要请求的对象、存储分区或其他资源等信息。

规范化请求可确保当 Cloud Storage 收到该请求时,它计算的签名与您计算的签名相同。如果您的版本与 Cloud Storage 计算的版本不匹配,请求将失败。

结构

规范化请求具有以下结构,包括在每个元素之间使用换行符:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

HTTP 动词

签名请求可以使用以下 HTTP 动词,这些动词必须随规范化请求一起指定:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1签名网址不支持 POST 请求,但使用可续传上传时除外。

资源路径

规范化请求包括指向请求要应用于的资源的路径。资源路径是位于主机名之后,查询字符串之前的所有内容。

例如,如果 Cloud Storage 网址为 https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg,则资源路径为 /example-bucket/cat-pics/tabby.jpeg

如果您使用 https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg 等备用 Cloud Storage 网址,则资源路径为 /cat-pics/tabby.jpeg

如需了解可与签名网址一起使用的其他网址端点,请参阅 XML API 请求端点

定义资源路径时,您必须对以下预留字符执行百分比编码?=!#$&'()*+,:;@[]."。此外,网址中使用的所有其他百分比编码都应包含在资源路径中。

规范化查询字符串

规范化请求包括随后必须包含在使用相关签名的签名请求中的所有查询字符串参数。但是,此类签名请求可能包含并非在规范化请求中指定的其他查询字符串参数。规范化请求中指定的查询字符串称为规范化查询字符串

查询字符串是资源路径末尾问号 (?) 后面的内容。

例如,如果 Cloud Storage 网址为 https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project,则查询字符串为 generation=1360887697105000&userProject=my-project

构建规范化查询字符串时,需要注意以下几点:

  • 必须使用按字典顺序排序的代码点值,按名称为查询字符串中的参数排序。

  • 查询字符串中的每个参数必须用 & 分隔。

  • 如果规范化查询字符串为空,则整个规范化请求的这一部分只是一个新行 (/n)。

必需的查询字符串参数

大多数查询字符串参数可根据需要添加,但是如果您打算使用规范化请求来创建签名网址,规范化请求中必须包含以下内容:

  • X-Goog-Algorithm:将用于对网址进行签名的算法。有效值为 GOOG4-RSA-SHA256GOOG4-HMAC-SHA256
  • X-Goog-Credential:将用于对网址进行签名的凭据。这些凭据包含采用以下格式提供的授权方和凭据范围[AUTHORIZER]%2F[CREDENTIAL_SCOPE]。授权方可以是服务帐号名称或 HMAC 访问密钥。
  • X-Goog-Date:采用 [ISO 8601][8] 基本格式 YYYYMMDD'T'HHMMSS'Z' 的当前日期和时间。
  • X-Goog-Expires:签名网址的生命周期(从 X-Goog-Date 开始算起,以秒为单位)。最长到期值为 604800 秒(7 天)。
  • X-Goog-SignedHeaders:以英文分号分隔的标头名称列表,这些标头在规范化请求中定义。它们也称为签名标头。host 必须是这些标头名称之一。

这些查询字符串参数以及 X-Goog-Signature 查询字符串参数(包含对请求进行身份验证的签名)随后必须用于签名网址本身。

规范化标头

规范化请求包括随后必须包含在使用相关签名的签名请求中的所有标头。但是,除了必需标头中所述的标头之外,这些签名请求可能包含并非在规范化请求中指定的其他标头。规范化请求中指定的标头称为规范化标头

规范化标头可以包含自定义标头以及以 x-goog 开头的扩展标头

指定规范化标头时,请注意以下几点:

  • 将所有标头名称都设为小写。
  • 使用按字典顺序排序的代码点值,按标头名称对所有标头排序。
  • 使用换行符 (/n) 分隔每个标头。
  • 创建一个标头名称(带有逗号分隔的值列表)以消除重复标头名称。确保值之间没有空格,并确保英文逗号分隔列表的顺序与标头在请求中显示的顺序匹配。如需了解详情,请参阅 RFC 7230 第 3.2 节
  • 将折叠空格或换行符(CRLF 或 LF)替换为一个空格。如需详细了解折叠空格,请参阅 RFC 7230 第 3.2.4 节
  • 移除标头名称后面出现的冒号周围的所有空格。

    例如,如果在冒号后面使用自定义标头 x-goog-acl: private,但又没有移除空格,则会返回 403 Forbidden 错误,因为您计算的请求签名与 Google 计算的签名不匹配。

示例

如果您拥有以下标头组:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

规范化请求中的规范化标头构造将是:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

所需的规范化标头

content-type 和扩展标头等大多数标头均可根据需要添加,但以下标头在每个签名请求中必不可少:

  • host:用于访问 Cloud Storage 的 URI。

此外,除非已在规范化标头中明确定义,否则以下标头不能用在使用签名的请求中。

  • x-goog-project-id
  • x-goog-copy-source
  • x-goog-metadata-directive
  • x-amz-copy-source
  • x-amz-metadata-directive

签名标头

规范化标头的名称部分是签名标头。

要创建签名标头列表,请将所有标头名称都转换为小写,按字符代码顺序对其进行排序,并使用英文分号 (;) 分隔各标头名称。

示例

如果您拥有以下标头组:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

规范化请求中的签名标头构造将是:

content-type;host;x-goog-meta-reviewer

载荷

  • 如果您的规范化请求将用于创建签名网址,则此值应该只是字符串 UNSIGNED-PAYLOAD

  • 如果您的规范化请求将在使用 Authorization 标头的请求中使用,则此值应为十六进制编码的 SHA-256 哈希请求载荷。如果载荷为空,请使用空字符串作为哈希函数输入。例如,一个哈希载荷(在此示例中为空载荷)为:

    3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

示例

以下是格式正确的规范化请求示例,其换行符显示为实际的新行而非 \n

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

后续步骤

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Cloud Storage
需要帮助?请访问我们的支持页面