XML API 概览

此文档简要介绍 Cloud Storage XML API，适用于软件开发者。本文假定您熟悉 RESTful 服务和网页编程，并且可以轻松创建通过 HTTP 请求运行的应用。如果上述方法不适用于您，请考虑以下某种替代方案：

• 如果您刚开始使用 Cloud Storage，应首先尝试 Cloud Console 快速入门或 gsutil 快速入门。这些教程演示了无需直接使用 API 即可使用 Cloud Storage 的基础知识。

• 如果您使用特定编程语言，则可以使用 Cloud Storage 客户端库。

• 如果您是移动或 Web 应用开发者，则可以使用适用于 Cloud Storage 的 Firebase SDK。

• 如果您不是软件开发者，并且希望将您的个人数据存储在云端并与他人共享，则可以使用 Google 云端硬盘。

概览

Cloud Storage XML API 是一个 RESTful 接口，允许您以程序化方式管理 Cloud Storage 数据。作为 RESTful API，它依赖于方法信息和范围信息来定义要执行的操作：

• 方法信息

  您可以使用标准 HTTP 方法（例如 DELETE、GET、HEAD 和 PUT）指定方法信息。

• 范围信息

  您可以使用范围限定的端点 (URI) 和各种范围参数来指定范围信息。对于 XML API，主要范围参数是存储分区和对象名称。您可以使用 HTTP 标头和查询字符串参数进一步限定操作范围。

您可以使用 HTTP 方法对您在该范围内指定的资源执行操作。有关 XML API 中可用操作的列表，请参阅 XML API 请求方法。

当您使用必须跨不同存储提供程序运行的工具和库时，或者当您从其他存储空间提供商迁移到 Cloud Storage 时，通过 XML API 访问 Cloud Storage 非常有用。在后一种情况下，您只需对现有工具和库进行一些更改，即可开始向 Cloud Storage 发送请求。如需详细了解如何迁移到 Cloud Storage，请参阅从 Amazon S3 迁移到 Google Cloud Storage。

请求

注意 ：我们建议您在读取或写入 Cloud Storage 数据时使用 HTTPS，以便在数据传输期间对数据进行加密。 Cloud Storage 会在数据写入磁盘之前自动加密数据。如需了解详情，请参阅加密。

Cloud Storage XML API 提供一个网页界面，用于发出 HTTP 请求和处理 HTTP 响应。此 API 兼容 HTTP/1.1、HTTP/2 和 HTTP/3 协议。每个请求都会实现标准的 HTTP 方法。除了这些方法，您还可以使用各种 HTTP 请求标头。

身份验证

向 Cloud Storage 发出的所有请求都必须进行身份验证，但向匿名访问的对象或存储分区发出的请求除外。如需详细了解如何为 Cloud Storage 请求设置 Authorization 标头，请参阅身份验证。

端点

重要提示 ：如果您打算通过浏览器传送内容，请注意，XML API 会从请求端点所对应的来源传送内容。如果您需要从某个独有来源传送内容，请考虑使用 JSON API 或基于身份验证的浏览器下载。

大多数 Cloud Storage XML API 请求使用以下 URI 访问存储分区和对象：

storage.googleapis.com

您可以通过向 URI 添加存储分区和对象来进一步缩小范围。生成的网址可以采用两种形式：

BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

您可以将 Cloud Storage URI 与采用不安全套接字层 (SSL) 加密的不安全请求 (HTTP) 和安全请求 (HTTPS) 搭配使用。

如需了解其他端点（例如 XML API 的专用上传和下载端点），请参阅请求端点。

标头和查询字符串参数

Cloud Storage XML API 支持 HTTP 请求标头。它也支持几个带有 x-goog- 前缀的扩展（自定义）请求标头。请求标头要求因您要发出的请求类型而异。一些常用的请求标头包括：

请求标头	说明	用量
Authorization	请求的身份验证字符串。	所有经过身份验证的请求都需要填写此参数。
Content-Length	请求正文（不包括标头）的大小（以字节为单位）。	所有 PUT 和 POST 请求（不包括分块传输除外）都必须提供。
Content-Type	请求正文的 MIME 类型，例如 application/xml 或 text/html。	建议用于包含实体正文的请求。
Date	请求的日期和时间。	必须为所有请求提供。
Host	请求的 URI。	必须为所有请求提供。
x-goog-project-id	您要使用的项目的 ID。	创建存储分区或列出存储分区时需要这样做，除非您使用 XML API 实现互操作性（例如与 Amazon S3 兼容）。如需了解详情，请参阅从 Amazon S3 迁移到 Google Cloud Storage。

Cloud Storage XML API 还支持各种查询字符串参数，您可以使用这些参数来限定请求范围。使用以下语法将查询字符串参数附加到请求的 HTTP 路径部分：

PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...

如需查看 XML API 标头和查询字符串参数的完整列表，请参阅 HTTP 标头和查询字符串参数。

请求示例

以下示例显示了一个典型的身份验证 Cloud Storage 请求。此请求会检索对象列表，这些对象存储在名为 travel-maps 的存储分区中。该请求将对象列表限制为仅包含前缀为 /europe/france 的对象。

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

响应

Cloud Storage XML API 会返回标准 HTTP 响应标头和多个扩展程序（自定义）响应标头。响应标头因您执行的操作而异。一些常用的响应标头包括：

响应标头	说明
Cache-Control	响应的缓存控制设置。
Content-Length	响应正文（不包括标头）的大小（以字节为单位）。
Content-Type	响应正文的 MIME 类型，例如 application/xml 或 text/html。
Date	响应的日期和时间。
ETag	HTTP 1.1 实体标记，可用于确定

对象是否已更改。

响应还可以包含状态代码。Cloud Storage 使用标准 HTTP 状态代码。错误响应会在响应正文中包含 XML 文档，其中包含有关错误条件的信息。如需查看 XML API 使用的状态代码列表，请参阅 HTTP 状态和错误代码。

以下示例显示了典型的 Cloud Storage 响应。该示例是对列出存储分区内容的请求的响应。存储分区名称为 travel-maps 且请求的范围是请求中，因此列表中仅返回前缀为 /europe/france/ 的对象。

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>
  <Name>travel-maps</Name>
  <Prefix>/europe/france/</Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.jpg</Key>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>