【Android】Google Contacts Data API : Protocol（中文版）

最新推荐文章于 2020-05-13 17:02:15 发布

littonvan

最新推荐文章于 2020-05-13 17:02:15 发布

阅读量9.6k

点赞数

分类专栏： Android功能实现代码汇总文章标签： google api android etag scheme 服务器

Android功能实现代码汇总专栏收录该内容

39 篇文章 0 订阅

订阅专栏

1 Protocol协议

1.1 Authenticating 认证

所有Contacts Data API的供给都是私有的受保护的。因此，你的客户端在访问一个联系人之前需要认证。可以通过以下两种方式来进行认证：CliengLogin 用户名/密码认证或者AuthSub代理认证

1.1.1 AuthSub代理认证

AuthSub proxy认证是当web应用程序需要认证他们的用户到谷歌账户时使用。客户端提供特殊的AuthSub让客户端能够进行一些特别的用户行为从而代理操作和客户端代码没有给用户用的用户名密码入口。

当用户第一使用你的应用程序的时候是没有被认证的，在这种情况下你需要显示一些信息并且给一个链接去谷歌的页面让用户去认证从而访问到他们的联系人。

下面是一些请求的参数需要被包含在AuthSubRequest URL中：

Parameter Description

next The URL of the page that Google should redirect the user to after authentication.

scope Indicates that the application is requesting a token to access contacts feeds. The scope string to use is https://www.google.com/m8/feeds/ (URL-encoded, of course).

secure Indicates whether the client is requesting a secure token.

session Indicates whether the token returned can be exchanged for a multi-use (session) token.

如果你请求的不是一个安全的令牌，这个AuthSubRequest URL可以像这样：

https://www.google.com/accounts/AuthSubRequest?scope=http://www.google.com/m8/feeds/&session=1&secure=0&next=http://www.example.com/welcome.html

用户根据这个连接去谷歌的网站就可以认证他们的谷歌账户

在用户认证时候，AuthSub系统就会跳转到一个特定的URL。AuthSub系统会附加一个认证的象征到这个URL上，作为这个请求的token参数的值。例如：

http://www.example.com/welcome.html?token=yourAuthToken

这个标记值代表一个如非单次使用请求页面象征。在这例子，自从session=1被提起，这个象征能被交换一个请求页面会议象征附近的的感召authsubsessiontoken服务同如非单次使用象征在一个授权头这般:

GET /accounts/AuthSubSessionToken HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Authorization: AuthSub token="yourAuthToken"

User-Agent: Java/1.5.0_06

Host: www.google.com

Accept: text/html, image/gif, image/jpeg, *; q=.2, **; q=.2

Connection: keep-alive

1.1.2 客户端登录，用户名/密码认证

如果你的机器是单机就可以使用客户端登录认证。发送一个post请求到下面的URL：

https://www.google.com/accounts/ClientLogin

POST的主体需要包含一些请求的信息。使用 application/x-www-form-urlencoded类型。这些参数是：

Parameter Description

accountType Type of account to be authenticated. The default is GOOGLE; if you want to support Google Apps users, use HOSTED_OR_GOOGLE.

Email The user's email address.

Passwd The user's password.

service The service name for contacts feeds is cp. (For other service names, see the service name list.)

source Identifies your client application. Should take the form companyName-applicationName-versionID. The examples use the name exampleCo-exampleApp-1.

如果认证请求失败，服务器就会返回HTTP 403 Forbidden的错误码

如果成功，就会返回HTTP 200 OK的状态码。添加3个长数字字符串码到这个响应的主体：SID，LSID，Auth。这个Auth的值就是每一次请求时都需要用到的证书，所以最好保留一个备份。你可以忽略SID和LSID的值。

每一次请求你都需要一个认证信息包含在请求头里面，请求的格式如下：

Authorization: GoogleLogin auth=yourAuthToken

yourAuthToken就是这个Auth的值（通过客户端登录请求返回来的）

使用同一个token为所有的请求在给定的session中。不要为每一次联系请求申请新的token。

1.1.3 Contacts feed URL

The feed URL是下面中的格式中的一种：

https://www.google.com/m8/feeds/contacts/userEmail/full

https://www.google.com/m8/feeds/contacts/default/full

“full”可以被其他的projection values所替换。你也可以使用用户的邮件地址代替default，这将告诉服务器返回这个用户的联系人。

只有被认证了的联系人的email地址才可以出现在这个特定的URL里面。

1.1.4 Specifying a version

Every request that you send using the Contacts Data API should specify version 3.0 of the API.

To specify a version number, use the GData-Version HTTP header:

GData-Version: 3.0

或者，如果你无法这时HTTP头信息的时候，你可以指定v=3.0作为一个请求参数放在URL中。但是写HTTP头信息是优先的。

Note: 客户端的库里是支持合适的版本头的，所以不要使用v=3.0的请求参数当你使用客户端的库时。

1.1.5 Creating contacts 创建联系人

认证完之后，你可以发布一个全新的联系人入口。

首先，创建一个要发布的联系人的XML描述。这个XML需要使用这样的格式，整个在<entry>元素的包裹下，看起来像下面这样子：

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'

xmlns:gd='http://schemas.google.com/g/2005'>

<atom:category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#contact' />

<gd:name>

<gd:givenName>Elizabeth</gd:givenName>

<gd:familyName>Bennet</gd:familyName>

<gd:fullName>Elizabeth Bennet</gd:fullName>

</gd:name>

<atom:content type='text'>Notes</atom:content>

<gd:email rel='http://schemas.google.com/g/2005#work'

primary='true'

address='liz@gmail.com' displayName='E. Bennet' />

<gd:email rel='http://schemas.google.com/g/2005#home'

address='liz@example.org' />

<gd:phoneNumber rel='http://schemas.google.com/g/2005#work'

primary='true'>

(206)555-1212

</gd:phoneNumber>

<gd:phoneNumber rel='http://schemas.google.com/g/2005#home'>

(206)555-1213

</gd:phoneNumber>

<gd:im address='liz@gmail.com'

protocol='http://schemas.google.com/g/2005#GOOGLE_TALK'

primary='true'

rel='http://schemas.google.com/g/2005#home' />

<gd:structuredPostalAddress

rel='http://schemas.google.com/g/2005#work'

primary='true'>

<gd:city>Mountain View</gd:city>

<gd:street>1600 Amphitheatre Pkwy</gd:street>

<gd:region>CA</gd:region>

<gd:postcode>94043</gd:postcode>

<gd:country>United States</gd:country>

<gd:formattedAddress>

1600 Amphitheatre Pkwy Mountain View

</gd:formattedAddress>

</gd:structuredPostalAddress>

</atom:entry>

发布这个入口，将其发送到联系人列表的post URL中。首先，将你的Atom<entry>元素作为一个新的post请求，使用application/atom+xml类型。然后发送这个post URL。例如，添加一个联系人到liz@.com的联系人列表中，post这个入口到如下的URL中：

https://www.google.com/m8/feeds/contacts/liz@gmail.com/full

或者你可以简单的使用如下的URL：

https://www.google.com/m8/feeds/contacts/default/full

然后谷歌服务器就会使用你的entyr创建一个联系人，然后返回一个HTTP 201 CREATED状态码。并且会返回一个新的联系人在这个表单中<enrty>。这个返回的和你发送过去的是一样的，但是他会包含一些various元素，例如<id>.

Note:一个联系人的photo是不能在创建联系人的时候被设置的。

如果因为某些原因创建失败，那么谷歌就会返回一些不同的状态码。

1.1.6 Retrieving contacts 检索联系人

1.1.6.1 Retrieving all contacts

要检索用户的联系人时，发送一个HTTP 的GET请求到联系人的URL。然后谷歌就会返回一个适当的联系人入口。比如。我们需要得到liz@gmail.com的联系人列表，发送这样的一个HTTP请求：

GET https://www.google.com/m8/feeds/contacts/liz@gmail.com/full

或者你可以简单的使用下面的URL

https://www.google.com/m8/feeds/contacts/default/ful

这个信号然后就会返回一个HTTP 200 OK 的状态码和一个标准的Atom 1.0 feed包含这些联系人。

Note：这个反馈可能并没有包含所有的用户联系人，因为这里有一个默认的限制返回的联系人数目。

下面的是一个仅有一个入口的联系人反馈示例：

<feed xmlns='http://www.w3.org/2005/Atom'

xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'

xmlns:gContact='http://schemas.google.com/contact/2008'

xmlns:batch='http://schemas.google.com/gdata/batch'

xmlns:gd='http://schemas.google.com/g/2005'

gd:etag='W/"CUMBRHo_fip7ImA9WxRbGU0."'>

<id>liz@gmail.com</id>

<category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#contact' />

<title>Elizabeth Bennet's Contacts</title>

type='application/atom+xml'

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full' />

type='application/atom+xml'

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full' />

type='application/atom+xml'

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/batch' />

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full?max-results=25' />

<name>Elizabeth Bennet</name>

<email>liz@gmail.com</email>

</author>

Contacts

</generator>

<openSearch:totalResults>1</openSearch:totalResults>

<openSearch:startIndex>1</openSearch:startIndex>

<openSearch:itemsPerPage>25</openSearch:itemsPerPage>

<id>

http://www.google.com/m8/feeds/contacts/liz@gmail.com/base/c9012de

</id>

<app:edited xmlns:app='http://www.w3.org/2007/app'>2008-12-10T04:45:03.331Z</app:edited>

<category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#contact' />

<title>Fitzwilliam Darcy</title>

<gd:name>

<gd:fullName>Fitzwilliam Darcy</gd:fullName>

</gd:name>

href='https://www.google.com/m8/feeds/photos/media/liz@gmail.com/c9012de'

gd:etag='"KTlcZWs1bCp7ImBBPV43VUV4LXEZCXERZAc."' />

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/c9012de' />

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/c9012de' />

<gd:phoneNumber rel='http://schemas.google.com/g/2005#home'

primary='true'>

456

</gd:phoneNumber>

<gd:extendedProperty name='pet' value='hamster' />

<gContact:groupMembershipInfo deleted='false'

href='http://www.google.com/m8/feeds/groups/liz@gmail.com/base/270f' />

</entry>

</feed>

1.1.6.2 Retrieving contacts using query parameters 使用查询参数检索联系人。

Contacts Data API 可以让我们查询一个满足我们特定要求的联系人集合。例如查询所有在某个给点时间之后更新的联系人。

例如，发送一个时间区的查询，添加updated-min参数到查询的URL。去得到所有在March 16,2007之后更新的联系人，HTTP URL如下：

GET https://www.google.com/m8/feeds/contacts/liz@gmail.com/full?updated-min=2007-03-16T00:00:00

或者直接发送一个简单的URL：

GET https://www.google.com/m8/feeds/contacts/default/full?updated-min=2007-03-16T00:00:00

当你发送这个GET请求之后，服务器将会返回一个HTTP 200 OK的状态吗和一个反馈包含所有的在指定日期之后创建或者更新的联系人。

Hint：如何追踪增加的修改了的联系人列表，按如下做：当你发送请求去得到反馈时，保持跟踪的值<updated>元素。然后你可以设置updated-min参数为<update>的值，并且将showdeleted设为true。我同样推荐设置requirealldeleted设置为true，这样当服务器无法完成查询的时候将会返回一个410 的HTTP响应。

Note：默认情况下，反馈中的联系人信息是不排序的。

1.1.6.3 Retrieving a single contact 检索一条Contact信息

检索一条指定的联系人，发送一个HTTP的GET请求到联系人的链接。服务器将会返回一个入口。例如：

GET https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/12345

或者简单的使用下面的URL：

GET https://www.google.com/m8/feeds/contacts/default/full/12345

服务器将会返回一个HTTP 200 OK的状态码和一个包含了联系人信息的入口。

1.1.6.4 Retrieving a contact again 再次检索某个联系人

如果你项检索一个你曾经检索过的联系人，你可以通过告诉服务器去仅仅发送这个联系人如果他自上次检索之后被修改过从而来提高效率。

发送一个HTTP GET请求，在头信息中包含一个If-None-Match ，指定这个联系人的ETag，ETag你可以在<entry>元素的gd:etag属性中找到。

例如：

If-None-Match: "Qn04eTVSLyp7ImA9WxRbGEUORAQ."

当服务器接受到请求之后就会去查看这个ETag是不是相同，如果是相同的就表明没有被修改，然后就会返回一个304 Not Modified 的状态码。

如果这个ETags不匹配，那么服务器就会返回这个被修改了的联系人。

1.1.6.5 Retrieving a photo for a contact 检索一个联系人的图片

检索联系人的图片，发送一个HTTP GET请求到这个联系人的图片链接。服务器将会返回这个图片的bytes。例如：

href='https://google.com/m8/feeds/photos/media/liz@gmail.com/c9012de'

gd:etag='"KTlcZWs1bCp7ImBBPV43VUV4LXEZCXERZAc."'/>

发送下面的HTTP请求：

GET https://google.com/m8/feeds/photos/media/liz@gmail.com/c9012de

服务器然后返回一个HTTP 200 OK的状态码和图片。

Note：如果联系人没有图片，那么这个联系人连接的元素将会没有gd:etag属性

Note：当使用图片链接时，在HTTP的头中需要有授权。

1.1.7 Updating contacts 更新联系人

更新一个已经存在的联系人，首先检索你想要更新的联系人，修改他，然后发送一个PUT请求到联系人编辑的URL，使用 application/atom+xml格式

确保你的更新没有重写其他的客户的修改，包括If-Match的头信息其中包含有原版的联系人的ETag值。你可以决定这个元宝的联系人的ETag的值通过<entry>元素的gd:etag属性。

如果你想更新联系人而不管有没有其他已经更新过了自从你检索他，那么就使用If-Match:*并且不要包含这个ETag。

Note：联系人的名字信息存储在<atom:title>元素中

确保<id>的值必须和已经存在的<id>一致。

<id>http://www.google.com/m8/feeds/contacts/liz@gmail.com/base/8411573</id>

<category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#contact' />

<title type='text'>Jo March</title>

<gd:name>

<gd:givenName>Jo</gd:givenName>

<gd:familyName>March</gd:familyName>

<gd:fullName>Jo March</gd:fullName>

</gd:name>

<content type='text'>Notes</content>

href='https://www.google.com/m8/feeds/photos/media/liz@gmail.com/8411573' />

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/8411573' />

href='https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/8411573' />

<gd:phoneNumber rel='http://schemas.google.com/g/2005#other'

primary='true'>456-123-2133</gd:phoneNumber>

<gd:extendedProperty name='pet' value='hamster' />

<gd:extendedProperty name='cousine'>

</gd:extendedProperty>

<gContact:groupMembershipInfo deleted='false'

href='http://www.google.com/m8/feeds/groups/liz@gmail.com/base/270f' />

</entry>

这个编辑的URL如下：

https://www.google.com/m8/feeds/contacts/liz@gmail.com/full/8411573

Important：保证向前兼容，当你PUT一个更新过的入口时，一定要维持所有的XML是你从服务器端检索下来的。否则被忽略的元素将会被删除。

Troubleshooting Tip：有一些防火墙拦截HTTP的PUT信息。为了绕过他，你可以包含一个X-HTTP-Method-Override: PUT 头在POST请求中。

Important：设置扩展属性（gd:extendedProperty 元素）只能设为full或者property-NAME映射

1.1.8 Contact photo management

没一个联系人都有图片的链接元素。是这样的格式：

href='https://www.google.com/m8/feeds/photos/media/liz@gmail.com/c9012de'

gd:etag='"KTlcZWs1bCp7ImBBPV43VUV4LXEZCXERZAc."'>

这个元素只有当联系人有一个关联的图片是才会出现。如果联系人有图片，那么这个元素将会包含一个gd:etag属性指定一个ETag为这个图片。如果没有图片，那么就没有gd:etag属性，并且href属性土工给URL来为联系人增加一个图片。

添加或者更新图片，使用<link>，发送一个新的图片通过PUT：

https://www.google.com/m8/feeds/photos/media/liz@gmail.com/c9012de。记得设置"image/*"类型的头。

删除图片，发送一个HTTP DELETE请求到相同的URL。

当更新或者删除图片的时候，发送ETag在If-Match头在HTTP的请求中。或者，使用If-Match:*来更新或者删除而不管是否有别人修改过。

1.1.9 Deleting contacts

删除一个联系人，发送一个DELETE请求到联系人编辑的URL。适合更新联系人相同的URL（谷歌一般在联系人被删除后的30天内都不会将联系人真正的删除，在这段时间内，你可以请求被保持的联系人使用showdeleted请求参数）。

如果你想确保不要删除一个自从你检索之后被别人修改过的联系人信息，包含一个HTTP If-Match头然后包含原版的联系人的ETag值。

如果想删除一个联系人而不管别人是否修改过，那么使用If-match:*并且不要包含ETag值。

Troubleshooting Tip：有一些防火墙拦截HTTP的DELETE信息。为了绕过他，你可以包含一个X-HTTP-Method-Override: PUT 头在POST请求中。

1.1.10 Using structured name and postal address

该<gd:name>元素表示一个联系人的姓名。它可以包含子元素代表各地区联系人的名称，如<gd:givenName>和<gd:familyName>。它也可以包含<gd:fullName>子元素，它代表了全部，接触格式的名称。

虽然全名往往可以从不同的名称部分所得，服务器不会尝试执行这种关系。客户端应用程序不应假设有一间全名和名称组成部分僵化的关系，因为其他应用程序可以选择，例如，允许使用给定名称的接触“亚伯拉罕，”姓氏“林肯”，并全名“答：林肯。”

您的客户端应用程序可以使用完整的名称，名称的部分，或两者兼而有之。如果您的应用程序要求用户输入一个名称，它可以提示全名，零件，或两者兼而有之。全名字段可以设置独立于结构名称字段。

当你的客户，通常只使用一个“味”的美称，它更新现有的联系人的名字已被用户修改，客户端可能要么自动生成和发送等风味与用户提供了一个它一起，或者它可能清除其他味道（即发送未经代表其他风味元素<gd:name>），以避免让外的与您的客户端支持的味道同步。如果任何一个格式化的姓名或名称部分的所有结构在客户端提供<gd:name>丢失，服务器可能会尝试填补了这个名字失踪的味道。

阅读时，显示或处理联系信息由谷歌提供的联系人或其他来源，你的客户应该准备好处理项目中的全名或结构名称是空的。特别是，许多传统应用创建联系人只包含完整的名称，而不是部分。

类似的问题适用于<gd:structuredPostalAddress>和<gd:formattedAddress>。虽然在原则<gd:formattedAddress>是从像<gd:street>和<gd:city>各种地址部分组成，服务器不执行任何关系。如果任何一个格式化的地址或地址的所有结构组件丢失，服务器可能会试图取得另一失踪的味道。

1.1.11 Managing contact groups

联系人可以被放置到不同的用户自定义的群组中去。你可以创建，检索，并且删除这些群组。你可以添加联系人到群组或者将联系人移除群组。

Contacts Data API提供了四个预定义的“system groups”为每个用户。

·My Contacts

·Friends

·Family

·Coworkers

系统群组出现在群组feed中就像用户自定义的群组一样使用。实际上，系统群组几乎就是项其他群组一样对待。不同的是：

·每一个系统群组的entry包含一个 <gContact:systemGroup>子元素。子元素的id属性标示这时哪个系统群组：Contacts, Friends, Family, or Coworkers.

·你不能增加新的系统群组，不能改名字，不能增加其他的属性，也不能删除。

·联系群组中系统群组没有rel="edit"的链接。

Note：系统组的名字都不能保证是局部的，所以一般你的客户是为展示的方式为你的用户，如通过提供适当的系统组本地化的名称，或代表他们使用的图标的系统组负责。

1.1.11.1 Contact groups feed URL

feed UR如下面2者中的任一个都可以：

https://www.google.com/m8/feeds/groups/userEmail/full

https://www.google.com/m8/feeds/groups/default/full

Note：“full”可以被其他的projection values所替换。你也可以使用用户的邮件地址代替default，这将告诉服务器返回这个用户的联系人。

Note：只有通过认证的用户的email地址才能在URL中。

1.1.11.2Changing group membership

决定联系人属于哪个群组，检查联系人的<gContact:groupMembershipInfo>元素。每一个该元素都包含一个群组的ID。

添加一个联系人到群组，你的客户端需要知道群组的ID。这个ID可以在群组的feed中的<id>元素中找到。

Note：<id>元素的值是互不相同的

在得到群组的ID之后，就可以更新联系人，添加一个新的 <gContact:groupMembershipInfo>元素来指定群组的ID。

删除群组关系，只需要删除联系人的<gContact:groupMembershipInfo>项就OK了。

所有的这些也都适用于系统的群组。

1.1.12 Creating contact groups创建群组

你在认证之后可以创建一个新的群组信息。

例如：

<atom:entry xmlns:gd="http://schemas.google.com/g/2005">

<atom:category scheme="http://schemas.google.com/g/2005#kind"

term="http://schemas.google.com/contact/2008#group"/>

<atom:title type="text">Salsa group</atom:title>

<gd:extendedProperty name="more info about the group">

<info>Nice people.</info>

</gd:extendedProperty>

</atom:entry>

发布这个entry，发送他到联系人列表的post URL。首先，使用一个新的POST请求来替换Atom<entry>元素，使用application/atom+xml类型。然后发送他到URL。例如，添加一个群组到联系人群组发送如下的链接：

https://www.google.com/m8/feeds/groups/jo@gmail.com/full

谷歌服务器创建了一个联系人群组之后会返回一个HTTP 201 CREATED状态码，并且会返回联系人群组的表单。表单中会添加一些东西例如<id>。

1.1.13 Retrieving contact groups 检索联系人群组

1.1.13.1 Retrieving all contact groups检索所有的群组

发送一个Get的请求。例如查询jo@gmail.com的群组：

GET https://www.google.com/m8/feeds/groups/jo@gmail.com/full

然后feed就会返回一个HTTP 200 OK的状态码和一个标准的Atom1.0 feed 包含群组的信息。

一个是联系人群组feed的示例（包含系统群组和联系人自定义群组）：

<feed xmlns='http://www.w3.org/2005/Atom'

xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'

xmlns:gContact='http://schemas.google.com/contact/2008'

xmlns:batch='http://schemas.google.com/gdata/batch'

xmlns:gd='http://schemas.google.com/g/2005'

gd:etag='W/"D08MQnc-fSp7ImA9WxRbGU0."'>

<id>jo@gmail.com</id>

<category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#group' />

<title>Jo March's Contact Groups</title>

href='http://www.google.com/' />

type='application/atom+xml'

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin' />

type='application/atom+xml'

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin' />

type='application/atom+xml'

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin/batch' />

<link rel='self'

type='application/atom+xml'

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin?max-results=25' />

<name>Jo March</name>

<email>jo@gmail.com</email>

</author>

<generator version='1.0'

uri='http://www.google.com/m8/feeds'>Contacts</generator>

<openSearch:totalResults>5</openSearch:totalResults>

<openSearch:startIndex>1</openSearch:startIndex>

<openSearch:itemsPerPage>25</openSearch:itemsPerPage>

<id>http://www.google.com/m8/feeds/groups/jo@gmail.com/base/6</id>

<category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#group' />

<title>System Group: My Contacts</title>

<content>System Group: My Contacts</content>

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin/6' />

<gContact:systemGroup id='Contacts' />

</entry>

[...Other system groups removed for ease of reading...]

<id>http://www.google.com/m8/feeds/groups/jo@gmail.com/base/68f415478ba1aa69</id>

<category scheme='http://schemas.google.com/g/2005#kind'

term='http://schemas.google.com/contact/2008#group' />

<title>joggers</title>

<content>joggers</content>

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin/68f415478ba1aa69' />

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/thin/68f415478ba1aa69' />

</entry>

</feed>

1.1.13.2 Retrieving contact groups using query parameters 检索满足特定条件的群组

例如要查询所有在March 16, 2007之前被更新的群组：

GET https://www.google.com/m8/feeds/groups/jo@gmail.com/full?updated-min=2007-03-16T00:00:00

服务器将返回一个HTTP 200 OK的状态码和一个包含所有满足条件的群组的feed。

Note：默认的，不排序。

1.1.13.3 Retrieving a single group for a contact 检索一条群组

若要检索为一个组给定的接触属于单组条目，发送一个HTTP GET请求，从gContact：groupMembershipInfo来自联系人的条目内容。

例如：

<gContact:groupMembershipInfo deleted="false" href="http://google.com/m8/feeds/groups/jo@gmail.com/base/68f415478ba1aa69"/>

元素，发送下面的HTTP请求：

GET https://www.google.com/m8/feeds/groups/jo@gmail.com/base/68f415478ba1aa69

服务器将会返回一个HTTP 200 OK的状态码和一个包含联系人群组的条目。

Note：这个条目可能并没有包含所有的联系人的群组信息，因为这有一个默认的条数限制。

1.1.14 Updating contact groups 更新联系人群组

更新一个已经存在的群组的名字或者属性，首先得到这个要更新的群组，然后修改他，然后在发送一个PUT请求到联系人编辑的URL，使用application/atom+xml 类型。确保<id>的值和之前的值要一致。

示例如下：

<entry xmlns:gd="http://schemas.google.com/g/2005"

gd:etag=""Rno4ezVSLyp7ImA9WxdTEUgNRQU."">

<category scheme="http://schemas.google.com/g/2005#kind"

term="http://schemas.google.com/g/2005#group"/>

<id>http://www.google.com/feeds/groups/jo@gmail.com/base/1234</id>

<title type="text">Salsa group</title>

<content type="text">Salsa group</content>

href= 'https://www.google.com/m8/feeds/groups/jo@gmail.com/full/2' />

href='https://www.google.com/m8/feeds/groups/jo@gmail.com/full/2'/>

<gd:extendedProperty name="more info about the group">

<info>Very nice people.</info>

</gd:extendedProperty>

</entry>

编辑的URL：

https://www.google.com/m8/feeds/groups/jo@gmail.com/full/2

在成功更新之后服务器将返回一个HTTP 200 OK的状态码和一个更新后的条目。

1.1.15 Deleting contact groups 删除联系人群组

发送一个DELETE请求到联系人群组编辑的URL。同样谷歌会为你保存30天，这期间可以通过showdeleted来查询，成功了将会返回200 OK

Troubleshooting Tip：有一些防火墙拦截HTTP的DELETE信息。为了绕过他，你可以包含一个X-HTTP-Method-Override: PUT 头在POST请求中。

Note：不要通过删除一个群组然后又添加一个群组的方式在更新群组。

1.1.16 Batch operations

如果您要执行的操作很多，所花费的时间发送和接收所有的HTTP消息真的可以积少成多，使您的应用程序缓慢，反应迟钝。随着一批请求，你可以让服务器执行一个HTTP请求与多个操作。其基本思想是，你创建一个联系人或联系小组饲料和每个操作添加一个要执行的条目。

下面的代码片断显示了一个包含两个批次请求创建操作，但你也可以使用查询，更新和删除联系人或联系人组。对不必要的部分，大部分已省略。

<?xml version='1.0' encoding='UTF-8'?>

<feed xmlns='http://www.w3.org/2005/Atom'

xmlns:gContact='http://schemas.google.com/contact/2008'

xmlns:gd='http://schemas.google.com/g/2005'

xmlns:batch='http://schemas.google.com/gdata/batch'>

<entry>

<batch:id>1</batch:id>

<batch:operation type='insert' />

<gd:name>

<gd:fullName>Contact 1</gd:fullName>

</gd:name>

<gd:email rel='http://schemas.google.com/g/2005#home' address='contact1@gmail.com' primary='true'/>

</entry>

<entry>

<batch:id>2</batch:id>

<batch:operation type='insert' />

<gd:name>

<gd:fullName>Contact 2</gd:fullName>

</gd:name>

<gd:email rel='http://schemas.google.com/g/2005#home' address='contact2@gmail.com' primary='true'/>

</entry>

</feed>

批量操作限制在每次100个操作。

Note：更新和删除时最好要使用gd:etag属性，从而避免重写别人的客户端操作。

littonvan

关注

0
点赞
踩
3

收藏

觉得还不错? 一键收藏
0
评论
【Android】Google Contacts Data API : Protocol（中文版）

1 Protocol协议 1.1 Authenticating 认证所有Contacts Data API的供给都是私有的受保护的。因此，你的客户端在访问一个联系人之前需要认证。可以通过以下两种方式来进行认证：CliengLogin 用户名/密码认证或者AuthSub代理认证 1.1.1 AuthSub代理认证 AuthSub
复制链接

扫一扫

专栏目录