Hướng dẫn về Python

Lưu ý quan trọng: Tài liệu này được viết trước năm 2012. Tuỳ chọn xác thực được mô tả trong tài liệu này (OAuth 1.0, AuthSub và ClientLogin) chính thức ngừng hoạt động kể từ ngày 20 tháng 4 năm 2012 và không còn nữa. Bạn nên chuyển sang OAuth 2.0 sớm nhất có thể.

API dữ liệu Google Sites cho phép các ứng dụng khách truy cập, xuất bản và sửa đổi nội dung trong một trang web tạo bằng Google Sites. Ứng dụng khách của bạn cũng có thể yêu cầu danh sách hoạt động gần đây, tìm nạp nhật ký sửa đổi và tải tệp đính kèm xuống.

Ngoài việc cung cấp một số thông tin cơ bản về những khả năng của Sites Data API, hướng dẫn này còn cung cấp các ví dụ về cách tương tác với API bằng cách dùng thư viện ứng dụng Python. Để được trợ giúp thiết lập thư viện ứng dụng, hãy xem Bắt đầu sử dụng Thư viện ứng dụng Google Data Python. Nếu bạn quan tâm đến để tìm hiểu thêm về giao thức cơ bản mà thư viện ứng dụng Python sử dụng để tương tác với Sites API cũ, vui lòng xem hướng dẫn về giao thức.

Đối tượng

Tài liệu này dành cho các nhà phát triển muốn viết các ứng dụng khách tương tác với Google Sites bằng cách dùng Thư viện ứng dụng Google Data Python.

Bắt đầu

Để sử dụng thư viện ứng dụng Python, bạn cần có Python 2.2 trở lên và các mô-đun được liệt kê trên trang wiki DependencyModules wiki. Sau khi tải thư viện ứng dụng xuống, hãy xem bài viết Bắt đầu sử dụng Thư viện Google Data Python để được trợ giúp về cách cài đặt và sử dụng ứng dụng.

Chạy mẫu

Một mẫu đầy đủ hoạt động nằm trong thư mục con samples/sites của Kho lưu trữ Mercurial của dự án (/samples/sites/sites_example.py).

Chạy ví dụ như sau:

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

Nếu cờ bắt buộc không được cung cấp, ứng dụng sẽ nhắc bạn nhập các giá trị đó. Mẫu này cho phép người dùng thực hiện một số thao tác minh hoạ cách sử dụng Sites API cũ. Do đó, bạn sẽ cần xác thực để thực hiện một số thao tác nhất định (ví dụ: sửa đổi nội dung). Chương trình này sẽ cũng nhắc bạn xác thực qua AuthSub, OAuth hoặc ClientLogin.

Để đưa các ví dụ trong hướng dẫn này vào mã của riêng bạn, bạn cần có các câu lệnh import sau:

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

Bạn cũng sẽ cần thiết lập đối tượng SitesClient đại diện cho kết nối ứng dụng với Sites API cũ. Truyền tên ứng dụng của bạn và tên trang web của Trang web (từ URL của trang web):

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

Để làm việc với trang web được lưu trữ trên miền G Suite, hãy đặt miền bằng tham số domain:

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

Trong các đoạn mã trên, đối số source là không bắt buộc nhưng bạn nên dùng cho mục đích ghi nhật ký. Phải theo định dạng: company-applicationname-version

Lưu ý: Phần còn lại của hướng dẫn này giả định bạn đã tạo một đối tượng SitesClient trong biến client.

Xác thực đến API Sites cũ

Bạn có thể sử dụng thư viện ứng dụng Python để làm việc với nguồn cấp dữ liệu công khai hoặc riêng tư. Sites Data API cấp quyền truy cập vào các báo cáo riêng tư và công khai nguồn cấp dữ liệu, tuỳ thuộc vào quyền của Trang web và thao tác mà bạn đang cố gắng thực hiện. Ví dụ: bạn có thể đọc nguồn cấp nội dung của trang web công khai nhưng không cập nhật trang web đó – đây là việc bắt buộc phải có khách hàng đã xác thực. Việc này có thể thực hiện qua Xác thực tên người dùng/mật khẩu ClientLogin, AuthSub hoặc OAuth.

Vui lòng xem bài viết Tổng quan về việc xác thực API dữ liệu của Google để biết thêm thông tin về AuthSub, OAuth và ClientLogin.

AuthSub cho các ứng dụng web

Xác thực AuthSub cho ứng dụng web nên được sử dụng bởi các ứng dụng khách cần xác thực người dùng với tài khoản Google hoặc G Suite. Nhà cung cấp dịch vụ không cần quyền truy cập vào tên người dùng và mật khẩu đối với người dùng Google Sites - mà chỉ cần Bắt buộc phải có mã thông báo 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 cho web hoặc ứng dụng đã cài đặt/dành cho thiết bị di động

OAuth có thể được dùng làm phương án thay thế cho AuthSub và dành cho các ứng dụng web. OAuth tương tự như việc sử dụng chế độ bảo mật và đã đăng ký của AuthSub trong đó tất cả yêu cầu dữ liệu phải được ký số và bạn phải đăng ký miền của mình.

ClientLogin cho các ứng dụng đã cài đặt/dành cho thiết bị di động

ClientLogin phải được sử dụng bởi các ứng dụng di động hoặc đã cài đặt cần xác thực người dùng với Tài khoản Google. Trong lần chạy đầu tiên, ứng dụng của bạn sẽ nhắc người dùng nhập tên người dùng/mật khẩu của họ. Trong các yêu cầu tiếp theo, mã thông báo xác thực đang được tham chiếu.

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

Trở lại đầu trang

Nguồn cấp dữ liệu trang web

Bạn có thể sử dụng nguồn cấp dữ liệu trang web này để liệt kê những trang web tạo bằng Google Sites mà người dùng sở hữu hoặc có quyền xem. Bạn cũng có thể dùng URL này để sửa đổi tên của một trang web hiện có. Cuối cùng, đối với các miền G Suite, bạn cũng có thể dùng ứng dụng này để tạo và/hoặc sao chép toàn bộ trang web.

Trang thông tin

Để liệt kê các trang web mà người dùng có quyền truy cập, hãy sử dụng phương thức GetSiteFeed() của ứng dụng. Phương thức này lấy một giá trị không bắt buộc đối số uri mà bạn có thể dùng để chỉ định URI nguồn cấp dữ liệu trang web thay thế. Theo mặc định, GetSiteFeed() sử dụng tên trang web và miền được đặt trên đối tượng ứng dụng. Hãy xem phần Bắt đầu để thông tin thêm về cách đặt các giá trị này trên đối tượng ứng dụng của bạn.

Dưới đây là ví dụ về cách tìm nạp danh sách trang web của người dùng đã xác thực:

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

Đoạn mã trên in tiêu đề, tên trang web, trang web được sao chép và URI nguồn cấp dữ liệu acl của trang web.

Tạo trang web mới

Lưu ý: Tính năng này chỉ dành cho các miền G Suite.

Bạn có thể cấp phép các trang web mới bằng cách gọi phương thức CreateSite() của thư viện. Tương tự như trình trợ giúp GetSiteFeed(), CreateSite() cũng chấp nhận đối số không bắt buộc, uri, mà bạn có thể dùng để chỉ định URI nguồn cấp dữ liệu trang web thay thế (trong trường hợp tạo trang web trong một miền khác với miền được đặt trên đối tượng SitesClient).

Dưới đây là ví dụ về cách tạo một trang web mới có chủ đề "phương tiện chặn" và cung cấp một tiêu đề và mô tả (không bắt buộc):

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

Yêu cầu ở trên sẽ tạo một trang web mới thuộc miền G Suite example2.com. Do đó, URL của trang web sẽ là https://sites.google.com/a/example2.com/title-for-my-site.

Nếu trang web được tạo thành công, máy chủ sẽ phản hồi bằng một gdata.sites.data.SiteEntry , được điền sẵn bằng các phần tử do máy chủ thêm vào: liên kết đến trang web, liên kết đến nguồn cấp dữ liệu acl của trang web, tên trang web, tiêu đề, bản tóm tắt, v.v.

Sao chép trang web

Lưu ý: Tính năng này chỉ dành cho các miền G Suite.

Bạn cũng có thể sử dụng CreateSite() để sao chép một trang web hiện có. Để thực hiện việc này, hãy truyền đối số từ khoá source_site vào. Mọi trang web đã được sao chép đều sẽ có đường liên kết này. Bạn có thể truy cập đường liên kết này qua entry.FindSourceLink(). Dưới đây là ví dụ về việc sao chép trang web được tạo trong phần Tạo trang web mới:

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

Điểm quan trọng:

• Chỉ có thể sao chép các trang web và mẫu trang web mà người dùng đã xác thực sở hữu.
• Bạn cũng có thể sao chép mẫu trang web. Trang web là mẫu nếu lệnh "Xuất bản trang web này dưới dạng mẫu" được chọn trong trang cài đặt Google Sites.
• Bạn có thể sao chép một trang web từ một miền khác, trừ phi bạn được liệt kê là chủ sở hữu trên trang web nguồn.

Cập nhật siêu dữ liệu của trang web

Để cập nhật tiêu đề hoặc phần tóm tắt về một trang web, bạn cần có SiteEntry chứa trang web hữu quan. Chiến dịch này ví dụ này sử dụng phương thức GetEntry() để tìm nạp SiteEntry trước tiên, sau đó thay đổi tiêu đề, nội dung mô tả và thẻ danh mục của 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)

Trở lại đầu trang

Đang tìm nạp Nguồn cấp dữ liệu hoạt động

Lưu ý: Để truy cập vào nguồn cấp dữ liệu này, bạn phải là cộng tác viên hoặc chủ sở hữu của Trang web. Ứng dụng khách của bạn phải xác thực bằng cách sử dụng mã thông báo AuthSub, OAuth hoặc ClientLogin. Hãy xem bài viết Xác thực với dịch vụ Sites.

Bạn có thể tìm nạp hoạt động gần đây của một Trang web (các thay đổi) bằng cách tìm nạp nguồn cấp dữ liệu hoạt động. Phương thức GetActivityFeed() của lib cung cấp quyền truy cập vào nguồn cấp dữ liệu sau:

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)

Việc gọi GetActivityFeed() sẽ trả về một đối tượng gdata.sites.data.ActivityFeed chứa danh sách gdata.sites.data.ActivityEntry. Mỗi mục nhập hoạt động chứa thông tin về một thay đổi đã được thực hiện đối với Trang web.

Trở lại đầu trang

Đang tìm nạp nhật ký sửa đổi

Lưu ý: Để truy cập vào nguồn cấp dữ liệu này, bạn phải là cộng tác viên hoặc chủ sở hữu của Trang web. Ứng dụng khách của bạn phải xác thực bằng cách sử dụng mã thông báo AuthSub, OAuth hoặc ClientLogin. Hãy xem bài viết Xác thực với dịch vụ Sites.

Nguồn cấp dữ liệu sửa đổi cung cấp thông tin về nhật ký sửa đổi cho mọi mục nội dung. GetRevisionFeed() có thể được dùng để tìm nạp bản sửa đổi cho một mục nhập nội dung nhất định. Phương thức này lấy một uri không bắt buộc chấp nhận gdata.sites.data.ContentEntry, URI đầy đủ của mục nhập nội dung hoặc mã mục nhập nội dung.

Ví dụ này truy vấn nguồn cấp nội dung và tìm nạp nguồn cấp dữ liệu của bản sửa đổi cho mục nhập nội dung đầu tiên:

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]

Việc gọi GetRevisionFeed() sẽ trả về một đối tượng gdata.sites.data.RevisionFeed chứa danh sách gdata.sites.data.RevisionEntry. Mỗi mục nhập của bản sửa đổi chứa thông tin như nội dung tại bản sửa đổi đó, số phiên bản và thời điểm phiên bản mới được tạo.

Trở lại đầu trang

Nguồn cấp nội dung

Truy xuất nguồn cấp nội dung

Lưu ý: Nguồn cấp nội dung có thể yêu cầu hoặc không yêu cầu xác thực; tuỳ theo quyền chia sẻ của Trang web. Nếu Trang web không công khai, ứng dụng của bạn phải xác thực bằng cách sử dụng mã thông báo AuthSub, OAuth hoặc ClientLogin. Xem Xác thực dịch vụ Sites.

Nguồn cấp nội dung trả về nội dung mới nhất của Trang web. Bạn có thể truy cập công cụ này bằng cách gọi hàm Phương thức GetContentFeed(), lấy tham số chuỗi uri không bắt buộc để truyền một truy vấn được tuỳ chỉnh.

Dưới đây là ví dụ về cách tìm nạp toàn bộ nguồn cấp nội dung và in ra một số thành phần thú vị:

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

Mẹo: Bạn có thể sử dụng entry.Kind() để xác định loại mục nhập.

Đối tượng feed thu được là một gdata.sites.data.ContentFeed chứa danh sách trong tổng số gdata.sites.data.ContentEntry. Mỗi mục nhập đại diện cho một trang/mục khác nhau trong Trang web của người dùng và có các phần tử dành riêng cho loại mục nhập đó. Xem đơn đăng ký mẫu để có ý tưởng tốt hơn một số thuộc tính có sẵn trong mỗi loại mục nhập.

Trở lại đầu trang

Ví dụ về truy vấn nguồn cấp nội dung

Bạn có thể tìm kiếm nguồn cấp nội dung bằng cách sử dụng một số tham số truy vấn chuẩn của Google Data API và những thông tin dành riêng cho API Sites cũ. Để biết thêm thông tin chi tiết và danh sách đầy đủ các thông số được hỗ trợ, hãy xem Hướng dẫn tham khảo.

Lưu ý: Các ví dụ trong phần này sử dụng phương thức trợ giúp gdata.sites.client.MakeContentFeedUri() để tạo URI cơ sở của nguồn cấp nội dung.

Truy xuất các loại mục nhập cụ thể

Để chỉ tìm nạp một loại mục nhập cụ thể, hãy sử dụng tham số kind. Ví dụ: đoạn mã này chỉ trả về attachment mục nhập:

kind = 'webpage'

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

Để trả về nhiều loại, hãy phân tách từng kind bằng dấu phẩy. Ví dụ: đoạn mã này trả về filecabinet và Mục nhập listpage:

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

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

Truy xuất trang theo đường dẫn

Nếu biết đường dẫn tương đối của một trang trong Google Sites, bạn có thể sử dụng tham số path để tìm nạp trang cụ thể đó. Ví dụ này trả về trang nằm ở 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)

Truy xuất tất cả các mục nhập trong trang gốc

Nếu biết mã mục nhập nội dung của một trang (ví dụ: "1234567890" trong ví dụ dưới đây), bạn có thể sử dụng tham số parent để tìm nạp tất cả các mục nhập con (nếu có):

parent = '1234567890'

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

Để biết các thông số khác, hãy xem Hướng dẫn tham khảo.

Trở lại đầu trang

Sáng tạo nội dung

Lưu ý: Trước khi tạo nội dung cho một trang web, hãy đảm bảo rằng bạn đã thiết lập trang web của mình trong ứng dụng khách.
client.site = "siteName"

Bạn có thể tạo nội dung mới (trang web, trang danh sách, trang tổ chức tệp, trang thông báo, v.v.) bằng cách sử dụng CreatePage(). Đối số đầu tiên cho phương thức này phải là loại trang cần tạo, theo sau là tiêu đề và nội dung HTML của trang.

Để biết danh sách các loại nút được hỗ trợ, hãy xem tham số kind trong Hướng dẫn tham khảo.

Tạo mục / trang mới

Ví dụ này sẽ tạo một webpage mới ở cấp cao nhất, bao gồm một số\" đối với nội dung trang, và đặt tiêu đề tiêu đề thành 'Tiêu đề trang web mới':

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

Nếu yêu cầu thành công, entry sẽ chứa bản sao của mục được tạo trên máy chủ, dưới dạng gdata.sites.gdata.ContentEntry.

Để tạo loại mục nhập phức tạp hơn được điền sẵn khi tạo (ví dụ: listpage có tiêu đề cột), bạn cần phải tạo gdata.sites.data.ContentEntry theo cách thủ công, điền các thuộc tính quan tâm và gọi client.Post().

Tạo mục/trang trong đường dẫn URL tuỳ chỉnh

Theo mặc định, ví dụ trước sẽ được tạo trong URL http://sites.google.com/domainName/siteName/new-webpage-title và có tiêu đề trang là 'Tiêu đề trang web mới'. Tức là tiêu đề được chuẩn hoá thành new-webpage-title cho URL. Để tuỳ chỉnh đường dẫn URL của một trang, bạn có thể thiết lập thuộc tính page_name trên mục nhập nội dung. Trình trợ giúp CreatePage() cung cấp dưới dạng đối số từ khoá không bắt buộc.

Ví dụ này tạo một trang filecabinet mới với tiêu đề là "File Storage", nhưng lại tạo trang này trong URL http://sites.google.com/domainName/siteName/files (thay vì http://sites.google.com/domainName/siteName/file-storage) bằng cách chỉ định thuộc tính page_name.

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

Máy chủ sử dụng các quy tắc ưu tiên sau đây để đặt tên cho đường dẫn URL của một trang:

1. page_name, nếu có. Phải đáp ứng a-z, A-Z, 0-9, -, _.
2. title, không được để trống nếu không có tên trang. Chuẩn hoá là cắt + thu gọn khoảng trắng thành "-" và xoá những ký tự không khớp với a-z, A-Z, 0-9, -, _.

Tạo trang con

Để tạo trang con (trang con) trong trang mẹ, hãy sử dụng đối số từ khoá parent của CreatePage(). parent có thể là gdata.sites.gdata.ContentEntry hoặc một chuỗi đại diện cho mã nhận dạng chính đầy đủ của mục nhập nội dung.

Ví dụ này truy vấn nguồn cấp nội dung cho các announcementpage và tạo một announcement mới trong nguồn cấp dữ liệu đầu tiên vừa tìm thấy:

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!'

Đang tải tệp lên

Giống như trong Google Sites, API hỗ trợ tải tệp đính kèm lên trang tổ chức tệp hoặc trang mẹ. Bạn phải tải tệp đính kèm lên vào trang gốc. Do đó, bạn phải đặt một đường liên kết dành cho cha mẹ trên ContentEntry mà bạn đang muốn tải lên. Xem phần Tạo trang con để biết thêm thông tin.

Phương thức UploadAttachment() của thư viện ứng dụng cung cấp giao diện để tải tệp đính kèm lên.

Đang tải tệp đính kèm lên

Ví dụ này tải một tệp PDF lên filecabinet đầu tiên trong nguồn cấp nội dung của người dùng. Tệp đính kèm được tạo với tiêu đề "Sổ tay nhân viên mới" và mô tả (không bắt buộc) là "gói 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

Nếu tải lên thành công, attachment sẽ chứa một bản sao của tệp đính kèm đã tạo trên máy chủ.

Tải tệp đính kèm lên thư mục

Tủ tệp trong Google Sites hỗ trợ các thư mục. UploadAttachment() cung cấp một từ khoá bổ sung đối số folder_name mà bạn có thể sử dụng để tải tệp đính kèm lên thư mục filecabinet. Chỉ cần chỉ định tên của thư mục đó:

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

Lưu ý rằng ví dụ này sẽ truyền đối tượng gdata.data.MediaSource đến UploadAttachment() của một đường dẫn tệp. Phương thức này cũng không vượt qua được loại nội dung. Thay vào đó, loại nội dung được chỉ định trên đối tượng MediaSource.

Tệp đính kèm trên web

Tệp đính kèm web là các loại tệp đính kèm đặc biệt. Về cơ bản, chúng là các đường liên kết đến các tệp khác trên web mà bạn có thể thêm vào trang thông tin của mình trên filecabinet. Tính năng này tương tự như tính năng "Thêm tệp bằng URL" trong giao diện người dùng Google Sites.

Lưu ý: Bạn chỉ có thể tạo tệp đính kèm web trong filecabinet. Bạn không thể tải các tệp này lên các loại trang khác.

Ví dụ này tạo một tệp đính kèm web trong filecabinet đầu tiên được tìm thấy trong nguồn cấp nội dung của người dùng. Tiêu đề và mô tả (không bắt buộc) của biểu trưng được đặt thành 'GoogleLogo' và 'màu đẹp'.

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!'

Cuộc gọi sẽ tạo một liên kết trỏ đến hình ảnh tại 'http://www.google.com/images/logo.gif' trong filecabinet.

Trở lại đầu trang

Cập nhật nội dung

Cập nhật siêu dữ liệu và/hoặc nội dung html của trang

Người dùng có thể chỉnh sửa siêu dữ liệu (tiêu đề, tên trang, v.v.) và nội dung trang thuộc bất kỳ loại mục nhập nào bằng bằng phương thức Update() của ứng dụng.

Dưới đây là ví dụ về cách cập nhật listpage với các thay đổi sau:

• Tiêu đề được sửa đổi thành "Tiêu đề đã cập nhật"
• Nội dung HTML của trang được cập nhật thành "Nội dung HTML đã cập nhật"
• Tiêu đề cột đầu tiên của danh sách được thay đổi thành "Chủ sở hữu"

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!'

Thay thế nội dung + siêu dữ liệu của tệp đính kèm

Bạn có thể thay thế nội dung tệp của tệp đính kèm bằng cách tạo một đối tượng MediaSource mới bằng nội dung tệp mới và gọi phương thức Update() của ứng dụng khách. Tệp đính kèm siêu dữ liệu (chẳng hạn như tiêu đề và nội dung mô tả) cũng có thể được cập nhật hoặc chỉ đơn giản là siêu dữ liệu. Ví dụ sau minh hoạ việc cập nhật nội dung tệp và siêu dữ liệu cùng một lúc:

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)

Trở lại đầu trang

Xoá nội dung

Để xoá một trang hoặc một mục khỏi trang web tạo bằng Google Sites, trước tiên, hãy truy xuất mục nhập nội dung rồi gọi phương thức Delete() của ứng dụng.

client.Delete(content_entry)

Bạn cũng có thể chuyển đường liên kết edit của mục nhập nội dung và/hoặc buộc xoá phương thức Delete():

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

Để biết thêm thông tin về ETag, hãy xem Hướng dẫn tham khảo về API dữ liệu của Google.

Trở lại đầu trang

Đang tải tệp đính kèm xuống

Mỗi mục nhập attachment chứa một đường liên kết nội dung src có thể được dùng để tải nội dung tệp xuống. Ứng dụng Sites có chứa phương thức trợ giúp để truy cập và tải tệp xuống từ đường liên kết này: DownloadAttachment(). Phương thức này chấp nhận một gdata.sites.data.ContentEntry hoặc URI tải xuống cho đối số đầu tiên và một đường dẫn tệp để lưu tệp đính kèm làm phương diện thứ hai.

Ví dụ này tìm nạp một mục nhập tệp đính kèm cụ thể (bằng cách truy vấn đường liên kết self) rồi tải tệp xuống đường dẫn được chỉ định:

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!'

Nhà phát triển ứng dụng có thể chỉ định đuôi tệp phù hợp với loại nội dung của tệp đính kèm. Loại nội dung có tại entry.content.type.

Trong một số trường hợp, bạn có thể không tải được tệp xuống đĩa (ví dụ: nếu ứng dụng của bạn đang chạy trong Google App Engine). Trong những trường hợp như vậy, hãy sử dụng _GetFileContent() để tìm nạp nội dung tệp và lưu trữ nội dung đó trong bộ nhớ.

Tệp tải xuống ví dụ này là một tệp đính kèm vào kỷ niệm.

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

Trở lại đầu trang

Nguồn cấp dữ liệu ACL

Tổng quan về quyền chia sẻ (ACL)

Mỗi mục nhập ACL trong nguồn cấp dữ liệu ACL đại diện cho vai trò truy cập của một thực thể cụ thể, có thể là người dùng, nhóm người dùng, miền hoặc quyền truy cập mặc định (là một trang web công khai). Mục nhập sẽ chỉ hiển thị cho các thực thể có quyền truy cập rõ ràng – một mục nhập sẽ hiển thị cho từng địa chỉ email trong phần "Người dùng có quyền truy cập" trong màn hình chia sẻ của giao diện người dùng Google Sites. Do đó, quản trị viên miền sẽ không xuất hiện, ngay cả khi chúng có quyền truy cập ngầm ẩn vào một trang web.

Vai trò

Phần tử vai trò đại diện cho cấp truy cập mà một thực thể có thể có. Phần tử gAcl:role có thể có 4 giá trị:

• người đọc — một người xem (tương đương với quyền chỉ có thể đọc).
• người viết — một cộng tác viên (tương đương với quyền đọc/ghi).
• owner – thường là quản trị viên trang web (tương đương với quyền truy cập đọc/ghi).

Phạm vi

Phần tử phạm vi đại diện cho thực thể có cấp truy cập này. Có 4 loại phần tử gAcl:scope:

• người dùng — một giá trị địa chỉ email, ví dụ: "user@gmail.com".
• group — một địa chỉ email của Google Group, ví dụ: "group@domain.com".
• domain – một tên miền của G Suite, ví dụ: "domain.com".
• default — Chỉ có thể có một phạm vi thuộc loại "default", không có giá trị (ví dụ: <gAcl:scope type="default">). Phạm vi cụ thể này kiểm soát quyền truy cập của bất kỳ người dùng nào theo mặc định trên trang web công khai.

Lưu ý: Miền không được có giá trị gAcl:role đặt thành "chủ sở hữu" truy cập, họ chỉ có thể là độc giả hoặc tác giả.

Truy xuất nguồn cấp dữ liệu ACL

Nguồn cấp dữ liệu ACL có thể được dùng để kiểm soát quyền chia sẻ của trang web và có thể được tìm nạp bằng phương thức GetAclFeed().

Ví dụ sau đây tìm nạp nguồn cấp dữ liệu ACL cho trang web hiện được thiết lập trên đối tượng SitesClient, và in ra các mục nhập quyền:

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)

Sau khi truy vấn thành công, feed sẽ là đối tượng gdata.sites.data.AclFeed chứa danh sách của gdata.sites.data.AclEntry.

Nếu bạn đang làm việc với các mục nhập trong SiteFeed thì mỗi SiteEntry chứa một đường liên kết đến nguồn cấp dữ liệu ACL của nó. Ví dụ: đoạn mã này tìm nạp trang web đầu tiên trong Nguồn cấp dữ liệu trang web của người dùng và truy vấn nguồn cấp dữ liệu ACL của trang đó:

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

Chia sẻ một trang web

Lưu ý: Một số ACL chia sẻ nhất định chỉ có thể hoạt động nếu miền được định cấu hình để cấp các quyền đó (ví dụ: nếu tính năng chia sẻ ra bên ngoài miền cho các miền G Suite đang bật, v.v.).

Để chia sẻ một trang web tạo bằng Google Sites bằng API, hãy tạo một gdata.sites.gdata.AclEntry với tuỳ chọn Các giá trị gdata.acl.data.AclScope và gdata.acl.data.AclRole. Xem Phần Tổng quan về nguồn cấp dữ liệu ACL cho AclScope có thể có và AclRoles giá trị.

Ví dụ này cấp quyền đọc trên Trang web cho người dùng '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)

Chia sẻ ở cấp Nhóm và cấp Miền

Tương tự như việc chia sẻ trang web với một người dùng, bạn có thể chia sẻ trang web qua Nhóm Google hoặc miền G Suite. Các giá trị scope cần thiết được liệt kê bên dưới.

Chia sẻ với một địa chỉ email nhóm:

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

Chia sẻ với toàn bộ miền:

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

Tính năng chia sẻ ở cấp miền chỉ được hỗ trợ cho các miền G Suite và chỉ cho miền mà trang web lưu trữ. Ví dụ: http://sites.google.com/a/domain1.com/siteA chỉ có thể chia sẻ toàn bộ Trang web với domain1.com, chứ không thể chia sẻ với domain2.com. Trang web không được lưu trữ trên miền G Suite (ví dụ: http://sites.google.com/site/siteB) không thể mời miền.

Sửa đổi quyền chia sẻ

Đối với quyền chia sẻ hiện có trên một trang web, trước tiên, hãy tìm nạp AclEntry có liên quan rồi sửa đổi quyền đó như mong muốn rồi gọi phương thức Update() của ứng dụng khách để sửa đổi ACL trên máy chủ.

Ví dụ này sửa đổi acl_entry trước đó của chúng ta trong phần Chia sẻ trang web, bằng cách cập nhật 'user@example.com' trở thành nhà văn (cộng tác viên):

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)

Để biết thêm thông tin về ETag, hãy xem Hướng dẫn tham khảo về API dữ liệu của Google.

Đang thu hồi quyền chia sẻ

Để xoá quyền chia sẻ, trước tiên hãy truy xuất AclEntry rồi gọi phương thức Delete() của ứng dụng.

client.Delete(acl_entry)

Bạn cũng có thể truyền phương thức Delete() đường liên kết edit của mục nhập acl và/hoặc buộc xoá:

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

Để biết thêm thông tin về ETag, hãy xem Hướng dẫn tham khảo về API dữ liệu của Google.

Trở lại đầu trang

Chủ đề đặc biệt

Truy xuất lại nguồn cấp dữ liệu hoặc mục nhập

Nếu muốn truy xuất nguồn cấp dữ liệu hoặc mục nhập mà bạn đã truy xuất trước đây, bạn có thể cải thiện hiệu quả bằng cách cho biết máy chủ để gửi danh sách hoặc mục nhập chỉ khi danh sách hoặc mục nhập đã thay đổi kể từ lần cuối bạn truy xuất.

Để thực hiện kiểu truy xuất có điều kiện này, hãy truyền giá trị ETag vào GetEntry(). Ví dụ: nếu bạn đã có đối tượng 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

Nếu GetEntry() gửi ngoại lệ gdata.client.NotModified, mục nhập sẽ ETag khớp với phiên bản trên máy chủ, tức là bạn có bản sao mới nhất. Tuy nhiên, nếu một khách hàng/người dùng khác đã thực hiện sửa đổi, thì mục nhập mới sẽ được trả về trong entry và sẽ không có trường hợp ngoại lệ nào được gửi.

Để biết thêm thông tin về ETag, hãy xem Hướng dẫn tham khảo về API dữ liệu của Google.

Trở lại đầu trang