Python 指南

重要事項：這份文件的撰寫時間是 2012 年。本文所述的驗證選項 (OAuth 1.0、AuthSub 和 ClientLogin) 已於 2012 年 4 月 20 日正式淘汰，並且全面停用。建議您盡快遷移至 OAuth 2.0。

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

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

適用對象

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

開始使用

如要使用 Python 用戶端程式庫，您需要 Python 2.2 以上版本，以及 DependencyModules 維基網頁所列的模組。下載用戶端程式庫後，請參閱「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]

如未提供必要旗標，應用程式會提示您輸入這些值。本範例可讓使用者執行一些作業，示範傳統版協作平台 API 的使用方式。因此，您必須進行驗證，才能執行特定作業 (例如修改內容)。程式也會提示您透過 AuthSub、OAuth 或 ClientLogin 進行驗證。

如要將本指南中的範例加入您自己的程式碼，您需要以下 import 陳述式：

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

您還需要設定 SitesClient 物件，代表與 Classic 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 物件。

驗證傳統版協作平台網站 API

Python 用戶端程式庫可用於公開或私人動態饋給。Sites Data API 可讓您存取私人和公開的資訊提供 (視網站的權限和您要執行的作業而定)。舉例來說，您可以讀取公開網站的內容動態饋給，但無法對其進行更新，即需要通過驗證的用戶端。這可以透過 ClientLogin 使用者名稱/密碼驗證、AuthSub 或 OAuth 來完成。

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

網頁應用程式的 AuthSub

用戶端應用程式應使用網頁應用程式的 AuthSub 驗證，而這類應用程式需要向 Google 或 G Suite 帳戶驗證使用者。營運商不需要存取 Google 協作平台使用者的使用者名稱和密碼，只需要 AuthSub 權杖。

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

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)

用於網頁或已安裝/行動應用程式的 OAuth

OAuth 可做為 AuthSub 的替代方案，適用於網頁應用程式。OAuth 與 AuthSub 的安全註冊模式類似，兩者的資料要求都必須經過數位簽署，且您必須註冊網域。

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

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

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

返回頁首

網站動態消息

此外，網站動態消息可用來列出使用者擁有的 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.ActivityEntry 清單的 gdata.sites.data.ActivityFeed 物件。每個活動項目都包含網站變更的相關資訊。

返回頁首

正在擷取修訂版本記錄

注意：你必須是網站的協作者或擁有者，才能存取這個動態饋給。 您的用戶端必須使用 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.RevisionEntry 清單的 gdata.sites.data.RevisionFeed 物件。每個修訂版本項目都包含下列資訊：該修訂版本的內容、版本號碼，以及建立新版本的時間。

返回頁首

內容動態饋給

擷取內容動態饋給

注意：內容動態饋給不一定需要驗證，實際情況視網站的共用權限而定。 如果是非公開網站，您的用戶端必須使用 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 Web 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，如果網頁名稱不存在，則不得為空值。正規化會將空白字元截斷至「-」，並移除不符合 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 Handbook」(新員工手冊) 和說明 (選填) 說明「HR packet」(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 協作平台 UI 中的「透過網址新增檔案」上傳方法。

注意：網路附件只能在 filecabinet 下建立。無法上傳至其他類型的頁面。

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

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 內容

任何項目種類的中繼資料 (標題、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)

您也可以傳遞內容項目的 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 連結，可用來下載檔案內容。協作平台用戶端含有透過以下連結存取及下載檔案的輔助方法：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 協作平台 UI 的共用畫面中的「具有存取權的使用者」面板中，每個電子郵件地址會顯示一個項目。因此，系統不會顯示網域管理員，即使他們擁有網站的隱含存取權也一樣。

角色

角色元素代表實體可擁有的存取層級。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.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.sites.gdata.AclEntry 並加入所需的 gdata.acl.data.AclScope 和 gdata.acl.data.AclRole 值。如要瞭解可能的 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 只能與 <網域>1.com 共用整個協作平台，而無法與 <網域>2.com 共用。如果協作平台未是由 G Suite 網域 (例如 http://sites.google.com/site/siteB) 代管，就無法邀請網域。

修改共用權限

如要在網站上現有的共用權限，請先擷取相關的 AclEntry，視需要修改權限，然後呼叫用戶端的 Update() 方法，修改伺服器上的 ACL。

本範例將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)

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

返回頁首

特殊主題

再次擷取動態饋給或項目

如要擷取先前擷取的動態饋給或項目，如要提高效率，您可以指示伺服器傳送清單或項目，前提是該清單或項目自上次擷取後有所變更。

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

返回頁首