Python 指南

重要提示：本文档撰写于 2012 年之前。本文档中介绍的身份验证选项（OAuth 1.0、AuthSub 和 ClientLogin）自 2012 年 4 月 20 日起已被正式弃用，不再可用。我们建议您尽快迁移到 OAuth 2.0。

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

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

受众群体

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

使用入门

如需使用 Python 客户端库，您需要 Python 2.2 或更高版本，以及 DependencyModules Wiki 页面上列出的模块。下载客户端库后，请参阅 Google Data 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]

如果未提供必需的标志，应用会提示您输入这些值。该示例允许用户执行一系列操作，以演示如何使用传统版 Google 协作平台 API。因此，您需要进行身份验证才能执行某些操作（例如修改内容）。该程序还会提示您通过 AuthSub、OAuth 或 ClientLogin 进行身份验证。

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

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

您还需要设置 SitesClient 对象，该对象表示与传统版 Sites 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 对象。

向传统版 Google 协作平台 API 进行身份验证

Python 客户端库可用于处理公开或私密 Feed。协作平台数据 API 提供对不公开 Feed 和公共 Feed 的访问权限，具体取决于网站的权限和您尝试执行的操作。例如，您或许可以读取公开网站的内容 Feed，但无法对其进行更新，因为更新需要使用经过身份验证的客户端。这可以通过 ClientLogin 用户名/密码身份验证、AuthSub 或 OAuth 来实现。

有关 AuthSub、OAuth 和 ClientLogin 的详细信息，请参阅 Google Data API 身份验证概述。

用于网络应用程序的 AuthSub

需要对用户进行 Google 账号或 G Suite 账号身份验证的客户端应用应使用 适用于 Web 应用的 AuthSub 身份验证。运营商不需要访问 Google 协作平台用户的用户名和密码，只需要一个 AuthSub 令牌。

查看有关将 AuthSub 集成到 Web 应用中的说明

请求一次性令牌

用户首次访问您的应用时，需要进行身份验证。通常，开发者会输出一些文本和一个链接，将用户定向至 AuthSub 批准页面，以便对用户进行身份验证并请求访问其文档。Google Data 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) 在客户端上设置现有令牌。

用于网络或安装版/移动应用的 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) 在客户端上设置现有令牌。

适用于已安装的应用/移动应用的 ClientLogin

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

查看关于将 ClientLogin 整合到已安装的应用的说明

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

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

提示：当您的应用首次成功对用户进行身份验证后，请将身份验证令牌存储在数据库中，以便日后使用。无需在每次运行应用时都提示用户输入密码。如需了解详情，请参阅重新调用身份验证令牌。

如需详细了解如何在 Python 应用中使用 Dialogflow，请参阅将 ClientLogin 与 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

注意：您必须是相应网站的协作者或所有者，才能访问此 Feed。 您的客户端必须使用 AuthSub、OAuth 或 ClientLogin 令牌进行身份验证。请参阅向 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 或 ClientLogin 令牌进行身份验证。请参阅向 Google 协作平台服务进行身份验证。

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

以下示例会查询内容 Feed，并提取第一个内容条目的修订版本 Feed：

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 可能需要进行身份验证，也可能不需要，具体取决于网站的分享权限。 如果网站为非公开网站，则您的客户端必须使用 AuthSub、OAuth 或 ClientLogin 令牌进行身份验证。请参阅向 Google 协作平台服务进行身份验证。

内容 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 查询参数以及传统版 Google 协作平台 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。例如，以下代码段会返回 filecabinet 和 listpage 条目：

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() 帮助程序将其作为可选的关键字参数提供。

此示例会创建标题为“文件存储空间”的新 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。该附件的标题为“新员工手册”，附有（可选）说明“人力资源包”。

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 对象中指定内容类型。

Web 附件

网页附件是一种特殊的附件。本质上，它们是指向网络上其他文件的链接，您可以将这些文件添加到 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() 方法修改任何条目种类的元数据（标题、页面名称等）和页面内容。

以下示例展示了如何更新 listpage 并进行了以下更改：

  • 标题已修改为“Updated Title”
  • 网页的 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)

您还可以将内容条目的 edit 链接传递给 Delete() 方法和/或强制删除：

# 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 链接，可用于下载文件内容。Sites 客户端包含一个辅助方法，用于访问此链接中的文件并下载该文件：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 Feed

共享权限 (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 Feed

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.AclEntry 列表的 gdata.sites.data.AclFeed 对象。

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

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())

共享网站

注意：只有当网域配置为允许此类权限（例如，为 G Suite 网域启用了网域外共享等）时，才能使用某些共享 ACL。

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

此示例向用户“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。

以下示例修改了共享网站部分中的旧 acl_entry，将“user@example.com”更新为作者（协作者）： 

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)

您还可以将 ACL 条目的 edit 链接传递给 Delete() 方法，并/或强制执行删除操作：

# 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 参考指南。

返回页首