Google 数据 API 协议基础知识

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

有关 Google 数据 API 的详细信息，请参阅 Google 数据开发者指南文档和参考指南。

观众

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

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

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

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

示例

以下示例显示了您可能会发送给通用服务的裸 Data API 协议请求，以及您可能收到的结果。有关如何使用各种编程语言发送请求的示例，请参阅特定语言的示例和客户端库。有关将 Google 数据 API 用于特定 Google 服务的信息，请参阅特定服务的文档。

请求 Feed 或其他资源

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

GET /myFeed

服务器做出以下响应：

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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 中不包含任何条目，但它确实包含元数据，例如标题和作者姓名。

插入新条目

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

POST /myFeed

<?xml version="1.0"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

更新条目

如需更新现有条目，请使用 PUT，同时使用条目的编辑 URI（由服务器在上例的 <link rel="edit"> 元素中提供）。

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

X-HTTP-Method-Override: PUT

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

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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>

请注意，修改 URI 已更改；现在以“/2/”（而不是“/1/”）结尾。编辑 URI 中的最后一个数字是版本号。如需详细了解版本，请参阅协议参考文档的乐观并发部分。

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

GET /myFeed

服务器做出以下响应：

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

删除条目

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

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

 X-HTTP-Method-Override: DELETE

以下示例演示了如何删除条目：

DELETE /myFeed/1/2/

服务器做出以下响应：

200 OK

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

GET /myFeed

服务器做出以下响应：

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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 状态代码。

其他资源

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

返回页首