Python 指南

重要事項：本文件是在 2012 年之前撰寫，驗證選項 (OAuth 1.0、AuthSub 和 ClientLogin) 中所述， 已正式淘汰 自 2012 年 4 月 20 日起，無法再使用。建議您遷移至 OAuth 2.0。

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

除了提供 Sites Data API 功能的一些背景資訊之外，本指南也提供與 API 互動的範例 使用 Python 用戶端程式庫。如需設定用戶端程式庫的說明，請參閱 開始使用 Google Data Python 用戶端程式庫。如果你有興趣瞭解 如要進一步瞭解 Python 用戶端程式庫用來與傳統版協作平台 API 互動的基礎通訊協定，請參閱 通訊協定指南。

目標對象

本文件可協助開發人員編寫與 Google 協作平台互動的用戶端應用程式 使用 Google Data Python 用戶端程式庫。

開始使用

如要使用 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]

如未提供必要的標記，應用程式會提示您輸入這些值。這個範例可讓使用者執行多項作業 示範如何使用傳統版協作平台 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 整合至網頁應用程式的操作說明

要求單次使用權杖

使用者首次造訪您的應用程式時，需要進行驗證。一般而言，開發人員會輸出一些文字和一個連結，用於引導使用者前往 ，藉此驗證使用者並要求存取他們的文件。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 處理常式)：

  • 下一個網址 — 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。

授權要求權杖

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

升級為存取權杖

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

提示：應用程式成功取得 OAuth 存取權杖後， 將權杖儲存在資料庫中，以便日後使用。因此，您無須在每次執行應用程式時，透過 OAuth 將使用者傳回。 使用 client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) 在用戶端設定現有權杖。

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

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

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

如要使用 ClientLogin，請叫用 ClientLogin() SitesClient 物件方法 (繼承自 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 物件上設定的網域)。

以下範例說明如何建立使用「插入畫面」主題的新網站以及提供 標題和 (選填) 說明：

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 協作平台設定頁面中勾選這項設定
  • 您可以從其他網域複製網站 (您必須是來源網站的擁有者)。

更新網站中繼資料

如要更新網站的標題或摘要，您需要包含相關網站的 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 權杖進行驗證。請參閱驗證協作平台服務。

您可以擷取活動資訊提供，擷取網站的最近活動 (變更)。 lib 的 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 權杖進行驗證。詳情請見 驗證協作平台服務。

內容資訊提供會傳回網站的最新內容。您可以呼叫程式庫的 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.ContentFeed (共 gdata.sites.data.ContentEntry 個)。每個項目都代表 中的不同網頁/項目 且包含特定項目類型的元素。如要進一步瞭解，請參閱範例應用程式 各個項目種類可用的部分屬性，

返回頁首

內容動態饋給查詢範例

您可以使用部分標準 Google Data API 查詢參數搜尋內容動態饋給。 以及傳統版協作平台 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。 如要自訂頁面的網址路徑，可以在內容項目上設定 page_name 屬性。CreatePage() 輔助工具 提供的引數當做選用的關鍵字引數

這個範例會建立新的 filecabinet 頁面，標題為「File Storage」，但建立頁面時 在網址 http://sites.google.com/domainName/siteName/files 下 (而非 http://sites.google.com/domainName/siteName/file-storage) 方法是指定 page_name 屬性

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，並在找到的第一個項目之下建立新的 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 檔案上傳到使用者內容動態饋給中的第一個 filecabinet。 系統會建立附件，主旨為「New Employee Stbook」(新員工手冊)和 (選擇性) 說明「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!'

這個呼叫會建立連結，並指向位於「http://www.google.com/images/logo.gif」的圖片filecabinet。

返回頁首


更新內容

更新網頁的中繼資料和/或 HTML 內容

任何項目類型的中繼資料 (標題、pageName 等) 和網頁內容皆可編輯 使用用戶端的 Update() 方法。

以下是透過以下變更更新 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 連結，可用來下載檔案內容。 協作平台用戶端內含輔助方法，可透過以下連結存取及下載檔案：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 項目都代表特定實體的存取權角色，可以是使用者、使用者群組、網域 或預設存取權 (為公開網站)僅有明確存取權的實體會顯示項目 - 將顯示一個項目 為「有權存取的使用者」中的每個電子郵件地址面板。因此，系統不會顯示網域管理員 即使他們可以透過隱含存取網站也沒問題。

角色

角色元素代表實體可擁有的存取層級。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 值 設定為「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.AclFeed 物件，其中包含 gdata.sites.data.AclEntry 的清單。

如果您使用 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.sites.gdata.AclEntry gdata.acl.data.AclScope 和 gdata.acl.data.AclRole 值。詳情請參閱 「ACL 動態饋給總覽」一節，找出可能的 AclScope 和 AclRoles 值。

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

返回頁首