GData协议基础知识

读者

这篇文档是为那些想理解由谷歌API使用的XML格式和协议的人而准备的。

即使你只是想写一些基于特定语言的，使用客户端库的代码，你也应该读一下这篇文档，这可以帮组你了解隐含在client libraries抽象层下到底发生了什么。

这篇文章假设了你已经理解了XML的基础知识，命名空间，聚类反馈，以及HTTP下的GET,POST,PUT,POST请求，还有HTTP的资源概念。对以上所述的的更多信息可看这部分的额外资源。

这篇文章不依赖于某一特定的编程语言。你的客户端可以使用任何一种语言和服务器端进行交互，只需要提交HTTP请求，然后解析基于XML的返回信息。

例子

以下的例子向你展示了你如何发送一个简单的Data
API协议的请求到某一个常用服务，以及你将收到一个什么样的返回结果。对于怎么样使用特定编程语言来发送请求，可以查看特定语言样例和client
libraries。对于使用谷歌数据APIS以及特定谷歌服务的信息，查看特定服务的文档。

请求一个反馈或者其他资源

假设有一个反馈叫做myFeed，并且假设它当前不包含任何请求输入。你想查看它，可以发送一个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>

注意：尽管这个反馈信息不包含任何请求输入，但是它却包含元数据，比如标题以及作者的姓名，还有版本描述符，以一种HTTP ETag的形式。

插入一个新的entry

如果想创建一个新的entry，发送一个POST请求，并且提供新的entry的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请求创建这些元素。同时注意反馈的作者信息非要和一个entry的作者是同一个人。

服务器返回信息为:

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>

搜索一个字符串
如果一个服务支持full-text 搜索，并且你想为某一个字符串作一个full-text搜索，你可以发送带有q参数的请求。想要更多关于查询参数的信息，你可以查看协议参考文档中的查询请求。

GET /myFeed？q=This

服务器将返回所有匹配字符串This的entries。（这个案例中只有一个）

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>

更新一个entry

更新一个已经存在的entry，可以使用PUT,并带上entry的编辑URI(由上个例子中在<link rel='edit'>元素中给出）

如果你的防火墙不允许PUT，那么你可以执行HTTP POST请求，并且设置方法覆盖头，方法如下：

X-HTTP-Method-Override：PUT

你还必须描述原始entry的ETag，来保证你没有overwrite其他人的修改。

在下面的例子中，我们将entry文本的旧值（"This is my entry")改为一个新的值（"This is my first entry").

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>

服务器返回

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发生了改变。关于资源的版本信息，可以参考协议参考文档的Resource versioning(ETag)部分。

如果想看新的entry,可以重新调用GET /myFeed

删除一个entry

删除一个存在的entry,可以发送一个DELETE请求。同样使用entry的编辑URI.

如果防火墙不允许，库使用POST和设置方法覆盖头，如下

X-HTTP-Method-Override: DELETE

当你删除一个entry,你可以选择是否是一个条件删除（只删除那些上次检索过后还没有发生改变的entries)或者是无条件删除。详情见参考，做一个无条件删除，先设置以下HTTP头

If-Match: *

下面例子是删除一个entry(如果头已经被有效设置）

DELETE  /myFeed/1

服务器返回

200 OK(IF ERROR , return error code).

额外资源（见另一篇日志）