本文档将介绍 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 状态代码。
其他资源
以下第三方文档可能对您有所帮助:
- IBM 的 Atom 概览
- HTTP 1.1 方法定义;针对
GET
、POST
、PUT
和DELETE
的规范 - HTTP 1.1 状态代码定义
- 如何创建 REST 协议
- 以 REST 方式构建 Web 服务
- XML 技术简介
- XML 命名空间示例