Python 指南

重要提示:本文档是在 2012 年之前撰写的。本文档中所述的身份验证选项(OAuth 1.0、AuthSub 和 CMEK)自 2012 年 4 月 20 日起已被正式弃用,不再提供。我们建议您尽快迁移到 OAuth 2.0

通过 Google 协作平台数据 API,客户端应用可以在 Google 协作平台内访问、发布和修改内容。 您的客户端应用还可以请求近期活动列表、提取修订历史记录以及下载附件。

除了介绍一些有关协作平台数据 API 功能的背景信息外,本指南还提供了使用 Python 客户端库与该 API 进行交互的示例。如需有关设置客户端库的帮助,请参阅 Google 数据 Python 客户端库使用入门。如果您有兴趣详细了解 Python 客户端库与传统版 协作平台 API 进行交互时使用的底层协议,请参阅协议指南

受众群体

本文档适用于想要使用 Google 数据 Python 客户端库编写与 Google 协作平台进行交互的客户端应用的开发者。

开始使用

要使用 Python 客户端库,您需要安装 Python 2.2 及更高版本以及 DependencyModules Wiki 页面上列出的模块。下载客户端库后,请参阅 Google 数据 Python 库使用入门,获取有关安装和使用客户端的帮助。

运行示例

完整的有效示例位于项目的 Mercurial 代码库 (/samples/sites/sites_example.py) 的 samples/sites 子目录中。

运行示例,如下所示:

python sites_example.py
# or
python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]

如果未提供必需的标志,应用会提示您输入这些值。通过该示例,用户可以执行许多操作,演示如何使用传统版 协作平台 API。因此,您需要通过身份验证才能执行某些操作(例如修改内容)。该程序还会提示您通过 AuthSubOAuthClientLogin 进行身份验证。

如需将本指南中的示例添加到您自己的代码中,您需要使用以下 import 语句:

import atom.data
import gdata.sites.client
import gdata.sites.data

您还需要设置 SitesClient 对象,该对象表示与传统版 协作平台 API 的客户端连接。 传入您的应用程序名称和网站网络空间名称(来自其网址):

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')

如要使用在 G Suite 网域上托管的网站,请使用 domain 参数设置网域:

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')

在上面的代码段中,source 为可选参数,但为了记录日志,建议使用该参数。它应遵循以下格式:company-applicationname-version

注意:本指南的其余部分假定您在变量 client 中创建了一个 SitesClient 对象。

使用传统版协作平台 API 进行身份验证

Python 客户端库可用于处理公共 Feed 或私有 Feed。协作平台 Data API 支持访问不公开 Feed 和公开 Feed,具体取决于网站的权限以及您尝试执行的操作。例如,您可能可以读取公开网站的内容 Feed,但不能更新它,而这需要一个经过身份验证的客户端。这可以通过 ClientLogin 用户名/密码身份验证、AuthSubOAuth 完成。

请参阅 Google 数据 API 身份验证概览,了解有关 AuthSub、OAuth 和 CMEK 的详细信息。

用于网络应用程序的 AuthSub

如果客户端应用需要向 Google 或 G Suite 帐号验证其用户身份,则应使用适用于 Web 应用的 AuthSub 身份验证。运营商不需要访问 Google 协作平台用户的用户名和密码,只需 AuthSub 令牌即可。

查看关于将 AuthSub 整合到您的 Web 应用的说明

请求一次性令牌

用户首次访问您的应用时,需要进行身份验证。通常,开发者会输出一些文本和一个链接,用于将用户引导至 AuthSub 批准页面,以对用户进行身份验证并请求访问其文档。Google 数据 Python 客户端库提供了 generate_auth_sub_url() 函数来生成此网址。以下代码设置了指向 AuthSubRequest 页面的链接。

import gdata.gauth

def GetAuthSubUrl():
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session)

print '<a href="%s">Login to your Google account</a>' % GetAuthSubUrl()

如果您要对 G Suite 托管网域中的用户进行身份验证,请将域名传递给 generate_auth_sub_url()

def GetAuthSubUrl():
  domain = 'example.com'
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session, domain=domain)

generate_auth_sub_url() 方法接受多个参数(对应于 AuthSubRequest 处理程序使用的查询参数):

  • next 网址 - 用户登录帐号并授予访问权限后 Google 将重定向到的网址;上例中的 http://www.example.com/myapp.py
  • 范围 - https://sites.google.com/feeds/
  • secure:一个布尔值,表示是否要在安全和注册模式下使用令牌;上述示例中的 True
  • session,第二个布尔值,用于指明稍后是否将一次性令牌交换为会话令牌;上述示例中的 True

升级为会话令牌

请参阅将 AuthSub 与 Google Data API 客户端库搭配使用

检索有关会话令牌的信息

请参阅将 AuthSub 与 Google Data API 客户端库搭配使用

撤消会话令牌

请参阅将 AuthSub 与 Google Data API 客户端库搭配使用

提示:您的应用成功获取长期会话令牌后,请将该令牌存储在数据库中,以供日后使用。无需在每次运行应用时将用户发送回 AuthSub。使用 client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) 在客户端上设置现有令牌。

适用于 Web 应用或已安装/移动应用的 OAuth

OAuth 可用作 AuthSub 的替代方案,适用于 Web 应用。OAuth 类似于使用 AuthSub 安全和注册模式,因为所有数据请求都必须进行数字签名,并且您必须注册自己的网域。

查看关于将 OAuth 加入到已安装的应用的说明

提取请求令牌

请参阅将 OAuth 与 Google Data API 客户端库配合使用

向请求令牌授权

请参阅将 OAuth 与 Google Data API 客户端库配合使用

升级为访问令牌

请参阅将 OAuth 与 Google Data API 客户端库配合使用

提示:您的应用成功获取 OAuth 访问令牌后,请将该令牌存储在数据库中,以备日后调用。每次运行应用时,无需通过 OAuth 将用户发回。 使用 client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) 在客户端上设置现有令牌。

已安装/移动应用的 CMEK

需要向 Google 帐号验证用户身份的已安装应用或移动应用应使用 ClientLogin。首次运行时,您的应用会提示用户输入其用户名/密码。在后续请求中,系统会引用身份验证令牌。

查看有关将 CMEK 合并到已安装的应用的说明

如需使用 ClientLogin,请调用 SitesClient 对象的 ClientLogin() 方法,该方法继承自 GDClient。指定您的客户端代表其发出请求的用户的电子邮件地址和密码。例如:

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1')
client.ClientLogin('user@gmail.com', 'pa$$word', client.source);

提示:您的应用在首次成功验证用户身份后,请将身份验证令牌存储在数据库中,以便在日后再次使用。您无需在每次运行应用时都提示用户输入密码。如需了解详情,请参阅撤回身份验证令牌

如需详细了解如何在 Python 应用中使用 CMEK,请参阅将 CMEK 与 Google Data API 客户端库配合使用

返回页首

网站 Feed

网站 Feed 可用于列出用户拥有或有权查看的 Google 网站。 它还可用于修改现有网站的名称。最后,对于 G Suite 网域,它还可用于创建和/或复制整个网站。

列出网站

如需列出用户有权访问的网站,请使用客户端的 GetSiteFeed() 方法。该方法接受一个可选参数 uri,您可以使用此参数来指定备用网站 Feed URI。默认情况下,GetSiteFeed() 会使用在客户端对象上设置的网站名称和网域。如需详细了解如何在客户端对象上设置这些值,请参阅使用入门部分。

以下示例展示了如何提取经过身份验证的用户的网站列表:

feed = client.GetSiteFeed()

for entry in feed.entry:
  print '%s (%s)' % (entry.title.text, entry.site_name.text)
  if entry.summary.text:
    print 'description: ' + entry.summary.text
  if entry.FindSourceLink():
    print 'this site was copied from site: ' + entry.FindSourceLink()
  print 'acl feed: %s\n' % entry.FindAclLink()
  print 'theme: ' + entry.theme.text

上面的代码段会输出网站的标题、网站名称、复制来源的网站及其 ACL Feed URI。

创建新网站

注意:此功能仅适用于 G Suite 网域。

您可以通过调用库的 CreateSite() 方法来配置新网站。与 GetSiteFeed() 帮助程序类似,CreateSite() 还接受可选参数 uri,此参数可用于指定备用网站 Feed URI(如果是在 SitesClient 对象中设置的网域之外的其他网域下创建网站)。

以下示例展示了如何使用主题“可选广告”创建新网站并提供标题和(可选)说明:

client.domain = 'example2.com'  # demonstrates creating a site under a different domain.

entry = client.CreateSite('Title For My Site', description='Site to hold precious memories', theme='slate')
print 'Site created! View it at: ' + entry.GetAlternateLink().href

上述请求会在 G Suite 网域 example2.com 下创建一个新网站。因此,该网站的网址将是 https://sites.google.com/a/example2.com/title-for-my-site。

如果网站成功创建,服务器将使用 gdata.sites.data.SiteEntry 对象进行响应,并在其中填充服务器添加的元素:指向网站的链接、指向网站的 acl Feed 的链接、网站名称、标题、摘要等等。

复制网站

注意:此功能仅适用于 G Suite 网域。

CreateSite() 还可用于复制现有网站。为此,请传入 source_site 关键字参数。被复制的所有网站都包含此链接,您可以通过 entry.FindSourceLink() 访问。以下示例展示了如何复制在创建新网站部分创建的网站:

copied_site = client.CreateSite('Copy of Title For My Site', description='My Copy', source_site=entry.FindSourceLink())
print 'Site copied! View it at: ' + copied_site.GetAlternateLink().href

要点:

  • 只能复制经过身份验证的用户拥有的网站和网站模板。
  • 也可以复制网站模板。如果在 Google 协作平台设置页面中选中了“将此网站发布为模板”设置,则相应网站就是模板。
  • 您可以从其他网域复制网站,但系统会将您列为源网站的所有者。

更新网站的元数据

如需更新网站的标题或摘要,您需要包含相关网站的 SiteEntry。此示例使用 GetEntry() 方法先获取 SiteEntry,然后更改其标题、说明和类别标记:

uri = 'https://sites.google.com/feeds/site/example2.com/title-for-my-site'
site_entry = client.GetEntry(uri, desired_class=gdata.sites.data.SiteEntry)

site_entry.title.text = 'Better Title'
site_entry.summary.text = 'Better Description'
category_name = 'My Category'
category = atom.data.Category(
    scheme=gdata.sites.data.TAG_KIND_TERM,
    term=category_name)
site_entry.category.append(category)
updated_site_entry = client.Update(site_entry)

# To force the update, even if you do not have the latest changes to the entry:
# updated_site_entry = client.Update(site_entry, force=True)

返回页首

获取活动供稿

注意:只有网站的协作者或所有者才能访问此 Feed。 您的客户端必须使用 AuthSub、OAuth 或 CMEK 令牌进行身份验证。请参阅在 Google 协作平台服务中进行身份验证

您可以通过提取活动 Feed 来获取网站的近期活动(更改)。 可以通过库的 GetActivityFeed() 方法访问此 Feed:

print "Fetching activity feed of '%s'...\n" % client.site
feed = client.GetActivityFeed()

for entry in feed.entry:
  print '%s [%s on %s]' % (entry.title.text, entry.Kind(), entry.updated.text)

调用 GetActivityFeed() 会返回一个包含 gdata.sites.data.ActivityEntry 列表的 gdata.sites.data.ActivityFeed 对象。每个活动条目都包含对网站所做更改的相关信息。

返回页首

正在获取修订历史记录

注意:只有网站的协作者或所有者才能访问此 Feed。 您的客户端必须使用 AuthSub、OAuth 或 CMEK 令牌进行身份验证。请参阅在 Google 协作平台服务中进行身份验证

修订 Feed 提供有关任何内容条目修订历史记录的信息。GetRevisionFeed() 方法可用于提取给定内容条目的修订版本。该方法采用可选的 uri 参数,该参数接受 gdata.sites.data.ContentEntry、内容条目的完整 URI 或内容条目 ID。

下例会查询内容供稿,并提取第一个内容条目的修订供稿:

print "Fetching content feed of '%s'...\n" % client.site
content_feed = client.GetContentFeed()
content_entry = content_feed.entry[0]

print "Fetching revision feed of '%s'...\n" % content_entry.title.text
revision_feed = client.GetRevisionFeed(content_entry)

for entry in revision_feed.entry:
  print entry.title.text
  print ' new version on:\t%s' % entry.updated.text
  print ' view changes:\t%s' % entry.GetAlternateLink().href
  print ' current version:\t%s...\n' % str(entry.content.html)[0:100]

调用 GetRevisionFeed() 会返回一个包含 gdata.sites.data.RevisionEntry 列表的 gdata.sites.data.RevisionFeed 对象。每个修订版本条目都包含该修订版本的内容、版本号以及新版本的创建时间等信息。

返回页首

内容 Feed

检索内容 Feed

注意:内容 Feed 可能需要进行身份验证,也可能不需要,具体取决于网站的共享权限。 如果网站是非公开的,您的客户端必须使用 AuthSub、OAuth 或 CMEK 令牌进行身份验证。请参阅向协作平台服务进行身份验证

内容 Feed 会返回某个网站的最新内容。您可以通过调用该库的 GetContentFeed() 方法来访问该库,该方法采用可选的 uri 字符串参数来传递自定义查询。

以下示例展示了如何获取整个内容 Feed 并输出一些有趣的元素:

print "Fetching content feed of '%s'...\n" % client.site
feed = client.GetContentFeed()

for entry in feed.entry:
  print '%s [%s]' % (entry.title.text, entry.Kind())

  # Common properties of all entry kinds.
  print ' content entry id: ' + entry.GetNodeId()
  print ' revision:\t%s' % entry.revision.text
  print ' updated:\t%s' % entry.updated.text

  if entry.page_name:
    print ' page name:\t%s' % entry.page_name.text

  if entry.content:
    print ' content\t%s...' % str(entry.content.html)[0:100]

  # Subpages/items will have a parent link.
  parent_link = entry.FindParentLink()
  if parent_link:
    print ' parent link:\t%s' % parent_link

  # The alternate link is the URL pointing to Google Sites.
  if entry.GetAlternateLink():
    print ' view in Sites:\t%s' % entry.GetAlternateLink().href

  # If this entry is a filecabinet, announcementpage, etc., it will have a feed of children.
  if entry.feed_link:
    print ' feed of items:\t%s' % entry.feed_link.href

  print

提示entry.Kind() 可用于确定条目的类型。

生成的 feed 对象是一个包含 gdata.sites.data.ContentEntry 列表的 gdata.sites.data.ContentFeed。每个条目代表用户网站内的一个不同网页/项目,并且包含针对该条目类型的特定元素。如需详细了解每种条目种类中提供的一些属性,请参阅示例应用

返回页首

内容 Feed 查询示例

您可以使用一些标准 Google Data API 查询参数以及传统版 协作平台 API 专用的查询参数来搜索内容 Feed。如需了解详情以及受支持参数的完整列表,请参阅参考指南

注意:本部分中的示例使用 gdata.sites.client.MakeContentFeedUri() 辅助方法构建内容 Feed 的基础 URI。

检索特定条目种类

如需仅提取特定类型的条目,请使用 kind 参数。例如,以下代码段仅返回 attachment 条目:

kind = 'webpage'

print 'Fetching only %s entries' % kind
uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind)
feed = client.GetContentFeed(uri=uri)

如需返回多个类型,请使用英文逗号分隔每个 kind。例如,以下代码段会返回 filecabinetlistpage 条目:

kind = ','.join(['filecabinet', 'listpage'])

print 'Fetching only %s entries' % kind
uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind)
feed = client.GetContentFeed(uri=uri)

按路径检索页面

如果您知道 Google 协作平台中某个网页的相对路径,可以使用 path 参数抓取该特定网页。 以下示例将返回位于 http://sites.google.com/domainName/siteName/path/to/the/page 的网页:

path = '/path/to/the/page'

print 'Fetching page by its path: ' + path
uri = '%s?path=%s' % (client.MakeContentFeedUri(), path)
feed = client.GetContentFeed(uri=uri)

检索父页面下的所有条目

如果您知道网页的内容条目 ID(例如下例中的“1234567890”),则可以使用 parent 参数获取该页面的所有子条目(如果有):

parent = '1234567890'

print 'Fetching all children of parent entry: ' + parent
uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent)
feed = client.GetContentFeed(uri=uri)

如需了解其他参数,请参阅参考指南

返回页首



创建内容

注意:在为网站创建内容之前,请确保您已在客户端中设置您的网站。
client.site = "siteName"

您可以使用 CreatePage() 创建新内容(网页、列表页、文件箱式页面、公告页等)。此方法的第一个参数应该是要创建的网页类型,其后是标题及其 HTML 内容。

如需查看受支持节点类型的列表,请参阅参考指南中的 kind 参数。

创建新内容 / 页面

此示例会在顶级目录下创建一个新的 webpage,为页面正文添加一些 XHTML,并将标题标题设置为“New WebPage Title”:

entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href

如果请求成功,entry 将包含服务器上创建的条目的副本,以 gdata.sites.gdata.ContentEntry 格式。

如需创建在创建时填充的更复杂的条目种类(例如带有列标题的 listpage),您需要手动创建 gdata.sites.data.ContentEntry,填写相关属性,然后调用 client.Post()

在自定义网址路径下创建项/网页

默认情况下,上一个示例将在网址 http://sites.google.com/domainName/siteName/new-webpage-title 下创建,页面标题为“New Webpage Title”。也就是说,网址的标题标准化为 new-webpage-title。 如需自定义页面的网址路径,您可以在内容条目上设置 page_name 属性。CreatePage() 帮助程序会将此参数作为可选的关键字参数提供。

此示例创建了一个标题为“File Storage”的新 filecabinet 页面,但通过指定 page_name 属性在网址 http://sites.google.com/domainName/siteName/files(而不是 http://sites.google.com/domainName/siteName/file-storage)下创建了该页面。

entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href

服务器使用以下优先规则为网页网址路径命名:

  1. page_name(如果存在)。必须满足 a-z, A-Z, 0-9, -, _
  2. 如果页面名称不存在,则 title 不得为 null。标准化是将空格修剪 + 收起为“-”,并移除与 a-z, A-Z, 0-9, -, _ 不匹配的字符。

创建子页面

如需在父页面下创建子页面(子页面),请使用 CreatePage()parent 关键字参数。 parent 可以是 gdata.sites.gdata.ContentEntry 或表示内容条目的完整自 ID 的字符串。

此示例查询的内容 Feed 以获取 announcementpage,并在找到的第一个 announcement 下创建一个新的 announcement

uri = '%s?kind=%s' % (client.MakeContentFeedUri(), 'announcementpage')
feed = client.GetContentFeed(uri=uri)

entry = client.CreatePage('announcement', 'Party!!', html='My place, this weekend', parent=feed.entry[0])
print 'Posted!'

上传文件

与在 Google 协作平台中一样,该 API 支持将附件上传到文件箱式页面或父页面。附件必须上传到父级页面。因此,您必须为尝试上传的 ContentEntry 设置父级链接。如需了解详情,请参阅创建子页面

客户端库的 UploadAttachment() 方法提供了用于上传附件的接口。

正在上传附件

此示例将 PDF 文件上传到用户内容 Feed 中的第一个 filecabinet 中。附件是标题为“New Employee Handbook”(新员工手册)和(可选)描述“HR packet”(人力资源包)创建的。

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet')
feed = client.GetContentFeed(uri=uri)

attachment = client.UploadAttachment('/path/to/file.pdf', feed.entry[0], content_type='application/pdf',
                                     title='New Employee Handbook', description='HR Packet')
print 'Uploaded. View it at: %s' % attachment.GetAlternateLink().href

如果上传成功,attachment 将在服务器上包含所创建附件的副本。

将附件上传到文件夹中

Google 协作平台中的文件箱式页面支持文件夹。UploadAttachment() 提供了一个额外的关键字参数 folder_name,可用于将附件上传到 filecabinet 文件夹中。只需指定该文件夹的名称即可:

import gdata.data

ms = gdata.data.MediaSource(file_path='/path/to/file.pdf', content_type='application/pdf')
attachment = client.UploadAttachment(ms, feed.entry[0], title='New Employee Handbook',
                                     description='HR Packet', folder_name='My Folder')

请注意,此示例将 gdata.data.MediaSource 对象(而非文件路径)传递给 UploadAttachment()。它也不会传递内容类型。而是在 MediaSource 对象中指定内容类型。

网络附件

网络附件是一种特殊类型的附件。从本质上讲,它们是指向网上其他文件的链接,您可以将这些文件添加到 filecabinet 商品详情中。此功能类似于 Google 协作平台界面中的通过网址添加文件上传方法。

注意:只能在 filecabinet 下创建网络附件。不能上传到其他类型的网页。

此示例会在用户内容 Feed 中的第一个 filecabinet 下创建一个网络附件。其标题和(可选)说明分别设置为“GoogleLogo”和“nice colors”。

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet')
feed = client.GetContentFeed(uri=uri)

parent_entry = feed.entry[0]
image_url = 'http://www.google.com/images/logo.gif'
web_attachment = client.CreateWebAttachment(image_url, 'image/gif', 'GoogleLogo',
                                            parent_entry, description='nice colors')

print 'Created!'

此调用会创建一个指向 filecabinet 中“http://www.google.com/images/logo.gif”处图片的链接。

返回页首



更新内容

更新网页的元数据和/或 HTML 内容

您可以使用客户端的 Update() 方法修改任何条目种类的元数据(title、pageName 等)和网页内容。

以下是更新 listpage 的示例,其中包含以下更改:

  • 标题已修改为“已更新标题”
  • 网页的 HTML 内容更新为“已更新的 HTML 内容”
  • 列表的第一个列标题更改为“所有者”
uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'listpage')
feed = client.GetContentFeed(uri=uri)

old_entry = feed.entry[0]

# Update the listpage's title, html content, and first column's name.
old_entry.title.text = 'Updated Title'
old_entry.content.html = 'Updated HTML Content'
old_entry.data.column[0].name = 'Owner'

# You can also change the page's webspace page name on an update.
# old_entry.page_name = 'new-page-path'

updated_entry = client.Update(old_entry)
print 'List page updated!'

替换附件的内容和元数据

您可以替换附件的文件内容,方法是使用新文件内容创建新的 MediaSource 对象,然后调用客户端的 Update() 方法。附件的元数据(例如标题和说明)也可以更新,或者只是更新元数据。以下示例演示了如何同时更新文件内容和元数据:

import gdata.data

# Load the replacement content in a MediaSource. Also change the attachment's title and description.
ms = gdata.data.MediaSource(file_path='/path/to/replacementContent.doc', content_type='application/msword')
existing_attachment.title.text = 'Updated Document Title'
existing_attachment.summary.text = 'version 2.0'

updated_attachment = client.Update(existing_attachment, media_source=ms)
print "Attachment '%s' changed to '%s'" % (existing_attachment.title.text, updated_attachment.title.text)

返回页首



正在删除内容

要从 Google 协作平台中移除网页或项,请先检索内容条目,然后调用客户端的 Delete() 方法。

client.Delete(content_entry)

您还可以向 Delete() 方法传递内容条目的 edit 链接并/或强制删除:

# force=True sets the If-Match: * header instead of using the entry's ETag.
client.Delete(content_entry.GetEditLink().href, force=True)

如需详细了解 ETag,请参阅 Google Data API 参考指南

返回页首



正在下载附件

每个 attachment 条目都包含一个内容 src 链接,用于下载文件内容。Google 协作平台客户端包含一种通过以下链接访问和下载文件的辅助方法:DownloadAttachment()。 它接受其第一个参数的 gdata.sites.data.ContentEntry 或下载 URI,以及将附件保存到第二个参数的文件路径。

以下示例会提取特定附件条目(通过查询其 self 链接)并将文件下载到指定路径:

uri = 'https://sites.google.com/feeds/content/site/siteName/1234567890'
attachment = client.GetEntry(uri, desired_class=gdata.sites.data.ContentEntry)

print "Downloading '%s', a %s file" % (attachment.title.text, attachment.content.type)
client.DownloadAttachment(attachment, '/path/to/save/test.pdf')

print 'Downloaded!'

应用开发者需负责指定对附件内容类型有意义的文件扩展名。内容类型可以在 entry.content.type 中找到。

在某些情况下(例如,如果您的应用在 Google App Engine 中运行),您可能无法将文件下载到磁盘上。对于这些情况,请使用 _GetFileContent() 提取文件内容并将其存储在内存中。

此示例会以附件的形式下载到内存中。

try:
  file_contents = client._GetFileContent(attachment.content.src)
  # TODO: Do something with the file contents
except gdata.client.RequestError, e:
  raise e

返回页首

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”。
  • default - 只能有一个“default”类型的范围,该范围没有值(例如 <gAcl:scope type="default">)。此特定范围用于控制任何用户在公开网站上默认拥有的访问权限。

注意:网域不能将 gAcl:role 值设为“所有者”访问权限,它们只能是读取者或写入者。

检索 ACL 供稿

ACL Feed 可用于控制网站的共享权限,并可使用 GetAclFeed() 方法获取。

以下示例会提取 SitesClient 对象上当前设置的网站的 ACL Feed,并输出权限条目:

print "Fetching acl permissions of site '%s'...\n" % client.site

feed = client.GetAclFeed()
for entry in feed.entry:
  print '%s (%s) - %s' % (entry.scope.value, entry.scope.type, entry.role.value)

查询成功后,feed 将是一个 gdata.sites.data.AclFeed 对象,其中包含一系列 gdata.sites.data.AclEntry

如果您要处理 SiteFeed 中的条目,则每个 SiteEntry 都包含指向其 ACL Feed 的链接。例如,以下代码段会获取用户网站 Feed 中的第一个网站,并查询其 ACL 供稿:

feed = client.GetSiteFeed()
site_entry = feed.entry[0]

print "Fetching acl permissions of site '%s'...\n" % site_entry.site_name.text
feed = client.GetAclFeed(uri=site_entry.FindAclLink())

共享网站

注意:某些共享 ACL 可能仅在网域配置为允许此类权限的情况下才能使用(例如,如果针对 G Suite 网域启用了与网域外用户共享内容的功能等)。

如需使用 API 共享 Google 网站,请使用所需的 gdata.acl.data.AclScopegdata.acl.data.AclRole 值创建 gdata.sites.gdata.AclEntry。请参阅 ACL Feed 概览部分,了解可能的 AclScopeAclRoles 值。

本示例将站点的读取权限授予用户“user@example.com”:

import gdata.acl.data

scope = gdata.acl.data.AclScope(value='user@example.com', type='user')
role = gdata.acl.data.AclRole(value='reader')
acl = gdata.sites.gdata.AclEntry(scope=scope, role=role)

acl_entry = client.Post(acl, client.MakeAclFeedUri())
print "%s %s added as a %s" % (acl_entry.scope.type, acl_entry.scope.value, acl_entry.role.value)

群组和网域级共享

与单个用户共享网站类似,您可以在 Google 群组或 G Suite 网域之间共享网站。下面列出了必要的 scope 值。

共享至群组电子邮件地址:

scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')

与整个网域共享:

scope = gdata.acl.data.AclScope(value='example.com', type='domain')

只有 G Suite 网域以及托管网站的网域支持网域级共享。 例如,http://sites.google.com/a/domain1.com/siteA 只能与 domain1.com 共享整个网站,而不能与 domain2.com 共享。未在 G Suite 网域(例如 http://sites.google.com/site/siteB)上托管的网站无法邀请网域。

修改共享权限

如需授予网站上的现有共享权限,请先获取相关 AclEntry,根据需要修改权限,然后调用客户端的 Update() 方法来修改服务器上的 ACL。

此示例将“user@example.com”更新为作者(协作者)来修改之前在共享网站部分中的 acl_entry

acl_entry.role.value = 'writer'
updated_acl = client.Update(acl_entry)

# To force the update, even if you do not have the latest changes to the entry:
# updated_acl = client.Update(acl_entrys, force=True)

如需详细了解 ETag,请参阅 Google Data API 参考指南

正在移除共享权限

如需移除共享权限,请先检索 AclEntry,然后调用客户端的 Delete() 方法。

client.Delete(acl_entry)

您还可以向 Delete() 方法传递 acl 条目的 edit 链接并/或强制删除:

# force=True sets the If-Match: * header instead of using the entry's ETag.
client.Delete(acl_entry.GetEditLink().href, force=True)

如需详细了解 ETag,请参阅 Google Data API 参考指南

返回页首

特殊主题

再次检索 Feed 或条目

如果要检索之前检索到的 Feed 或条目,您可以告知服务器仅在自上次检索以来发生了更改时才发送列表或条目,从而提高效率

如需执行此类条件检索,请将 ETag 值传递给 GetEntry()。例如,如果您有一个现有的 entry 对象:

import gdata.client

try:
  entry = client.GetEntry(entry.GetSelfLink().href, desired_class=gdata.sites.data.ContentEntry, etag=entry.etag)
except gdata.client.NotModified, error:
  print 'You have the latest copy of this entry'
  print error

如果 GetEntry() 抛出 gdata.client.NotModified 异常,则该条目的 ETag 与服务器上的版本匹配,这意味着您拥有的副本是最新的。但是,如果其他客户端/用户进行了修改,新条目将在 entry 中返回,并且不会抛出任何异常。

如需详细了解 ETag,请参阅 Google Data API 参考指南

返回页首