Python 指南

重要事項：本文件是在 2012 年之前撰寫，本文所述的驗證選項 (OAuth 1.0、AuthSub 和 ClientLogin) 已於 2012 年 4 月 20 日正式淘汰，因此無法再使用。建議您盡快改用 OAuth 2.0。

Google Sites Data API 可讓用戶端應用程式存取、發布及修改 Google 網站中的內容。用戶端應用程式也可以請求近期活動清單、擷取修訂版本記錄並下載附件。

除了提供 Site Data API 功能的背景資訊，本指南還提供使用 Python 用戶端程式庫與 API 互動的範例。如需設定用戶端程式庫的相關說明，請參閱「開始使用 Google Data Python 用戶端程式庫」。如果您想進一步瞭解 Python 用戶端程式庫用於與傳統 Sites API 互動的基礎通訊協定，請參閱通訊協定指南。

目標對象

本文件適用於想要使用 Google Data Python 用戶端程式庫，編寫與 Google Sites 互動的用戶端應用程式的開發人員。

開始使用

如要使用 Python 用戶端程式庫，您需要使用 Python 2.2 以上版本，以及 DependencyModules 維基網頁中列出的模組。下載用戶端程式庫後，請參閱「開始使用 Google Data Python 程式庫」，瞭解如何安裝和使用用戶端。

執行範例

完整的運作範例位於專案 Mercurial 存放區的 samples/sites 子目錄中 (/samples/sites/sites_example.py)。

請按照下列步驟執行範例：

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

如果未提供必要的標記，應用程式會提示您輸入這些值。這個範例可讓使用者執行多項作業，說明如何使用傳統版 Sites API。因此，您必須完成驗證程序，才能執行特定作業 (例如修改內容)。程式也會提示您透過 AuthSub、OAuth 或 ClientLogin 進行驗證。

如要在您的程式碼中納入本指南的範例，您需要下列 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 用戶端程式庫可用於處理公開或私人動態饋給。視網站的權限和您要執行的作業而定，Sites Data API 會提供私人和公開動態饋給的存取權。舉例來說，您可能可以讀取公開網站的內容動態饋給，但無法更新該動態饋給，因為這項操作需要經過驗證的用戶端。您可以透過 ClientLogin 使用者名稱/密碼驗證、AuthSub 或 OAuth 來執行這項操作。

如要進一步瞭解 AuthSub、OAuth 和 ClientLogin，請參閱 Google Data API 驗證總覽。

網頁應用程式的 AuthSub

網頁應用程式的 AuthSub 驗證應用於用戶端應用程式，以便向 Google 或 G Suite 帳戶驗證使用者。運算子不需存取 Google 協作平台使用者的使用者名稱和密碼，只需提供 AuthSub 憑證即可。

查看如何將 AuthSub 整合至網頁應用程式的操作說明

要求單次使用權杖

使用者首次造訪應用程式時，必須進行驗證。通常，開發人員會顯示一些文字和連結，引導使用者前往 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 的替代方案，適用於網路應用程式。OAuth 與 AuthSub 的安全與註冊模式類似，因為所有資料要求都必須經過數位簽署，而且您必須註冊網域。

查看將 OAuth 整合至已安裝的應用程式的操作說明

擷取要求權杖

請參閱透過 Google Data API 用戶端程式庫使用 OAuth。

授權要求權杖

請參閱「使用 OAuth 與 Google Data API 用戶端程式庫」。

升級為存取權杖

請參閱「使用 OAuth 與 Google Data API 用戶端程式庫」。

提示：應用程式成功取得 OAuth 存取權杖後，請將該憑證儲存在資料庫中，以便日後使用。您不需要在每次執行應用程式時，透過 OAuth 將使用者傳送回去。使用 client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) 在用戶端上設定現有的權杖。

已安裝/行動應用程式的 ClientLogin

ClientLogin 應由需要對 Google 帳戶進行使用者驗證的已安裝或行動應用程式使用。首次執行時，應用程式會提示使用者輸入使用者名稱/密碼。在後續要求中，系統會參照驗證權杖。

查看如何將 ClientLogin 整合至已安裝的應用程式

如要使用 ClientLogin，請叫用 SitesClient 物件的 ClientLogin() 方法，該方法是從 GDClient 繼承而來。請指定用戶端要代為提出要求的使用者電子郵件地址和密碼。例如：

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

提示：應用程式首次成功驗證使用者後，請將驗證權杖儲存在資料庫中，以便日後重用。因此每當應用程式執行時，都不必要求使用者提供密碼。詳情請參閱呼叫驗證權杖。

如要進一步瞭解如何在 Python 應用程式中使用 ClientLogin，請參閱搭配 Google Data API 用戶端程式庫使用 ClientLogin。

返回頁首

網站動態

網站動態饋給可用於列出使用者擁有或具備檢視權限的 Google 協作平台。您也可以使用這個指令碼修改現有網站的名稱。最後，對於 G Suite 網域，您也可以使用這個工具建立及/或複製整個網站。

列出網站

如要列出使用者可存取的網站，請使用用戶端的 GetSiteFeed() 方法。這個方法使用選用的引數 uri，可用於指定替代網站動態饋給 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 動態饋給 URI。

建立新網站

注意：這項功能僅適用於 G Suite 網域。

只要呼叫程式庫的 CreateSite() 方法，即可佈建新網站。與 GetSiteFeed() 輔助工具類似，CreateSite() 也接受 uri 選用引數，此引數可用於指定替代網站動態饋給 URI (用於建立網站的網域，不是在 SitesClient 物件上設定的網域)。

以下範例說明如何使用「slate」主題建立新網站，並提供標題和 (選用) 說明：

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 動態消息的連結、網站名稱、標題、摘要等。

複製網站

注意：這項功能僅適用於 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 Sites 設定頁面中勾選「將這個網站發布為範本」設定，該網站即為範本。
  • 您可以從其他網域複製網站 (您必須是來源網站的擁有者)。

更新網站的中繼資料

如要更新網站的標題或摘要，您需要包含相關網站的 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)

返回頁首

擷取活動動態提醒

注意：你必須是網站的協作者或擁有者，才能存取這個動態饋給。 您的用戶端必須使用 AuthSub、OAuth 或 ClientLogin 權杖進行驗證。請參閱驗證協作平台服務。

您可以擷取活動動態消息，擷取網站的最近活動 (變更)。 這個程式庫的 GetActivityFeed() 方法可提供此動態饋給的存取權：

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.ActivityFeed 物件，其中包含 gdata.sites.data.ActivityEntry 的清單。每個活動項目都包含網站所做的變更資訊。

返回頁首

正在擷取修訂版本記錄

注意：您必須是網站的協作者或擁有者，才能存取動態饋給。 您的用戶端必須使用 AuthSub、OAuth 或 ClientLogin 權杖進行驗證。請參閱驗證協作平台服務。

修訂版本動態饋給會提供任何內容項目的修訂版本記錄資訊。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.RevisionFeed 物件，其中包含 gdata.sites.data.RevisionEntry 的清單。每個修訂版本項目都包含許多資訊，例如該修訂版本的內容、版本號碼，以及建立新版本的時間。

返回頁首

內容動態饋給

擷取內容動態饋給

注意：內容動態饋給可能需要驗證，也可能不需要驗證，這取決於網站的分享權限。如果網站不是公開網站，您的用戶端必須使用 AuthSub、OAuth 或 ClientLogin 權杖進行驗證。請參閱「驗證協作平台服務」。

內容動態饋給會傳回網站的最新內容。呼叫 lib 的 GetContentFeed() 方法，該方法使用選用的 uri 字串參數來傳送自訂查詢，即可存取這個程式庫。

以下是擷取整個內容動態饋給並列印出一些有趣元素的範例：

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。每個項目都代表使用者網站中不同的網頁/項目，並包含特定項目種類專屬的元素。請參閱範例應用程式，進一步瞭解各項目種類可用的部分屬性。

返回頁首

內容動態饋給查詢範例

您可以使用部分 標準 Google Data API 查詢參數和傳統 Sites API 專屬參數，搜尋內容動態饋給。如要進一步瞭解支援的參數和完整的支援參數清單，請參閱參考指南。

注意：本節中的範例使用 gdata.sites.client.MakeContentFeedUri() 輔助方法，建構內容動態饋給的基本 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 頁面，標題為「File Storage」，但會透過指定 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，如果沒有頁面名稱，則不得為空值。標準化是指將空白字元裁減 + 縮減為「-」並移除不符合 a-z, A-Z, 0-9, -, _ 的字元。

建立子頁面

如要在父頁面下建立子頁面 (子項)，請使用 CreatePage() 的 parent 關鍵字引數。parent 可以是 gdata.sites.gdata.ContentEntry，也可以是代表內容項目完整自我 ID 的字串。

這個範例會查詢 announcementpage 的內容動態饋給，並在找到的第一個 announcementpage 下方建立新的 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 Sites 一樣，API 也支援將附件上傳至檔案櫃頁面或父頁面。附件必須上傳至上層頁面。因此，您必須在要上傳的 ContentEntry 上設定父項連結。詳情請參閱「建立子頁面」一文。

用戶端程式庫的 UploadAttachment() 方法會提供上傳附件的介面。

正在上傳附件

在此範例中，系統會將 PDF 檔案上傳到使用者內容動態饋給中的第一個 filecabinet。系統會建立附件，並於其中標題為「新員工手冊」標題，以及說明 (選填) 說明「HR 封包」。

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 下建立網頁附件。但無法上傳至其他類型的網頁。

這個範例會在使用者內容動態饋給找到的第一個 filecabinet 下建立網路附件。其標題和 (選用) 說明分別設為「GoogleLogo」和「nice color」。

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() 方法，編輯任何項目類型的中繼資料 (標題、pageName 等) 和網頁內容。

以下是更新 listpage 的範例，其中包含以下變更：

  • 標題已修改為「Updated Title」
  • 網頁的 HTML 內容已更新為「Updated HTML Content」
  • 清單的第一個欄標題已變更為「Owner」
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 連結，可用來下載檔案內容。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 動態饋給

共用權限 (ACL) 總覽

ACL 動態饋給中的每個 ACL 項目都代表特定實體的存取權角色，可以是使用者、使用者群組、網域或預設存取權 (亦即公開網站)。系統只會顯示明確存取權實體的項目，在 Google Sites UI 的「存取權使用者」面板中，每個電子郵件地址都會顯示一筆項目。因此，即使網域管理員已隱含網站的存取權，也不會顯示。

角色

role 元素代表實體可擁有的存取層級。gAcl:role 元素有四個可能的值：

  • reader：檢視者 (等同於唯讀存取權)。
  • writer - 協作者 (相當於讀取/寫入權限)。
  • 擁有者：通常是網站管理員 (等同於讀取/寫入存取權)。

範圍

範圍元素代表具有此存取層級的實體。gAcl:scope 元素分為四種類型：

  • user - 電子郵件地址值，例如「user@gmail.com」。
  • group：Google 網路論壇電子郵件地址，例如「group@domain.com」。
  • domain：G Suite 網域名稱，例如「domain.com」。
  • 預設：只有一個可能的「預設」類型範圍，且沒有任何值 (例如 <gAcl:scope type="default">)。這個特定範圍會控制任何使用者在公開網站上預設的存取權。

注意：網域的 gAcl:role 值不得設為「owner」存取權，只能是讀取或寫入權限。

擷取 ACL 動態饋給

您可以使用 ACL 動態饋給控管網站的分享權限，並使用 GetAclFeed() 方法擷取動態饋給。

以下範例會擷取目前在 SitesClient 物件上設定的網站 ACL 動態饋給，並列印權限項目：

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 動態饋給的連結。舉例來說，這個程式碼片段會擷取使用者網站動態饋給中的第一個網站，並查詢其 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.AclScope 和 gdata.acl.data.AclRole 值的 gdata.sites.gdata.AclEntry。如要瞭解可能的 AclScope 和 AclRoles 值，請參閱「ACL 動態饋給總覽」一節。

以下範例會將網站的讀取權限授予使用者「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)

您也可以將 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 參考指南。

返回頁首

特殊主題

再次擷取動態饋給或項目

如果您想擷取先前擷取過的動態饋給或項目，可以提高效率，只要告訴伺服器，只在該清單或項目自上次擷取後有所變動時傳送即可。

如要執行這類的條件擷取作業，請將 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 參考指南。

返回頁首