借助传统版 Google 协作平台 API,您的应用可以在 Google 协作平台内访问、发布和修改内容。 此外,您的应用还可以请求近期活动列表、提取修订历史记录以及上传/下载附件和文件。
受众群体
本文假定您了解 Google 数据 API 协议背后的一般概念。
本文面向的是特定程序员,他们希望编写可与 Google 协作平台进行交互的客户端应用。 它提供了一系列使用原始 XML/HTTP 进行基本数据 API 交互的示例及说明。阅读本文档后,您可以阅读左侧导航栏中其他指南中的特定语言示例,详细了解如何使用我们的客户端库与该 API 进行交互。
有关本指南中资料的参考信息,请参阅参考指南。
向请求授权
当您的应用请求非公开用户数据时,它必须包含授权令牌。Google 也可通过此令牌识别您的应用。
关于授权协议
您的应用必须使用 OAuth 2.0 向请求授权,其他任何授权协议均不受支持。如果您的应用使用使用 Google 账号登录,系统会代您执行授权方面的某些操作。
使用 OAuth 2.0 向请求授权
针对非公开用户数据向 Google 协作平台数据 API 发出的请求必须由经过身份验证的用户授权。
根据您所编写的应用的类型,OAuth 2.0 的具体授权流程可能会有所不同。下面是适用于所有应用类型的大致流程:
- 开发应用时,您需要使用 Google API 控制台注册该应用。然后,Google 会提供您稍后需要用到的信息,例如客户端 ID 和客户端密钥。
- 在 Google API 控制台中激活 Google 协作平台数据 API。(如果 API 控制台中未列出该 API,请跳过这一步。)
- 当您的应用需要访问用户数据时,它会请求 Google 提供特定范围的访问权限。
- Google 会向相应用户显示权限请求页面,让用户授权您的应用请求他们的某些数据。
- 待该用户同意后,Google 会为您的应用提供一个时效很短的访问令牌。
- 您的应用会请求获取用户数据,并在请求中附上该访问令牌。
- 如果 Google 确定您的请求及令牌有效,就会返回您所请求的数据。
有些流程还包含其他步骤,例如使用刷新令牌获取新的访问令牌。如需详细了解适用于各类应用的不同流程,请参阅 Google 的 OAuth 2.0 文档。
以下是 Google 协作平台数据 API 的 OAuth 2.0 范围信息:
https://sites.google.com/feeds/
要通过 OAuth 2.0 请求访问权限,您的应用既需要授权范围信息,也需要 Google 在您注册应用时提供的信息(如客户端 ID 和客户端密钥)。
指定版本
您向 Google 协作平台数据 API 发出的每个请求都应指定版本 1.4。如需指定版本号,请使用 GData-Version
HTTP 标头:
GData-Version: 1.4
或者,如果您无法设置 HTTP 标头,则可以在网址中将 v=1.4
指定为查询参数。但应尽可能优先使用 HTTP 标头。
注意:客户端库会自动提供适当的版本标头,因此在使用客户端库时请勿使用 v=1.4
查询参数。
网站 Feed
网站 Feed 可用于列出用户拥有或有权查看的 Google 协作平台,还可用于修改现有网站的标题。对于 G Suite 网域,该工具还可用于创建或复制整个网站。
列出网站
要列出用户有权访问的网站,请向以下网址发送经过身份验证的 GET
请求:
https://sites.google.com/feeds/site/domainName
Feed 参数 | 说明 |
---|---|
domainName | “site ”或您的 G Suite 托管域名(例如 example.com )的域名。 |
响应将包含带有以下网站列表的 Feed:
GET /feeds/site/domainName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> HTTP/1.1 200 OK <feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0"> <id>https://sites.google.com/feeds/site/site</id> <updated>2009-12-02T17:47:34.406Z</updated> <title>Site</title> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://sites.google.com/feeds/site/site"/> <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="https://sites.google.com/feeds/feeds/site/domainName"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName"/> <link rel="next" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/?start-index=2"/> <generator version="1" uri="http://sites.google.com/">Google Sites</generator> <openSearch:startIndex>1</openSearch:startIndex> <entry gd:etag="W/"CkUAQH4_eil7I2A9WxNaFk4.""> <id>https://sites.google.com/feeds/site/site/myTestSite</id> <updated>2009-12-01T01:17:21.042Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-01T01:17:21.042Z</app:edited> <title>myTestSite</title> <summary/> <link rel="alternate" type="text/html" href="http://sites.google.com/site/myTestSite/"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/myTestSite"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myTestSite"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myTestSite"/> <sites:siteName>myTestSite</sites:siteName> <sites:theme>default</sites:theme> </entry> <entry gd:etag="W/"DkQGQHczfA9WxNaFk4.""> <id>https://sites.google.com/feeds/site/domainName/myOtherTestSite</id> <updated>2009-12-01T02:25:21.987Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-01T02:25:21.987Z</app:edited> <title>myOtherTestSite</title> <summary>A new site to hold memories</summary> <category scheme="http://schemas.google.com/sites/2008#tag" term="Memories Site"/> <link rel="alternate" type="text/html" href="http://sites.google.com/site/myOtherTestSite"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/myOtherTestSite"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myOtherTestSite"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myOtherTestSite"/> <sites:siteName>myOtherTestSite</sites:siteName> <sites:theme>iceberg</sites:theme> </entry> ... </feed>
网站按字母顺序排列。
创建新网站
注意:此功能仅适用于 G Suite 网域。
您可以通过向网站 Feed 发出 HTTP POST
来配置新网站,例如:
POST /feeds/site/example.com HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:sites="http://schemas.google.com/sites/2008"> <title>Source Site</title> <summary>A new site to hold memories</summary> <sites:theme>slate</sites:theme> </entry>
上述请求会在 G Suite 网域 example.com
下创建一个主题为“可选广告”的新 Google 网站。
此网站的网址为 http://sites.google.com/a/example.com/source-site/。
如果网站成功创建,服务器将做出 201 Created
响应。响应条目将包含服务器添加的元素,例如指向网站的链接、指向网站 ACL Feed 的链接、网站名称、标题和摘要。
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0" gd:etag="W/"DEECR38l7I2A9WxNaF0Q.""> <id>https://sites.google.com/feeds/site/example.com/source-site</id> <updated>2009-12-02T23:31:06.184Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-02T23:31:06.184Z</app:edited> <title>New Test Site</title> <summary>A new site to hold memories</summary> <link rel="alternate" type="text/html" href="http://sites.google.com/a/example.com/source-site/"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/example.com/source-site"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/source-site"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/source-site"/> <sites:siteName>source-site</sites:siteName> <sites:theme>slate</sites:theme> </entry>
复制网站
注意:此功能仅适用于 G Suite 网域。
您可以采用与创建新网站相同的方式复制现有网站。不过,在 POST
请求的 Atom 条目中,请添加一个 <link>
,其中 rel='source'
指向要复制的网站的网站 Feed。所有被复制的网站都有这个链接以下是复制网站的示例:
POST /feeds/site/example.com HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom"> <link rel="http://schemas.google.com/sites/2008#source" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/source-site"/> <title>Copy of New Test Site</title> <summary>A newer site to hold memories</summary> </entry>
以上请求会复制 http://sites.google.com/a/example.com/source-site/ 上的网站。
要点:
- 只能复制经过身份验证的用户拥有的网站和网站模板。
- 也可以复制网站模板。如果在 Google 协作平台设置页面中选中了“将此网站发布为模板”设置,则相应网站就是模板。
- 您可以从其他网域复制网站,但系统会将您列为源网站的所有者。
更新网站的元数据
如需更新网站的标题或摘要,请向网站条目的 edit
链接发送 HTTP PUT
。
例如,以下示例会将之前网站的标题更新为 New Test Site2
,并将其说明更新为 Newer description
。
PUT /feeds/site/example.com/source-site HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0" gd:etag="W/"DEECR38l7I2A9WxNaF0Q.""> <id>https://sites.google.com/feeds/site/example.com/source-site</id> <updated>2009-12-02T23:31:06.184Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-02T23:31:06.184Z</app:edited> <title>New Test Site2</title> <summary>Newer description</summary> <category scheme="http://schemas.google.com/sites/2008#tag" term="Category"/> <link rel="alternate" type="text/html" href="http://sites.google.com/a/example.com/source-site/"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/example.com/source-site"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/source-site"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/source-site"/> <sites:siteName>source-site</sites:siteName> </entry>
添加类别
注意:此功能仅适用于 G Suite 网域。
G Suite 域名网站包含类别元数据,可用于对网域中的网站进行分类。要添加或更新类别元数据,请向网站条目的 edit
链接发送 HTTP PUT
(其中包含 category
标记)。请参阅以下示例中的粗体代码行:
PUT /feeds/site/example.com/source-site HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0" gd:etag="W/"DEECR38l7I2A9WxNaF0Q.""> <id>https://sites.google.com/feeds/site/example.com/source-site</id> <updated>2009-12-02T23:31:06.184Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-02T23:31:06.184Z</app:edited> <title>My Team website</title> <summary>This site contains contact information and a summary of major efforts our team owns</summary> <category scheme="http://schemas.google.com/sites/2008#tag" term="Team Site"/> <link rel="alternate" type="text/html" href="http://sites.google.com/a/example.com/my-team-site/"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/example.com/my-team-site"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/my-team-site"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/my-team-site"/> <sites:siteName>my-team-site</sites:siteName> </entry>
本示例修改现有网站并添加类别“团队网站”。
您还可以通过添加额外的 <category>
标签来添加多个类别。请参阅以下示例中的粗体代码行:
PUT /feeds/site/example.com/my-team-site HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0" gd:etag="W/"DEECR38l7I2A9WxNaF0Q.""> <id>https://sites.google.com/feeds/site/example.com/my-team-site</id> <updated>2009-12-02T23:31:06.184Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-02T23:31:06.184Z</app:edited> <title>My Team website</title> <summary>This site contains contact information and a summary of major efforts our team owns</summary> <category scheme="http://schemas.google.com/sites/2008#tag" term="Team Site/"> <category scheme="http://schemas.google.com/sites/2008#tag" term="Legal Department/"> <link rel="alternate" type="text/html" href="http://sites.google.com/a/example.com/my-team-site/"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/example.com/my-team-site"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/my-team-site"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/example.com/my-team-site"/> <sites:siteName>my-team-site</sites:siteName> </entry>
此示例添加了两个类别:“团队网站”和“法务部门”
网址映射
借助网址映射,Google 协作平台用户可以将自己的网域映射到 Google 协作平台。例如,您可以使用 http://www.mydomainsite.com
代替 http://sites.google.com/a/domain.com/mysite
。根据网站的托管位置,您可以手动修改网站的网址映射。如需了解详情,请参阅我们的帮助中心文章。
提取网站的网址映射
若要返回某个网站的网址映射,请使用 with-mappings=true
参数提取网站条目/Feed:
GET /feeds/site/domainName?with-mappings=true HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> HTTP/1.1 200 OK <feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0"> ... <entry gd:etag="W/"DkQGQHczfA9WxNaFk4.""> <id>https://sites.google.com/feeds/site/domainName/myOtherTestSite</id> <updated>2009-12-01T02:25:21.987Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-01T02:25:21.987Z</app:edited> <title>myOtherTestSite</title> <summary>A new site to hold memories</summary> <link rel="alternate" type="text/html" href="http://sites.google.com/site/myOtherTestSite"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/myOtherTestSite"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myOtherTestSite"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myOtherTestSite"/> <link rel='webAddressMapping' href='http://www.mysitemapping.com'> <link rel='webAddressMapping' href='http://www.mysitemapping2.com'> <link rel='webAddressMapping' href='http://www.myothermapping.org'> </entry> ... </feed>
现有映射将显示为带有 rel='webAddressMapping' 的 link
。例如,上面的示例中有三个指向网站 http://sites.google.com/site/myOtherTestSite
的 webAddressMapping
。
修改网址映射
注意:在使用网址映射时,所有 GET/POST/PUT 操作都应指定 with-mappings=true
参数。如果该参数不存在,则网站条目 (GET) 中不会返回 webAddressMapping
,在更新/移除条目中的 PUT 映射时,系统不会考虑 webAddressMapping
。
如需添加、更新或删除映射,只需在创建新网站或更新网站的元数据时指定、更改或移除此类链接即可。网站 Feed URI 中必须包含 with-mappings=true
参数。注意:要更新地址映射,您必须是网站管理员;如果网站是由 G Suite 托管的,则您必须是网域管理员。
例如,以下请求会将 http://www.mysitemapping.com
映射更新为 http://www.my-new-sitemapping.com
,并通过在条目中保留链接来移除 http://www.mysitemapping2.com
:
PUT /feeds/site/domainName?with-mappings=true HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry gd:etag="W/"DkQGQHczfA9WxNaFk4.""> <id>https://sites.google.com/feeds/site/domainName/myOtherTestSite</id> <updated>2009-12-01T02:25:21.987Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-01T02:25:21.987Z</app:edited> <title>myOtherTestSite</title> <summary>A new site to hold memories</summary> <link rel="alternate" type="text/html" href="http://sites.google.com/site/myOtherTestSite"/> <link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/myOtherTestSite"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myOtherTestSite"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/site/domainName/myOtherTestSite"/> <link rel='webAddressMapping' href='www.my-new-sitemapping.com'> <!-- missing mapping2 will be deleted --> <link rel='webAddressMapping' href='http://www.myothermapping.org'> </entry>
请注意,也可以在创建/复制网站时指定网址映射。
活动 Feed
您可以通过提取活动 Feed 来获取网站的近期活动(更改)。活动 Feed 中的每个条目都包含对网站所做更改的相关信息。
如需查询活动供稿,请向活动供稿网址发送 HTTP GET
:
https://sites.google.com/feeds/activity/domainName/siteName
Feed 参数 | 说明 |
---|---|
domainName | “site ”或您的 G Suite 托管域名(例如 example.com )的域名。 |
siteName | 您网站的网络空间名称;可在网站的网址中找到(例如 myCoolSite )。 |
示例请求和响应:
GET /feeds/activity/site/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"> <id>https://sites.google.com/feeds/activity/site/siteName</id> <updated>2009-09-10T05:24:23.120Z</updated> <title>Activity</title> <link rel="alternate" type="text/html" href="http://sites.google.com/site/siteName/system/app/pages/recentChanges"/> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://sites.google.com/feeds/activity/site/siteName"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/activity/site/siteName"/> <generator version="1" uri="http://sites.google.com">Google Sites</generator> <openSearch:startIndex>1</openSearch:startIndex> <entry xmlns:gd="http://schemas.google.com/g/2005" gd:etag="W/"CU4GQ3szfSl7ImA9WxNRFUg.""> <id>https://sites.google.com/feeds/activity/site/siteName/940375996952876062</id> <updated>2009-09-10T03:38:42.585Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#deletion" label="deletion"/> <title>home</title> <summary type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">User deleted <a href="http://sites.google.com/site/siteName/home">home</a> </div> </summary> <link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/site/siteName/5409745539831916487"/> <link rel="http://schemas.google.com/sites/2008#current" type="application/atom+xml" href="https://sites.google.com/feeds/content/site/siteName/5409745539831916487"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/activity/site/siteName/940375996952876062"/> <author> <name>User</name> <email>user@gmail.com</email> </author> </entry> <entry xmlns:gd="http://schemas.google.com/g/2005" gd:etag="W/"CU8DQn45fyl7ImA9WxNRFUg.""> <id>https://sites.google.com/feeds/activity/site/siteName/7165439066235480082</id> <updated>2009-09-10T03:37:53.027Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#edit" label="edit"/> <title>home</title> <summary type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">User2 edited <a href="http://sites.google.com/site/siteName/home">home</a> </div> </summary> <link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/site/siteName/5409745539831916487"/> <link rel="http://schemas.google.com/sites/2008#current" type="application/atom+xml" href="https://sites.google.com/feeds/content/site/siteName/5409745539831916487"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/activity/site/siteName/7165439066235480082"/> <author> <name>User</name> <email>user@gmail.com</email> </author> </entry> <entry xmlns:gd="http://schemas.google.com/g/2005" gd:etag="W/"CU8AR3s4cSl7ImA9WxNRFUg.""> <id>https://sites.google.com/feeds/activity/site/siteName/127448462987345884</id> <updated>2009-09-10T03:37:26.539Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#creation" label="creation"/> <title>home</title> <summary type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">User3 created <a href="http://sites.google.com/site/siteName/home">home</a> </div> </summary> <link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/site/siteName/5409745539831916487"/> <link rel="http://schemas.google.com/sites/2008#current" type="application/atom+xml" href="https://sites.google.com/feeds/content/site/siteName/5409745539831916487"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/activity/site/siteName/127448462987345884"/> <author> <name>User3</name> <email>user3@gmail.com</email> </author> </entry> </feed>
注意:只有网站的协作者或所有者才能访问此 Feed。
您的客户端必须发送正确的 Authorization
标头,并引用向请求授权中获取的令牌。
修订版本 Feed
要获取任何内容条目的修订历史记录,请向该条目的修订链接发送 HTTP GET
:
https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID
Feed 参数 | 说明 |
---|---|
domainName | “site ”或您的 G Suite 托管域名(例如 example.com )的域名。 |
siteName | 您网站的网络空间名称;可在网站的网址中找到(例如 myCoolSite )。 |
如需查找指定页面/评论/附件/listitem 的修订链接,请先使用相应条目的 CONTENT_ENTRY_ID 从内容 Feed 中检索该条目。检索到的条目将包含修订版本 Feed 的 <atom:link>
。例如:
<link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID"/>
示例请求和响应:
GET /feeds/revision/domainName/siteName/CONTENT_ENTRY_ID HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0"> <id>https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID</id> <updated>2009-09-10T04:33:35.337Z</updated> <title>Revisions</title> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID"/> <generator version="1" uri="http://sites.google.com">Google Sites</generator> <openSearch:startIndex>1</openSearch:startIndex> <entry gd:etag="W/"CU4GQmA9WxNRFUg.""> <id>https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID/2</id> <updated>2009-09-10T03:38:42.045Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <title>Home</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">Latest content here</div> </content> <link rel="alternate" type="text/html" href="http://sites.google.com/domainName/siteName/CONTENT_ENTRY_ID/system/app/pages/admin/compare?wuid=wuid%3Agx%3A4f67c7&rev1=2"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID/2"/> <author> <name>User</name> <email>user@gmail.com</email> </author> <sites:pageName>home</sites:pageName> <sites:revision>2</sites:revision> </entry> <entry gd:etag="W/"CU8DQ388eSl7ImA9WxNRFUg.""> <id>https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID/1</id> <updated>2009-09-10T03:37:52.171Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <title>Home</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">Older content here</div> </content> <link rel="alternate" type="text/html" href="http://sites.google.com/domainName/siteName/CONTENT_ENTRY_ID/system/app/pages/admin/compare?wuid=wuid%3Agx%3A4bc7&rev1=1"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/CONTENT_ENTRY_ID/1"/> <author> <name>User</name> <email>user@gmail.com</email> </author> <sites:pageName>home</sites:pageName> <sites:revision>1</sites:revision> </entry> </feed>
注意:只有网站的协作者或所有者才能访问此 Feed。
您的客户端必须发送正确的 Authorization
标头,并引用向请求授权页面中获取的令牌。
内容 Feed
检索内容
内容 Feed 列出了 Google 协作平台的当前内容。向以下网址发送经过身份验证的 GET
请求:
https://sites.google.com/feeds/content/domainName/siteName
Feed 参数 | 说明 |
---|---|
domainName | “site ”或您的 G Suite 托管域名(例如 example.com )的域名。 |
siteName | 您网站的网络空间名称;可在网站的网址中找到(例如 myCoolSite )。 |
所得结果是列出站点上内容条目第一页的 Feed。Feed 中的每个条目将表示不同类型的内容条目,例如 webpage
、filecabinet
、attachment
、comment
等。<category scheme="http://schemas.google.com/g/2005#kind">
元素决定了条目的类型。如需查看支持 kind
值的列表,请参阅参考指南。
注意:此 Feed 可能需要进行身份验证,也可能不需要身份验证,具体取决于网站的共享权限。
如果网站为非公开网站,您的客户端必须发送正确的 Authorization
标头(如上例所示)并引用在向请求授权步骤中获取的令牌。
GET /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0"> <id>https://sites.google.com/feeds/content/domainName/siteName</id> <updated>2009-08-31T01:39:20.286Z</updated> <title>Content</title> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName"/> <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName"/> <link rel="http://schemas.google.com/g/2005#batch" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/batch""/> <link rel="next" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/?start-index=2"/> <generator version="1" uri="http://sites.google.com">Google Sites</generator> <openSearch:startIndex>1</openSearch:startIndex> <entry gd:etag="W/"Ck8GQXk7fil7ImA9WxNSFk0.""> <id>https://sites.google.com/feeds/content/domainName/siteName/7322156894</id> <updated>2009-08-30T02:53:40.706Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-08-30T02:53:40.706Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <title>Subpage</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">Page html content here</div> </content> <link rel="http://schemas.google.com/sites/2008#parent" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/6492205817"/> <link rel="alternate" type="text" href="http://sites.google.com/site/siteName/subpage"/> <link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/7322156894"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/7322156894"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/7322156894"/> <author> <name>User</name> <email>user@gmail.com</email> </author> <sites:pageName>subpage</sites:pageName> <sites:revision>5</sites:revision> </entry> <entry gd:etag="W/"CkMBQH08fCl7ImA9WxNSFk0.""> <id>https://sites.google.com/feeds/content/domainName/siteName/5930635231</id> <updated>2009-08-30T02:47:31.374Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-08-30T02:47:31.374Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#listitem" label="listpage"/> <title/> <link rel="http://schemas.google.com/sites/2008#parent" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/5930635231"/> <link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/5930635231"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/5930635231"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/5930635231"/> <author> <name>User</name> <email>user@gmail.com</email> </author> <sites:revision>1</sites:revision> <gs:field index="A" name="Issue/Feature">Implement cool feature X</gs:field> <gs:field index="B" name="Priority">P2</gs:field> <gs:field index="C" name="Owner"/> <gs:field index="D" name="Resolved"/> </entry> <entry gd:etag="W/"AkYHQ3ozcCl7ImA9WxJaE08.""> <id>https://sites.google.com/feeds/content/domainName/siteName/1265948545471894517</id> <updated>2009-08-03T19:35:32.488Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-08-03T19:35:32.488Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#filecabinet" label="filecabinet"/> <title>files</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">Page html content here</div> </content> <link rel="alternate" type="text" href="https://sites.google.com/domainName/siteName/files"/> <link rel="http://schemas.google.com/sites/2008#revision" type="application/atom+xml" href="https://sites.google.com/feeds/revision/domainName/siteName/12671894517"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/12671894517"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/12671894517"/> <author> <name>User</name> <email>user@gmail.com</email> </author> <gd:feedLink href="httpn://sites.google.com/feeds/content/domainName/siteName?parent=12671894517"/> <sites:pageName>files</sites:pageName> <sites:revision>1</sites:revision> </entry> ... </feed>
注意:这只是前几条结果。如需浏览整个内容 Feed,请点击 Feed 的“下一页”链接:
<link rel="next" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/?start-index=2"/>
如需了解 Atom 常见元素,请参阅 Google 数据协议参考。
下文介绍了传统版协作平台 API 包含哪些元素。某些种类条目具有其他属性(未列出),而其他种类条目则没有。例如,listitem
条目可能包含 <gs:field>
元素,而 webpage
条目则不包含。
元素 | 说明 |
---|---|
<content ...> | 内部文本是网页的 HTML 正文。对于某些条目(例如附件),此元素将包含指向该文件的 src 属性。 |
<link rel="alternate" ...> | 链接到 Google 协作平台中的网页或项。 |
<link rel="http://schemas.google.com/sites/2008#revision" ...> | href 属性指向条目的修订版本 Feed。 |
<link rel="http://schemas.google.com/sites/2008#parent" ...> | href 属性指向条目的父条目。 |
<link rel="http://schemas.google.com/sites/2008#template" ...> | href 属性指向条目的模板页面。 |
<category scheme="http://schemas.google.com/g/2005#kind" ...> | label 是条目的类型。 |
<category term="http://schemas.google.com/g/2005#template" ...> | label=template 表示条目是一个模板。 |
<gd:feedLink> | href 属性指向条目父级的子级。 |
<sites:pageName> | 网页的网络空间名称;与网页的网址中的名称相对应。 |
<sites:revision> | 当前修订版本号。 |
内容 Feed 查询示例
您可以使用一些标准 Google Data API 查询参数以及传统版 协作平台 API 专用的查询参数来搜索内容 Feed。如需了解详情以及受支持参数的完整列表,请参阅参考指南。
检索特定条目种类
如需仅提取特定类型的条目,请使用 kind
参数。此示例仅返回 webpage
条目:
GET /feeds/content/domainName/siteName?kind=webpage
如需返回多个条目类型,请使用“,”分隔每个 kind
。以下示例返回 filecabinet
和 listpage
条目:
GET /feeds/content/domainName/siteName?kind=filecabinet,listpage
或者,您也可以为 Google 数据 /-/category
查询使用标准格式,而不是使用 kind
参数:
GET /feeds/content/domainName/siteName/-/filecabinet|listpage
检索页面模板
以下示例仅返回 template
网页:
GET /feeds/content/domainName/siteName/-/template
如需返回所有条目类型并包含 template
页面,请使用:
GET /feeds/content/domainName/siteName/-/template|-template
按路径检索页面
如果您知道 Google 协作平台中某个网页的相对路径,可以使用 path
参数抓取该特定网页。
以下示例将返回位于 http://sites.google.com/site/siteName/path/to/the/page
的网页:
GET /feeds/content/domainName/siteName?path=/path/to/the/page
检索父页面下的所有条目
如果您知道页面的条目 ID,则可以使用 parent
参数获取该页面的所有子条目(如果有):
GET /feeds/content/domainName/siteName?parent=CONTENT_ENTRY_ID
包含草稿或已删除的条目
如需添加草稿条目或已删除的条目,请分别使用 include-drafts
或 include-deleted
参数。此示例包含内容 Feed 中的草稿条目:
GET /feeds/content/domainName/siteName?include-drafts=true
全文搜索
如需搜索网站的全部内容,请使用 q
参数执行全文搜索:
GET /feeds/content/domainName/siteName?q=Text%20I%20am%20looking%20for
创建内容
通过向内容 Feed 发送 HTTP POST
,可以创建新内容(网页、列表页、文件箱式页面、公告页等):
https://sites.google.com/feeds/content/domainName/siteName
如需查看支持的条目类型的列表,请参阅参考指南中的 kind
参数。
创建新内容 / 页面
下例在网站的顶级位置下创建一个新的 webpage
,为网页正文添加一些 XHTML,并将标题标题设置为“New WebPage Title”:
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 328 Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <title>New Webpage Title</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">HTML body goes here</div> </content> </entry>
如果成功,服务器将返回 201 Created
以及该条目的副本。
在自定义网址路径下创建项/网页
默认情况下,上一个示例将在网址 http://sites.google.com/domainName/siteName/new-webpage-title
下创建,页面标题为“New Webpage Title”。也就是说,对于网址的 <atom:title>
标准化为 new-webpage-title
。若要自定义网页的网址路径,您可以设置 <sites:pageName>
元素。
此示例创建了一个页面标题为“File Storage”的新 filecabinet
,但在网址 http://sites.google.com/domainName/siteName/files
下通过指定 <sites:pageName>
元素创建了该页面。
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 393 Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom" xmlns:sites="http://schemas.google.com/sites/2008"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#filecabinet" label="filecabinet"/> <title>File Storage</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">A list of files is below.</div> </content> <sites:pageName>files</sites:pageName> </entry>
服务器使用以下优先规则为网页网址路径命名:
<sites:pageName>
(如果存在)。必须满足a-z, A-Z, 0-9, -, _
。- 如果 pageName 不存在,
<atom:title>
不得为 null。标准化是将空格修剪 + 收起为“-”,并移除与a-z, A-Z, 0-9, -, _
不匹配的字符。
例如,服务器可接受“Custom_Page2”。
创建子页面
如需在父页面下创建子页面(子页面),请在新的 Atom 条目中添加 <link rel="http://schemas.google.com/sites/2008#parent">
。将链接的 href
属性设置为父条目的自链接。
此示例在条目 ID 为 PARENT_ENTRY_ID
的父公告页面下创建了一个标题为“announcement”的新 announcement
。网页正文的 XHTML 内容也包含在内:
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 470 Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#announcement" label="announcement"/> <link rel="http://schemas.google.com/sites/2008#parent" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/PARENT_ENTRY_ID"/> <title>announcement</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">This weekend. My place.</div> </content> </entry>
页面模板
创建页面模板
创建页面模板的过程与创建新项/页面和创建子页面的过程相同。不同之处在于添加 category
,并将术语和标签分别设置为“http://schemas.google.com/g/2005#template”和“template”。
本示例将创建一个新的 webpage
模板。
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 464 Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom" xmlns:sites="http://schemas.google.com/sites/2008"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <category scheme="http://schemas.google.com/g/2005#labels" term="http://schemas.google.com/g/2005#template" label="template"/> <title>Webpage Template</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">This weekend. My place.</div> </content> </entry>
通过模板创建页面
与创建页面模板类似,您可以通过添加 <link>
并使 rel='http://schemas.google.com/sites/2008#template' 指向页面模板的 self 链接,从而通过模板实例化新页面。
本示例通过现有的页面模板创建了一个新的 filecabinet
页面,该模板定义了一个文件箱式页面。
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 464 Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom" xmlns:sites="http://schemas.google.com/sites/2008"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#filecabinet" label="filecabinet"/> <title>File Cabinet Page From Template</title> <link rel='http://schemas.google.com/sites/2008#template' type='application/atom+xml' href='https://sites.google.com/feeds/content/domainName/siteName/ENTRY_ID'/> </entry>
请注意:尽管有一个模板定义了 <category>
,但仍需要在条目中添加一个。另请注意,如果您添加 <content>
元素,服务器将拒绝该元素。
上传文件
与在 Google 协作平台中一样,API 允许您将附件上传到文件箱式页面和父页面。
要将附件上传到父级文件夹,请向内容 Feed 网址发送 HTTP POST
请求:
https://sites.google.com/feeds/content/domainName/siteName
POST
正文应该是 MIME 多部分请求,以便将文件内容与包含附件元数据的 <atom:entry>
合并。<atom:entry>
应引用父条目的自链接,以便指定创建连接的位置。如需了解详情,请参阅创建子页面。
正在上传附件
以下是将 PDF 文件上传到 ID 为 PARENT_ENTRY_ID
的文件柜式页面的示例。系统将创建连接,标题为“PDF File”且标题为“HR packet”(可选)说明。
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 7221984 Content-Type: multipart/related; boundary=END_OF_PART --END_OF_PART Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#attachment" label="attachment"/> <link rel="http://schemas.google.com/sites/2008#parent" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/PARENT_ENTRY_ID"/> <title>PDF File</title> <summary>HR packet</summary> </entry> --END_OF_PART Content-Type: application/pdf ... pdf contents here ... --END_OF_PART--
如果上传成功,服务器将使用 201 Created
和新创建的附件条目的副本进行响应。
将附件上传到文件夹中
如需将附件上传到 filecabinet
中的现有文件夹,请添加一个类别,并将“term”属性设为文件夹的名称:
<category scheme="http://schemas.google.com/sites/2008#folder" term="FolderName">
网络附件
网络附件是一种特殊类型的附件。实质上,它们是指向网络上的其他文件的链接,您可以将这些文件添加到文件箱式列表中。此功能类似于 Google 协作平台界面中的“通过网址添加文件”上传方法。
注意:网络附件只能在文件箱式页面下创建。不能上传到其他类型的网页。
此示例在 ID FILECABINET_ENTRY_ID
引用的文件箱下创建了一个 webattachment
。其标题和(可选)说明分别设置为“GoogleLogo”和“nice colors”。
POST /feeds/content/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Type: application/atom+xml Content-Length: 531 <entry xmlns="http://www.w3.org/2005/Atom"> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webattachment" label="webattachment"/> <link rel="http://schemas.google.com/sites/2008#parent" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/FILECABINET_ENTRY_ID"/> <title>GoogleLogo</title> <summary>nice colors</summary> <content type="image/gif" src="http://www.google.com/images/logo.gif"></content> </entry>
POST
会在用户的文件箱式页面中创建一个指向“http://www.google.com/images/logo.gif”图片的链接。
更新内容
只需向 edit
链接发出一个 PUT
请求,即可修改任何页面的元数据(标题、pageName 等)和网页内容。
请求正文应包含描述已更新页面的 Atom 条目。此规则的例外情况是附件条目,此类条目只能用于更新附件的元数据。
如需更改附加文件的内容,只需将原始数据作为 PUT
请求的正文添加到附件的 edit-media
链接中即可。您还可以使用 MIME 多部分请求一次更新元数据和附加的文件内容。
要断言您的更新不会覆盖其他客户端的更改,请包含原始条目的 ETag 值。为此,您可以在 HTTP If-Match
标头中提供 ETag 值,也可以在更新的条目中添加原始条目的 gd:etag
属性。如需确定原始条目的 ETag 值,请检查 <entry>
元素的 gd:etag
属性。对于媒体条目,媒体的 ETag 可以在 edit-media
链接的 gd:etag
属性中使用。
如果您希望更新该条目,而不管自您检索以来是否有其他人更新了该条目,请使用 If-Match: *
且不要包含 ETag。如需详细了解 ETag,请参阅 Google 数据 API 参考指南。
更新作品的元数据或 HTML 内容
如需更新条目的元数据或 HTML 内容,请向该条目的 edit
链接发送 HTTP PUT
。
以下是通过以下更改更新 listpage
条目(由其 ID ENTRY_ID
表示)的示例:
- 标题已修改为“内容更新”
- 更新后的 HTML 内容
- 列表的第一个列标题更新为“所有者”
- 网页的网址路径被
<sites:pageName>
元素修改了
PUT /feeds/content/domainName/siteName/ENTRY_ID Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 816 Content-Type: application/atom+xml <entry xmlns="http://www.w3.org/2005/Atom" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:gd="http://schemas.google.com/g/2005" gd:etag="W/"CEEBRn0ymA9WxJWEUw.""> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#listpage" label="listpage"/> <title>Updated Title</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">Updated Content</div> </content> <gs:worksheet name="listpage"/> <gs:header row="1"/> <gs:data startRow="2"> <gs:column index="A" name="Owner"/> <gs:column index="B" name="Decription"/> <gs:column index="C" name="Completed"/> </gs:data> <sites:pageName>newPagePath</sites:pageName> </entry>
注意:条目(由服务器返回)包含的元素将比上述示例更多。
替换附件的内容
以下是替换附件内容,但保持其元数据不变的示例。由于请求包含新内容,因此系统将使用附件条目的 edit-media
链接。
PUT /feeds/media/content/domainName/siteName/ATTACHMENT_ENTRY_ID Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Length: 70581 Content-Type: application/msword ... doc contents here ...
更新附件元数据和内容
以下是同时更新附件的元数据及其内容的示例。附件名称将更新为“新标题”,其内容将替换为 .zip 文件的内容。由于请求包含新的文件内容,因此将使用附件条目的 edit-media
链接。
请注意,为元数据添加 ETag 也会为媒体内容提供隐式 If-Match
,因为对媒体内容的任何更新都会导致元数据的 ETag 发生变化。
PUT /feeds/media/content/domainName/siteName/ATTACHMENT_ENTRY_ID Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> Content-Type: multipart/related; boundary="END_OF_PART" --END_OF_PART Content-Type: application/atom+xml <?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="BxAaTxRZAyp7ImBq"> <link rel="http://schemas.google.com/sites/2008#parent" type="application/atom+xml" href="https://sites.google.com/feeds/content/domainName/siteName/ATTACHMENT_ENTRY_ID"/> <title>New Title</title> </entry> --END_OF_PART Content-Type: application/zip ... zip contents here ... --END_OF_PART
正在删除内容
如需从 Google 网站中移除某个条目,请先检索该条目,然后向该条目的 edit
网址发送 DELETE
请求。此网址就是更新作品的元数据或 HTML 内容时使用的网址。
DELETE /feeds/content/domainName/siteName/ENTRY_ID Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> If-Match: <ETag or * here>
如果条目已成功删除,服务器会返回 HTTP 200 OK
响应。
如果条目在检索后被其他客户端更改,如果要确保不会删除该条目,请添加一个 HTTP If-Match
标头,该标头包含原始条目的 ETag 值。您可以通过检查 <entry>
元素的 gd:etag
属性来确定原始条目的 ETag 值。
如果您希望删除该条目,而不管自您检索以来是否有其他人更新了该条目,请使用 If-Match: *
且不要包含 ETag。(在这种情况下,您无需在删除条目前对其进行检索。)
如需详细了解 ETag,请参阅 Google Data API 参考指南。
正在下载附件
有了附件条目后,您可以通过向该条目的 <content>
src 链接发送经过身份验证的 HTTP GET
来下载文件。PDF 的内容链接示例:
<content type="application/pdf" src="http://502377765-a-google-com-s-sites.googlegroups.com/feeds/media/content/domainName/siteName/678942036"/>
ACL 供稿
共享权限 (ACL) 概览
ACL Feed 中的每个 ACL 条目都代表特定实体的一个访问角色,可以是一个用户、一组用户、一个网域,也可以是默认访问权限(即公共网站)。系统仅针对具有明确访问权限的实体显示条目 - 在 Google 协作平台界面共享屏幕的“有访问权限的人”面板中,每个电子邮件地址会显示一个条目。因此,系统不会显示网域管理员,即使他们具有对网站的隐式访问权限。
角色
角色元素表示实体可以拥有的访问权限级别。gAcl:role
元素有四个可能的值:
- reader - 查看者(等同于只读访问权限)。
- writer - 协作者(相当于读取/写入权限)。
- owner - 通常是网站管理员(相当于读/写权限)。
作用域
作用域元素表示拥有此访问权限级别的实体。gAcl:scope
元素有五种可能的类型:
- user - 电子邮件地址值,例如“user@gmail.com”。
- group - Google 群组电子邮件地址,例如“group@domain.com”。
- domain - G Suite 域名,例如“domain.com”。
- invite - 受邀访问网站,但尚未添加到网站的 ACL 中的用户。(如果指定了 gdata 1.3 或更低版本,则该属性不可用。)
- default - 只能有一个“default”类型的范围,该范围没有值(例如
<gAcl:scope type="default">
)。此特定范围用于控制任何用户在公开网站上默认拥有的访问权限。
注意:网域不能将 gAcl:role
值设为“所有者”访问权限,它们只能是读取者或写入者。
关于“邀请”范围。
当您向 ACL 添加一位或多位尚未拥有 Google 账号的用户时,API 会返回邀请范围。此 API 会返回包含嵌入式令牌的网址,您必须向受邀用户提供该令牌,才能允许他们接受邀请。
通过这种邀请方式,您可以邀请非 Google 用户,而无需事先知道他们想要使用的电子邮件地址。只要用户点击带有嵌入令牌的邀请网址,他们就可以使用所需的任何电子邮件地址进行注册以获取访问权限。此外,多个用户可以使用此网址来接受邀请,因此这在邀请一个用户或一组用户时很有用。
注意:“邀请”范围仅适用于 gdata 版本 1.4 及更高版本。如果您明确指定 1.3 或更低版本,则无法执行此操作。
检索 ACL 供稿
ACL 供稿可用于控制网站的共享权限,并可通过以下 URI 访问:
https://sites.google.com/feeds/acl/site/domainName/siteName
Feed 参数 | 说明 |
---|---|
domainName | “site ”或您的 G Suite 托管域名(例如 example.com )的域名。 |
siteName | 您网站的网络空间名称;可在网站的网址中找到(例如 myCoolSite )。 |
请注意,网站 Feed 中的每个条目都包含指向该 Feed 的链接:
<link rel="http://schemas.google.com/acl/2007#accessControlList" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName"/>
要检索网站的共享权限,请向 ACL 供稿 URI 发送 HTTP GET
:
GET /feeds/acl/site/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here>
服务器将使用 200 OK
和 ACL 条目的 Feed 进行响应:
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:gAcl="http://schemas.google.com/acl/2007" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006" xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0"> <id>https://sites.google.com/feeds/acl/site/domainName/siteName</id> <updated>2009-12-03T22:01:05.963Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/acl/2007#accessRule"/> <title>Acl</title> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName"/> <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName"/> <generator version="1" uri="http://sites.google.com">Google Sites</generator> <openSearch:startIndex>1</openSearch:startIndex> <entry> <id>https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserA%40gmail.com</id> <updated>2009-12-03T22:01:05.963Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-03T22:01:05.963Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/acl/2007#accessRule"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserA%40google.com"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserA%40google.com"/> <gAcl:scope type="user" value="userA@google.com"/> <gAcl:role value="owner"/> </entry> <entry> <id>https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserB%40gmail.com</id> <updated>2009-12-03T22:01:05.963Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-03T22:01:05.963Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/acl/2007#accessRule"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserB%40gmail.com"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserB%40gmail.com"/> <gAcl:scope type="user" value="userB@gmail.com"/> <gAcl:role value="writer"/> </entry> <entry> <id>https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserC%40gmail.com</id> <updated>2009-12-03T22:01:05.963Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-03T22:01:05.963Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/acl/2007#accessRule"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserC%40gmail.com"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3AuserC%40gmail.com"/> <gAcl:scope type="user" value="userC@gmail.com"/> <gAcl:role value="reader"/> </entry> ... </feed>
共享网站
ACL Feed 接受 GET
、POST
和 PUT
请求。要在 ACL Feed 中插入新角色,只需向网站的 ACL Feed 发出 POST
请求即可。
注意:某些共享 ACL 可能仅在网域配置为允许此类权限的情况下才能使用(例如,如果针对 G Suite 网域启用了与网域外用户共享内容的功能等)。
此示例向网站添加了一位新协作者(作者):
POST /feeds/acl/site/domainName/siteName HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'> <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/> <gAcl:role value='writer'/> <gAcl:scope type='user' value='new_writer@example.com'/> </entry>
成功插入后,系统会返回 201 Created
和新条目:
<entry> <id>https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_writer%40example.com</id> <updated>2009-12-03T22:01:05.963Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-03T22:01:05.963Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/acl/2007#accessRule"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_writer%40example.com"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_writer%40example.com"/> <gAcl:role value='writer'/> <gAcl:scope type='user' value='new_writer@example.com'/> </entry>
通过“邀请”范围邀请用户
如果您添加的用户没有 Google 帐号,该 API 会返回一个网址,您必须向要邀请的用户提供该网址。用户点击该网址后,即可通过现有帐号登录或创建新帐号来访问相应网站。
成功的邀请会返回 201 Created
和一个新条目,其中包含您必须传递给用户的网址:
<entry> <id>https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_invite%40example.com</id> <updated>2009-12-03T22:01:05.963Z</updated> <app:edited xmlns:app="http://www.w3.org/2007/app">2009-12-03T22:01:05.963Z</app:edited> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/acl/2007#accessRule"/> <link rel="http://schemas.google.com/sites/2008#invite" type="text/html"href="domainName/siteName?invite=inviteToken"/> <link rel="self" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_invite%40example.com"/> <link rel="edit" type="application/atom+xml" href="https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_invite%40example.com"/> <gAcl:role value='writer'/> <gAcl:scope type='invite' value='new_invite%40example.com'/> </entry>
群组和网域级共享
与与单个用户共享网站类似,您可以在 Google 群组或 G Suite 网域之间共享网站。下面列出了必要的 scope
值。
共享至群组电子邮件地址:
<gAcl:scope type="group" value="group@example.com"/>
与整个网域共享:
<gAcl:scope type="domain" value="example.com"/>
只有 G Suite 网域以及托管网站的网域支持网域级共享。例如,http://sites.google.com/a/domain1.com/siteA 只能与 domain1.com 共享整个网站,而不能与 domain2.com 共享。不是在 G Suite 网域(如 http://sites.google.com/site/siteB)上托管的网站无法邀请网域。
修改共享权限
如需更新 ACL 条目,请根据需要修改该条目,并向该条目的 edit
链接发出 HTTP PUT
请求,该链接只是一个 <link>
元素,其“rel”属性设为“edit”。在前面的示例中,该链接为:
<link rel='edit' type='application/atom+xml' href='https://sites.google.com/feeds/acl/site/domainName/siteName/user%3Anew_writer%40example.com'/>
以下代码段将 new_writer@gmail.com
的角色更改为“reader”:
PUT /feeds/acl/site/domainName/siteName/user%3Anew_writer%40example.com HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'> <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/> <gAcl:role value='reader'/> <gAcl:scope type='user' value='new_writer@gmail.com'/> </entry>
正在移除共享权限
如需移除此用户的权限,请向用于 PUT
请求的同一 edit
关联发出 DELETE
请求:
DELETE /feeds/acl/site/domainName/siteName/user%3Anew_writer%40example.com HTTP/1.1 Host: sites.google.com GData-Version: 1.4 Authorization: <your authorization header here>
服务器将使用 200 OK
进行响应。
特殊主题
再次检索 Feed 或条目
如果要检索之前检索到的 Feed 或条目,您可以告知服务器仅在自上次检索以来发生了更改时才发送列表或条目,从而提高效率。
如需执行此类条件检索,请发送包含 HTTP If-None-Match
标头的 HTTP GET
请求。在标头中,指定列表或条目的 ETag(可在 <feed>
元素或 <entry>
元素的 gd:etag
属性中找到)。
使用网站 Feed 的示例:
GET /feeds/site/domainName/myOtherTestSite/ GData-Version: 1.4 If-None-Match: W/"Ck8GQXk7fil7ImA9WxNSFk0."
当服务器收到此请求时,它会检查您请求的项是否具有与您指定的 ETag 相同的 ETag。如果 ETag 匹配,则内容尚未更改,并且服务器会返回 HTTP 304 Not Modified
状态代码或 HTTP 412 Precodition Failed
状态代码。这两个状态代码都表示您已检索的项目为最新。
如果 ETag 不匹配,则表示自您上次请求以来该项已经过修改,服务器会返回该项。
如需详细了解 ETag,请参阅 Google Data API 参考指南。
批处理
批量请求让您的客户端能够在一个请求中执行多项操作,而不必单独提交每项操作。
服务器将执行尽可能多的请求的更改,并返回状态信息,您可以使用该信息来评估每项操作是成功还是失败。如需详细了解 Google Data API 中的批处理,请参阅使用 Google Data API 进行批处理
批量 Feed 中的每项操作都有一个 <id> 元素,插入操作除外。此元素与您在更新、删除或查询内容 Feed 时通常会使用的请求网址相同。
例如,如果要更新修改,请将相关条目的 <id> 设置为 edit
链接。
用于标识目标条目。新条目不含 <id> 元素,因为它们尚未创建。您可以在 <batch:id> 中定义一个字符串值,该值将在服务器的响应中返回,并用于查找相应的条目。
要发出批量请求,请构造批量 Feed 并将 HTTP POST
发送到 Feed 的批量链接:
<link rel="http://schemas.google.com/g/2005#batch" type="application/atom+xml" href="https://sites.google.com/feeds/content/site/siteName/batch"/>
以下示例展示了如何查询、插入、更新和删除网页条目:
POST /feeds/content/site/siteName/batch HTTP/1.1 Host: sites.google.com Accept: */* If-Match: * GData-Version: 1.4 Authorization: <your authorization header here> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gd="http://schemas.google.com/g/2005" xmlns:batch='http://schemas.google.com/gdata/batch'> <entry> <id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID1</id> <batch:operation type="query"/> </entry> <entry> <batch:id>1</batch:id> <batch:operation type='insert'/> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <title>New Webpage1</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">HTML body goes here</div> </content> </entry> <entry gd:etag=""YDgpeyI.""> <id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID2</id> <batch:operation type='update'/> <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/> <title>Updated Title for Webpage2</title> ... <batch:operaation type="update"/> </entry> <entry gd:etag=""YassseyI.""> <id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID3</id> <batch:operation type='delete'/> </entry> </feed>
对于每项操作,返回的 Feed 都会包含一个结果条目:
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:sites="http://schemas.google.com/sites/2008" xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:dc="http://purl.org/dc/terms" xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gd="http://schemas.google.com/g/2005" xmlns:thr="http://purl.org/syndication/thread/1.0">
<id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID1</id>
<updated>2009-11-10T22:44:08.369Z</updated>
<title>Batch Feed</title>
<entry gd:etag=""YDgpsdfeyI."">
<id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID1</id>
<published>2009-08-31T04:42:45.251Z</published>
<updated>2009-10-25T22:46:13.729Z</updated>
<app:edited xmlns:app="http://www.w3.org/2007/app">2009-10-25T22:46:13.671Z</app:edited>
<category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/sites/2008#webpage" label="webpage"/>
<title>Page Title</title>
...
<batch:status code="200" reason="Success"/>
<batch:operation type="query"/>
</entry>
<entry gd:etag=""YDsseyI."">
<id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID4</id>
<published>2009-11-10T22:44:08.531Z</published>
<updated>2009-11-10T22:44:08.560Z</updated>
<app:edited xmlns:app="http://www.w3.org/2007/app">2009-11-10T22:44:08.531Z</app:edited>
<category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/sites/2008#webpage" label="webpage"/>
<title>New Webpage1</title>
<content type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml">
<table cellspacing="0" class="sites-layout-name-one-column sites-layout-hbox">
<tbody>
<tr>
<td class="sites-layout-tile sites-tile-name-content-1">
<div>HTML body goes here</div>
</td>
</tr>
</tbody>
</table>
</div>
</content>
...
<batch:id>1</batch:id>
<batch:status code="201" reason="Created"/>
<batch:operation type="insert"/>
</entry>
<entry gd:etag=""YDkpeyI."">
<id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID2</id>
<updated>2009-11-10T22:44:09.296Z</updated>
<title>Updated Title for Webpage2</title>
...
<sites:pageName>updated-title-for-webpage2</sites:pageName>
<sites:revision>5</sites:revision>
<batch:status code="200" reason="Success"/>
<batch:operation type="update"/>
</entry>
<entry>
<id>https://sites.google.com/feeds/content/site/siteName/ENTRY_ID3</id>
<title>Deleted</title>
<content>Deleted</content>
<batch:status code="200" reason="Success"/>
<batch:operation type="delete"/>
</entry>
</feed>