此页面由 Cloud Translation API 翻译。

协议基础知识

警告：本页面介绍的是 Google 的旧版 API，即 Google 数据 API；它仅与 Google 数据 API 目录中列出的许多 API 相关，其中许多 API 已替换为较新的 API。如需了解特定新 API，请参阅新 API 的文档。如需了解如何使用较新的 API 向请求授权，请参阅 Google 帐号身份验证和授权。

本文档将介绍许多 Google API 使用的 Google 数据协议的基础知识，包括查询的示例、结果的示例，等等。

如需详细了解 Google 数据协议，请参阅开发者指南概览页面和协议参考。

观众

本文档旨在向想要大致了解 Google 数据 API 所用 XML 格式和协议的任何人展示。

即使您只想编写使用特定语言的客户端库的代码，您也需要阅读本文档，了解客户端库的抽象层当前的情况。

本文档假定您了解 XML、命名空间、联合 Feed 以及 HTTP 中的 GET、POST、PUT 和 DELETE 请求的基础知识，以及 HTTP 的“资源”概念。如需详细了解这些内容，请参阅本文档中的其他资源部分。

本文档不依赖任何特定的编程语言；您的客户端可以使用允许您发出 HTTP 请求和解析基于 XML 的响应的任何编程语言与服务器进行交互。

如果您想在不编写任何代码的情况下尝试本文档中的示例，您可能会发现命令行实用程序 c网址或 Wget 很有用；如需了解详情，请参阅这些实用程序的手册页面或关于使用 c网址与使用 Google 数据协议的服务进行交互的文档。

示例

以下示例展示了您可能会直接使用 Google Data Protocol API 协议发送到通用服务的 HTTP 请求，以及您可能会收到的结果。有关如何使用各种编程语言发送请求的示例，请参阅特定语言的示例和客户端库。如需了解如何将 Google 数据协议与特定的 Google 服务搭配使用，请参阅特定服务的文档。

请求 Feed 或其他资源

假设有一个名为 /myFeed 的 Feed，并假设它当前不包含任何条目。如需查看它，请将以下 HTTP 请求发送到服务器：

GET /myFeed

服务器做出以下响应：

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

请注意，虽然 Feed 中不包含任何条目，但它确实包含元数据，例如标题和作者姓名。它还包含版本标识符，格式为 HTTP ETag。

插入新条目

如需创建新条目，请发送 POST 请求，并提供新条目的 XML 表示形式：

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

请注意，您不提供标准 Atom <id>、<link> 或 <updated> 元素；服务器会创建这些元素来响应您的 POST 请求。另请注意，Feed 的作者不一定要与条目的作者相同。

服务器做出以下响应：

201 CREATED

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

搜索字符串

如需对特定字符串进行全文搜索，请在使用支持全文搜索的服务时，发送带有 q 参数的 GET 请求。如需详细了解查询参数，请参阅协议参考文档中的查询请求。

GET /myFeed?q=This

服务器会返回一个 Feed，其中包含与搜索字符串 This 匹配的所有条目。（在本例中只有一个）。

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

更新条目

如需更新现有条目，您需要执行以下步骤。

检索您要更新的条目。
根据需要进行修改。
向条目的修改 URI 发送 PUT 请求，并在消息正文中包含更新后的条目。在上一个示例中，编辑 URI 显示为 <link rel='edit'> 元素的 href 属性。

您还必须指定原始条目的 ETag，以确保您不会覆盖其他人的更改。

在以下示例中，我们会将条目的文本从旧值（“这是我的条目”）更改为新值（“这是我的第一个条目）：

PUT /myFeed/1/1/

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

服务器做出以下响应：

200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

请注意，ETag 已更改。如需详细了解资源版本，请参阅协议参考文档的资源版本控制 (ETag) 部分。

如需在上下文中查看新条目，请再次请求整个资源：

GET /myFeed

服务器做出以下响应：

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

注意：如果您的防火墙不支持 PUT，请执行 HTTP POST 并设置方法替换标头，如下所示：

X-HTTP-Method-Override: PUT

删除条目

如需删除现有条目，请使用该条目的修改 URI 发送 DELETE 请求（由服务器在上例中提供）。

如果您的防火墙不允许 DELETE，则执行 HTTP POST 并按如下所示设置方法替换标头：

X-HTTP-Method-Override: DELETE

删除某个条目时，您可以选择执行条件删除（仅当该条目自上次检索后未发生变化时）或无条件删除。如需了解详情，请参阅协议参考文档的资源版本控制 (ETag) 部分。如需进行无条件删除，请设置以下 HTTP 标头：

If-Match: *

以下示例将删除某个条目（如果标头设置正确）：

DELETE /myFeed/1/

服务器做出以下响应：

200 OK

再执行一次 GET，以查看 Feed 现在是否不包含条目：

GET /myFeed

服务器会返回一个仅包含元数据的 Feed：

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

如果删除失败，服务器会返回错误代码。如需了解详情，请参阅协议参考文档中的 HTTP 状态代码。

请求部分 Feed 或条目（实验性）

与本文档中显示的简单示例 Feed 相比，实际中的 Feed 可能非常复杂。对于某些 API，您可以只请求您感兴趣的元素或属性，而不是完整的资源表示法。如果避免检索和解析不需要的数据，就可以显著提高客户端应用的效率。

如需请求部分响应，请使用 fields 查询参数指定您希望返回的元素或属性。如需了解详情，请参阅协议参考文档中的部分响应。

以下示例只请求了 Feed ID 以及每个 Feed 条目的作者和标题，

GET /myFeed?fields=id,entry(author)

服务器做出以下响应：

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

您可以对返回数据的任何类型请求使用 fields 参数。除了 GET 之外，还包含 POST 和 PUT（以及用于发出部分更新请求的 PATCH）。

注意：fields 查询参数仅控制响应请求而发回的数据，不会影响您必须在 PUT、POST 或 PATCH 请求的正文中提供的数据。

POST 和 PUT 的示例如下所示。

当您发出 POST 请求部分响应时，仍必须提供与插入新条目中所述的数据相同的数据。以下示例请求的是仅包含新条目标题的部分响应：
```
POST /myFeed?fields=title
      
...data...
```
服务器做出以下响应：
```
200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
```
当您发出部分响应的 PUT 请求时，仍必须提供完整资源表示法的修改版本，如更新条目中所述。以下示例请求的是部分响应，其中仅包含修改后的条目的新 ETag 值：
```
PUT /myFeed/1/1?fields=@gd:etag
  
...data...
```
服务器做出以下响应：
```
200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>
```

更新特定字段（实验性）

如果您使用的 API 支持部分响应并且具有可修改的字段，您还可以避免在修改条目时发送不必要的数据。部分更新可让您只为要更改的字段发送数据。

如需使用部分更新，请向 PUT 使用的同一修改 URI 发送 PATCH 请求。您通过 PATCH 发送的数据必须遵循特定惯例。不过，由于语义足够灵活，您可以使用一个请求替换目标资源中的数据，向目标资源添加数据，甚至从目标资源中删除数据。

注意：与 PUT 一样，您必须指定原始条目的 ETag，以确保您不会覆盖其他人的更改。

如需详细了解 PATCH 及其语义，请参阅协议参考文档中的部分更新。

以下示例展示了修改条目标题的部分更新请求：

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

收到 PATCH 请求时，服务器首先会移除条目的 gd:fields 属性所指定的任何字段（如果存在）；然后，它会将请求正文中提供的任何数据与目标资源合并。在此示例中，先从目标资源中移除标题元素，然后再合并新的标题值。实际上，此请求将旧标题替换为新标题。

但请注意，PATCH 的语义是将部分表示法合并到现有资源中。您无需移除字段即可更新其值。

如果该字段在目标条目中只能存在一次，则在合并时，部分表示法中的字段将覆盖目标条目中的相应字段。
如果该字段在目标条目中可以多次出现，则在合并时，系统会将部分字段添加到目标条目中。

下一个示例展示了重复字段和非重复字段的合并方式不同，该示例在条目中添加新的标题和作者，但没有使用 gd:fields 属性先移除其中任一字段。

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

由于部分条目表示法没有 gd:fields 属性，因此未移除任何字段。不过，<title> 和 <author> 元素的新值会与目标资源合并：

由于 Atom 只允许每个条目一个标题，因此新标题会覆盖现有值。
由于 Atom 允许每个条目有多个作者，因此新的作者会附加到已在目标资源中的作者元素列表中。

注意：并非所有 API 都符合 Atom 标准。例如，有些 API 仅允许每个条目有一个 <author> 元素；另一些 API 会沿用 Feed 级别的条目作者，将该字段设为只读。

服务器处理完有效的 PATCH 请求之后，会返回 HTTP 200 状态代码，以及更新后的条目的完整表示形式的副本。

如果您希望服务器仅返回某些元素或属性，可以将 fields 查询参数与 PATCH 结合使用，以请求部分响应。

其他资源

以下第三方文档可能对您有所帮助：

IBM 的 Atom 概览
HTTP 1.1 方法定义；针对 GET、POST、PUT 和 DELETE 的规范
HTTP 1.1 状态代码定义
如何创建 REST 协议
以 REST 方式构建 Web 服务
XML 技术简介
XML 命名空间示例

返回页首