Quan trọng: Tài liệu này được viết trước năm 2012. Các 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 không được dùng nữa kể từ ngày 20 tháng 4 năm 2012 và không còn hoạt động nữa. Bạn nên chuyển sang OAuth 2.0 càng sớm càng tốt.
API dữ liệu của 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 lịch sử 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ề chức năng của API Dữ liệu trang web, hướng dẫn này còn đưa ra các ví dụ về cách tương tác với API bằng cách sử 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ài viết Bắt đầu sử dụng Thư viện ứng dụng Python dữ liệu của Google. Nếu bạn muố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 API Sites cũ, vui lòng xem hướng dẫn về giao thức.
Đối tượng người xem
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 Thư viện ứng dụng Google Data Python.
Bắt đầu
Để dùng thư viện ứng dụng Python, bạn cần Python 2.2 trở lên và các mô-đun được liệt kê trên trang wiki DependencyModules. 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 Python dữ liệu của Google để đượ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 đủ đang 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 không cung cấp cờ bắt buộc, ứ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 API của Sites 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 cũng sẽ 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 mình, 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 API Sites cũ.
Chuyển tên ứng dụng và tên trang web của Trang web (từ URL của ứng dụng):
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Để làm việc với một trang web được lưu trữ trên miền G Suite, hãy đặt miền bằng cách sử dụ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 nên dùng cho mục đích ghi nhật ký. Mã này phải tuân theo định dạng: company-applicationname-version
Lưu ý: Phần còn lại của hướng dẫn giả định rằng bạn đã tạo một đối tượng SitesClient trong biến client.
Xác thực với API Sites cũ
Bạn có thể 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ư. API Dữ liệu trang web cho phép bạn truy cập vào nguồn cấp dữ liệu riêng tư và công khai, 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 dữ liệu nội dung của một trang web công khai nhưng không được cập nhật trang đó – một hoạt động yêu cầu phải có ứng dụng khách đã xác thực. Bạn có thể thực hiện việc này qua quy trình xác thực tên người dùng/mật khẩu ClientLogin, AuthSub hoặc OAuth.
Vui lòng xem Tổng quan về xác thực API dữ liệu của Google để biết thêm thông tin về AuthSub, OAuth và ClientLogin.
AuthSub dành cho các ứng dụng web
Xác thực AuthSub dành 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 của họ đến tài khoản Google hoặc G Suite. Toán tử không cần quyền truy cập vào tên người dùng và mật khẩu cho người dùng Google Sites mà chỉ cần mã thông báo AuthSub.
Xem hướng dẫn kết hợp AuthSub vào ứng dụng web của bạn
Yêu cầu mã thông báo dùng một lần
Khi người dùng truy cập vào ứng dụng của bạn lần đầu tiên, họ cần xác thực. Thông thường, nhà phát triển in một số văn bản và đường liên kết đưa người dùng đến trang phê duyệt AuthSub để xác thực người dùng và yêu cầu quyền truy cập vào tài liệu của họ. Thư viện ứng dụng Google Data Python cung cấp một hàm generate_auth_sub_url() để tạo URL này. Mã bên dưới thiết lập một đường liên kết đến trang 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()
Nếu bạn muốn xác thực người dùng trên miền do G Suite lưu trữ, hãy chuyển tên miền đó vào 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)
Phương thức generate_auth_sub_url() nhận một vài tham số (tương ứng với các tham số truy vấn mà trình xử lý AuthSubRequest sử dụng):
- URL tiếp theo – URL mà Google sẽ chuyển hướng đến
sau khi người dùng đăng nhập vào tài khoản của họ và cấp quyền truy cập;
http://www.example.com/myapp.pytrong ví dụ trên - phạm vi –
https://sites.google.com/feeds/ - bảo mật, một giá trị boolean cho biết mã thông báo có được dùng ở chế độ bảo mật và đã đăng ký hay không;
Truetrong ví dụ trên - session, một boolean thứ hai cho biết liệu mã thông báo sử dụng một lần sau đó có được đổi lấy mã thông báo phiên hay không;
Truetrong ví dụ trên
Nâng cấp lên mã thông báo phiên
Xem Sử dụng AuthSub với thư viện ứng dụng Google Data API.
Truy xuất thông tin về mã phiên
Xem Sử dụng AuthSub với thư viện ứng dụng Google Data API.
Thu hồi mã phiên
Xem Sử dụng AuthSub với thư viện ứng dụng Google Data API.
Mẹo: Sau khi ứng dụng của bạn lấy thành công mã thông báo phiên hoạt động tồn tại trong thời gian dài, hãy lưu trữ mã thông báo đó trong cơ sở dữ liệu để gọi lại để sử dụng sau này. Không cần gửi người dùng lại AuthSub mỗi lần chạy ứng dụng.
Sử dụng client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) để thiết lập mã thông báo hiện có trên ứng dụng.
OAuth cho web hoặc ứng dụng đã cài đặt/thiết bị di động
Có thể sử dụng OAuth làm giải pháp 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ả các yêu cầu dữ liệu phải có chữ ký số và bạn phải đăng ký miền của mình.
Xem hướng dẫn kết hợp OAuth vào ứng dụng đã cài đặt
Đang tìm nạp mã thông báo yêu cầu
Xem bài viết Sử dụng OAuth với thư viện ứng dụng Google Data API.
Uỷ quyền mã thông báo yêu cầu
Xem bài viết Sử dụng OAuth với thư viện ứng dụng Google Data API.
Nâng cấp lên mã truy cập
Xem bài viết Sử dụng OAuth với thư viện ứng dụng Google Data API.
Mẹo: Sau khi ứng dụng của bạn lấy thành công mã truy cập OAuth, hãy lưu trữ mã thông báo đó trong cơ sở dữ liệu của bạn để gọi lại để sử dụng sau này. Bạn không cần phải gửi lại người dùng thông qua OAuth mỗi lần chạy ứng dụng.
Sử dụng client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) để thiết lập mã thông báo hiện có trên ứng dụng.
ClientLogin cho ứng dụng đã cài đặt/dành cho thiết bị di động
Bạn nên sử dụng ClientLogin cho các ứng dụng đã cài đặt hoặc dành cho thiết bị di động cần xác thực người dùng trong Tài khoản Google. Trong lần chạy đầu tiên, ứng dụng 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 sẽ được tham chiếu.
Xem hướng dẫn kết hợp ClientLogin vào ứng dụng đã cài đặt
Để sử dụng ClientLogin, hãy gọi phương thức ClientLogin() của đối tượng SitesClient. Đối tượng này được kế thừa từ GDClient. Hãy chỉ định địa chỉ email và mật khẩu của người dùng mà ứng dụng của bạn thay mặt gửi yêu cầu. Ví dụ:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Mẹo: Sau khi ứng dụng xác thực thành công người dùng lần đầu tiên, hãy lưu trữ mã xác thực trong cơ sở dữ liệu để thu hồi để dùng sau. Không cần nhắc người dùng về mật khẩu của họ trong mỗi lần bạn chạy ứng dụng. Hãy xem phần Gọi lại mã thông báo xác thực để biết thêm thông tin.
Để biết thêm thông tin về cách sử dụng ClientLogin trong các ứng dụng Python, hãy xem phần Sử dụng ClientLogin với thư viện ứng dụng API dữ liệu của Google.
Nguồn cấp dữ liệu trang web
Nguồn cấp dữ liệu trang web có thể dùng để liệt kê các 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 công cụ này để tạo và/hoặc sao chép toàn bộ trang web.
Trang web danh sách
Để 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 sẽ sử dụng một đối số
không bắt buộc là 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. Vui lòng xem phần Bắt đầu để biết thêm thông tin về cách đặt các giá trị này trên đối tượng ứng dụng.
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 cho 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 một đối số không bắt buộc là uri. Bạn có thể sử dụng đối số này để chỉ định URI nguồn cấp dữ liệu trang web thay thế (trong trường hợp tạo trang web ở 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 với chủ đề "phương tiện chặn" và cung cấp tiêu đề cũng như nội dung 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 trong miền G Suite example2.com.
Do đó, URL của trang web này 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 đối tượng gdata.sites.data.SiteEntry, chứa các phần tử do máy chủ thêm vào: đường liên kết đến trang web, đường liên kết đến nguồn cấp dữ liệu acl của trang web, tên trang web, tiêu đề, thông tin 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ể dùng CreateSite() để sao chép một trang web hiện có. Để làm việc này, hãy truyền đối số từ khoá source_site.
Mọi trang web được sao chép đều có đường liên kết này. Bạn có thể truy cập vào đường liên kết này qua entry.FindSourceLink(). Sau đâ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
Lưu ý quan trọng:
- Chỉ những trang web và mẫu trang web mà người dùng đã xác thực mới có thể sao chép.
- Bạn cũng có thể sao chép mẫu trang web. Trang web được xem là một mẫu nếu chế độ cài đặt "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 trang web từ một miền khác, trong khi chờ 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 của một trang web, bạn cần có SiteEntry chứa trang web có liên quan. 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 thành phần đó:
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)
Đ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. Khách hàng của bạn phải xác thực bằng mã thông báo AuthSub, OAuth hoặc ClientLogin. Hãy xem phần 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ác thay đổi) của một Trang web 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 này:
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ề đối tượng gdata.sites.data.ActivityFeed chứa danh sách gdata.sites.data.ActivityEntry. Mỗi mục hoạt động chứa thông tin về một thay đổi đã được thực hiện đối với Trang web.
Đ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. Khách hàng của bạn phải xác thực bằng mã thông báo AuthSub, OAuth hoặc ClientLogin. Hãy xem phần Xác thực với dịch vụ Sites.
Nguồn cấp dữ liệu bản sửa đổi cung cấp thông tin về nhật ký sửa đổi cho bất kỳ mục nội dung nào. Bạn có thể sử dụng phương thức GetRevisionFeed() để tìm nạp bản sửa đổi cho một mục nội dung nhất định. Phương thức này sẽ sử dụng một tham số uri không bắt buộc chấp nhận gdata.sites.data.ContentEntry, URI đầy đủ của một mục 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 sửa đổi cho mục 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ề đối tượng gdata.sites.data.RevisionFeed chứa danh sách gdata.sites.data.RevisionEntry. Mỗi mục sửa đổi chứa các thông tin, chẳng hạn như nội dung của bản sửa đổi đó, số phiên bản và thời điểm tạo phiên bản mới.
Nguồn cấp dữ liệu nội dung
Truy xuất nguồn cấp nội dung
Lưu ý: Nguồn cấp dữ liệu nội dung có thể yêu cầu hoặc không, tuỳ thuộc vào quyền chia sẻ của Trang web. Nếu Trang web không công khai, ứ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 phần 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 một Trang web. Bạn có thể truy cập thư viện này bằng cách gọi phương thức GetContentFeed() của lib. Phương thức này sẽ lấy tham số chuỗi uri không bắt buộc để truyền một truy vấn 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 một số phần tử 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 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 đó. Hãy xem ứng dụng mẫu để biết rõ hơn về một số thuộc tính có sẵn trong mỗi loại mục nhập.
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 API Dữ liệu của Google chuẩn và các tham số truy vấn 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 tham 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 cụ thể, hãy sử dụng tham số kind. Ví dụ: đoạn mã này chỉ trả về các mục nhập attachment:
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 dữ liệu, hãy phân tách từng kind bằng dấu phẩy. Ví dụ: đoạn mã này trả về các mục filecabinet và 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 trang web tạo bằng Google Sites, bạn có thể sử dụng tham số path để tìm nạp trang cụ thể đó.
Ví dụ này sẽ trả về trang tại 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 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ụ bên dưới), bạn có thể sử dụng tham số parent
để tìm nạp tất cả các mục con của trang đó (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 thêm các thông số khác, hãy xem Hướng dẫn tham khảo.
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 đó 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 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ụ sau đây sẽ tạo một webpage mới trong cấp cao nhất, bao gồm một số ngôn ngữ sau tuỳ chỉnh cho phần nội dung của trang và đặt tiêu đề cho tiêu đề trang là "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 nhập đượ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 tạo gdata.sites.data.ContentEntry theo cách thủ công, điền vào các thuộc tính mà bạn quan tâm rồi 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ể đặt thuộc tính page_name trên mục nội dung. Trình trợ giúp CreatePage() cung cấp giá trị này dưới dạng một đối số từ khoá không bắt buộc.
Ví dụ này tạo một trang filecabinet mới có tiêu đề "Bộ nhớ tệp", nhưng sẽ tạo trang 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 đường dẫn URL của một trang:
page_name, nếu có. Phải đáp ứnga-z, A-Z, 0-9, -, _.title, không được để trống nếu không có tên trang. Theo cách chuẩn hoá, bạn sẽ cắt bỏ + thu gọn khoảng trắng thành "*" và xoá các ký tự không khớp vớia-z, A-Z, 0-9, -, _.
Tạo trang con
Để tạo trang con (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 đầ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 bên dưới nguồn cấp dữ liệu đầu tiên được 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
Cũ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 chính. Tệp đính kèm phải được tải
lên trang gốc. Do đó, bạn phải thiết lập đường liên kết mẹ trên ContentEntry mà bạn muốn tải lên. Hãy 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 sẽ tải một tệp PDF lên filecabinet đầu tiên có trong nguồn cấp nội dung của người dùng.
Tệp đính kèm sẽ được tạo với tiêu đề "Sổ tay nhân viên mới" và phần mô tả (không bắt buộc) là "Gói nhân sự".
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
Các thư mục hỗ trợ tệp trong Google Sites. UploadAttachment() cung cấp một đối số từ khoá bổ sung, folder_name mà bạn có thể sử dụng để tải tệp đính kèm lên thư mục filecabinet. Bạn 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 truyền đối tượng gdata.data.MediaSource đến UploadAttachment() thay vì đường dẫn tệp. Phương thức này cũng không truyền một 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 trên web là 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 filecabinet của mình. Tính năng này tương tự như phương thức tải lên "Thêm tệp bằng URL" trong giao diện người dùng của Google Sites.
Lưu ý: Bạn chỉ có thể tạo tệp đính kèm trên 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 trên web trong filecabinet đầu tiên có trong nguồn cấp nội dung của người dùng.
Tiêu đề và nội dung mô tả (không bắt buộc) của biểu trưng được đặt lần lượt thành "GoogleBiểu trưng" và "màu sắc đẹ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!'
Lệnh gọi này tạo một đường liên kết trỏ đến hình ảnh tại "http://www.google.com/images/logo.gif" trong filecabinet.
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
Bạn 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 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 đã 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 và 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 một tệp đính kèm bằng cách tạo một đối tượng MediaSource mới với nội dung tệp mới và gọi phương thức Update() của ứng dụng. Bạn cũng có thể cập nhật siêu dữ liệu của tệp đính kèm (chẳng hạn như tiêu đề và nội dung mô tả) hoặc chỉ cập nhật siêu dữ liệu.
Ví dụ dưới đây 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)
Xoá nội dung
Để xoá một trang hoặc một mục khỏi một trang web tạo bằng Google Sites, trước tiên, hãy truy xuất mục nội dung đó, sau đó gọi phương thức Delete() của ứng dụng.
client.Delete(content_entry)
Bạn cũng có thể chuyển phương thức Delete() liên kết edit của mục nhập nội dung và/hoặc buộc xoá:
# 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 API dữ liệu của Google.
Đ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ể dùng để tải nội dung của tệp xuống.
Ứng dụng Sites chứa một 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 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 đối số thứ hai.
Ví dụ này tìm nạp một mục đính kèm cụ thể (bằng cách truy vấn đường liên kết self của mục đó) và tải tệp đó xuống đường dẫn đã 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. Bạn có thể tìm thấy loại nội dung trong entry.content.type.
Trong một số trường hợp, bạn không thể tải 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 mẫu này là một tệp đính kèm vào bộ nhớ.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
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à trang web công khai). Các mục nhập sẽ chỉ được 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 mỗi địa chỉ email trong bảng điều khiển "Người có quyền truy cập" trên 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 hiển thị, mặc dù họ có quyền truy cập ngầm định vào một trang web.
Vai trò
Phần tử vai trò thể hiện cấp truy cập mà một thực thể có thể có. Phần tử gAcl:role có thể có bốn giá trị:
- người đọc – người xem (tương đương với quyền chỉ có thể đọc).
- tác giả – một cộng tác viên (tương đương với quyền đọc/ghi).
- chủ sở hữu — thường là quản trị viên trang web (tương đương với quyền đọc/ghi).
Kính ngắm
Phần tử phạm vi đại diện cho thực thể có cấp truy cập này. Có thể có 4 loại phần tử gAcl:scope:
- user — giá trị địa chỉ email, ví dụ: "user@gmail.com".
- group — địa chỉ email của Google Group, ví dụ: "group@domain.com".
- domain — tên miền G Suite, ví dụ như "domain.com".
- default – Chỉ có thể có một phạm vi thuộc loại "mặc định" 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 được đặt thành quyền truy cập "chủ sở hữu", chúng chỉ có thể là người đọc hoặc người ghi.
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 một 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 đặt trên đối tượng SitesClient và in 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 gdata.sites.data.AclEntry.
Nếu bạn đang làm việc với các mục nhập trong SiteFeed, 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 web đó:
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ẻ trang web
Lưu ý: Bạn chỉ có thể sử dụng một số ACL chia sẻ nhất định nếu miền được định cấu hình để cho phép các quyền đó (ví dụ: nếu bạn bật tính năng chia sẻ bên ngoài miền cho các miền G Suite, 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 có giá trị gdata.acl.data.AclScope và gdata.acl.data.AclRole mong muốn. Xem phần Tổng quan về nguồn cấp dữ liệu ACL để biết các giá trị AclScope và AclRoles có thể có.
Ví dụ sau đâ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 trên một nhóm Google hoặc miền G Suite. Giá trị scope cần thiết được liệt kê dưới đây.
Đang chia sẻ với địa chỉ email của 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')
Chúng tôi chỉ hỗ trợ chia sẻ ở cấp miền cho các miền G Suite và chỉ cho miền mà trang web được 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, không phải domain2.com. Các 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 các 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 đề cập, sửa đổi quyền theo ý muốn, sau đó gọi phương thức Update() của ứng dụng để sửa đổi Danh sách kiểm soát quyền truy cập (ACL) trên máy chủ.
Ví dụ này sửa đổi acl_entry trước đây của chúng ta trong phần Chia sẻ một trang web, bằng cách cập nhật "user@example.com" thành một người viết (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 API dữ liệu của Google.
Đang xoá quyền chia sẻ
Để xoá quyền chia sẻ, trước tiên, hãy truy xuất AclEntry, sau đó 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() của đườ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 API dữ liệu của Google.
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 một nguồn cấp dữ liệu hoặc mục nhập mà bạn đã truy xuất trước đó, bạn có thể cải thiện tính hiệu quả bằng cách yêu cầu máy chủ chỉ gửi danh sách hoặc mục nhập nếu danh sách hoặc mục nhập đó đã thay đổi kể từ lần gần nhất bạn truy xuất.
Để thực hiện loại 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ó sẵn một đố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() trả về trường hợp ngoại lệ gdata.client.NotModified, ETag của mục nhập sẽ khớp với phiên bản trên máy chủ, nghĩa là bạn có bản sao mới nhất.
Tuy nhiên, nếu một ứng dụng/người dùng khác đã thực hiện sửa đổi, mục nhập mới sẽ được trả về trong entry và không có 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 API dữ liệu của Google.