借助传统版 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 Sites Data API 的 OAuth 2.0 范围信息:
https://sites.google.com/feeds/
要通过 OAuth 2.0 请求访问权限,您的应用既需要授权范围信息,也需要 Google 在您注册应用时提供的信息(如客户端 ID 和客户端密钥)。
指定版本
您向 Google Sites Data 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
下创建一个采用“slate”主题的新 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 网域版网站包含类别元数据,这些元数据有助于对网域中的网站进行分类。如需添加或更新类别元数据,请向包含 category
标记的网站条目的 edit
链接发送 HTTP PUT
。请参阅以下示例中的粗体线:
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 协作平台网站。例如,可以使用 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
。例如,在上面的示例中,有三个 webAddressMapping
指向网站 http://sites.google.com/site/myOtherTestSite
。
修改网址映射
注意:处理网址映射时,所有 GET/POST/PUT 操作都应指定 with-mappings=true
参数。如果该参数不存在,则网站条目中将不会返回 webAddressMapping
(GET),也不会在更新/移除 (PUT) 条目的映射时考虑该参数。
如需添加、更新或删除映射,只需在创建新网站或更新网站的元数据时指定、更改或移除此类链接即可。网站 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 )。 |
如需查找给定网页/评论/附件/列表项的修订链接,请先使用其 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 会列出网站的当前内容。向以下网址发送经过身份验证的 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 数据协议参考文档。下面介绍了对传统 Sites 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 标准查询参数以及传统版 Sites 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>
元素。
此示例会创建一个页面标题为“文件存储空间”的新 filecabinet
,但通过指定 <sites:pageName>
元素,将该页面创建在网址 http://sites.google.com/domainName/siteName/files
下。
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, -, _
。<atom:title>
,如果未提供 pageName,则不得为 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
。页面正文的 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>
通过模板创建页面
与创建页面模板类似,您可以通过添加一个 rel='http://schemas.google.com/sites/2008#template' 指向页面模板的自链接的 <link>
,从模板中实例化新页面。
本示例会根据定义文件箱式页面的现有页面模板创建新的 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>
,但您仍需要在条目中添加一个 <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 文件”且具有(可选)说明“人力资源文件包”的附件。
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">
Web 附件
网页附件是一种特殊的附件。本质上,它们是指向网络上其他文件的链接,您可以将这些链接添加到文件柜商家信息中。此功能类似于 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 条目。此规则的例外情况是附件条目,其中条目只能用于更新附件的元数据。如需更改附加文件的内容,只需将原始数据作为对附件 edit-media
链接的 PUT
请求的正文添加即可。您还可以使用 MIME 多部分请求同时更新元数据和附加的文件内容。
如需断言您的更新不会覆盖其他客户端的更改,请添加原始条目的 ETag 值。为此,您可以在 HTTP If-Match
标头中提供 ETag 值,也可以在更新后的条目中添加原始条目的 gd:etag
属性。如需确定原始条目的 ETag 值,请检查 <entry>
元素的 gd:etag
属性。对于媒体条目,媒体的 ETag 可能在 edit-media
链接的 gd:etag
属性中提供。
如果您希望更新条目,而不管自您检索以来是否有其他人更新过该条目,请使用 If-Match: *
并且不要包含 ETag。如需详细了解 ETag,请参阅 Google Data 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 中的用户。(如果指定了 达 1.3 或更低版本,则无法使用此属性。)
- default - 只有一个可能的“default”类型范围,该范围没有值(例如
<gAcl:scope type="default">
)。此特定范围用于控制任何用户在公共网站上默认拥有的访问权限。
注意:网域的 gAcl:role
值不能设置为“所有者”访问权限,只能是读取器或写入器。
“invite”范围简介。
当您向 ACL 中添加一个或多个尚无 Google 账号的用户时,该 API 会返回邀请范围。该 API 会返回一个包含嵌入式令牌的网址,您必须向受邀用户提供该网址,以便他们接受邀请。
通过这种邀请方式,您可以在事先了解非 Google 用户要使用的电子邮件地址的情况下邀请他们。只要用户点击带有嵌入式令牌的邀请网址,他们就可以使用自己想要的任何电子邮件地址注册访问。此外,多个用户都可能使用此网址接受邀请,因此,如果要邀请一位用户或一组用户,此方法会很有用。
注意:“invite”范围仅在 1.4 版及更高版本中可用。如果您明确指定了 1.3 或更低版本,则此方法不起作用。
检索 ACL 供稿
ACL Feed 可用于控制网站的共享权限,可通过以下 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"/>
要检索网站的共享权限,请将 HTTP GET
发送到 ACL 供稿 URI:
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 供稿接受 GET
、POST
和 PUT
请求。如需将新角色插入 ACL Feed,只需向网站的 ACL Feed 发出 POST
请求即可。
注意:仅当网域配置为允许此类权限时(例如,如果为 G Suite 网域启用了与网域外部用户共享的功能等),才能使用某些共享 ACL。
以下示例向网站添加了新的协作者(作者):
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>
通过“invite”范围邀请用户
如果您添加的用户没有 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 或条目,可以提高效率,方法是指示服务器仅在相应列表或条目自上次检索后发生变化时才发送。
如需执行此类条件式检索,请发送包含 HTTP If-None-Match
标头的 HTTP GET
请求。在标头中,指定列表或条目的 ETag,您可以在 <feed>
元素或 <entry>
元素的 gd:etag
属性中找到该 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 并向 Feed 的批量链接发送 HTTP POST
:
<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>