Lưu ý 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 ngừng hoạt động kể từ ngày 20 tháng 4 năm 2012 và không còn được cung cấp nữa. Bạn nên chuyển sang OAuth 2.0 càng sớm càng tốt.
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ề các tính năng của API Dữ liệu trang web, 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 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 Google Data Python. 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 trang web 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 có tương tác với Google Sites bằ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. 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 Data Python cho 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 hoạt động đầy đủ 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 bạn 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 Sites cũ. Do đó, bạn cần xác thực để thực hiện một số thao tác (ví dụ: sửa đổi nội dung). Chương trình cũng sẽ nhắc bạn xác thực thông 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âu lệnh import sau:
import atom.data import gdata.sites.client import gdata.sites.data
Bạn cũng cần thiết lập đối tượng SitesClient. Đối tượng này đại diện cho kết nối ứng dụng khách với API trang web cũ.
Truyền vào tên ứng dụng và tên không gian 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 một Trang web được lưu trữ trên miền G Suite, hãy thiết lập 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ý. Mã này 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 với 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ư. API Dữ liệu trang web cung cấp quyền truy cập vào nguồn cấp dữ liệu công khai và riêng tư, tuỳ thuộc vào quyền của Trang web và thao tác 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 thể cập nhật nguồn cấp dữ liệu đó – một thao tác yêu cầu ứng dụng được xác thực. Bạn có thể thực hiện việc này thông qua tính năng 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ề quy trình 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 ứng dụng web
Xác thực AuthSub cho ứng dụng web nên được các ứng dụng khách sử dụng để xác thực người dùng của họ với tài khoản Google hoặc G Suite. Người vận hành không cần quyền truy cập vào tên người dùng và mật khẩu của người dùng Google Sites – chỉ cần có mã thông báo AuthSub.
Xem hướng dẫn về cách 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 sẽ in một số văn bản và đường liên kết hướng 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 đườ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 được lưu trữ bằng G Suite, hãy truyề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 số 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 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/ - secure, một boolean để cho biết liệu mã thông báo có được sử dụng ở chế độ an toàn 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 dùng một lần có được trao đổi cho 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
Hãy xem bài viết Sử dụng AuthSub với Thư viện ứng dụng API Dữ liệu của Google.
Truy xuất thông tin về mã thông báo phiên
Hãy xem bài viết Sử dụng AuthSub với Thư viện ứng dụng API Dữ liệu của Google.
Thu hồi mã thông báo phiên
Xem phần Sử dụng AuthSub với Thư viện ứng dụng API Dữ liệu của Google.
Mẹo: Sau khi ứng dụng của bạn đã thu nạp thành công mã thông báo phiên hoạt động dài hạn, hãy lưu trữ mã thông báo đó trong cơ sở dữ liệu để gọi lại khi cần. Không cần phải gửi lại người dùng cho AuthSub mỗi lần chạy ứng dụng.
Sử dụng client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) để đặt mã thông báo hiện có trên ứng dụng.
OAuth cho web hoặc ứng dụng đã cài đặt/ứng dụng di động
OAuth có thể được sử 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 ở chỗ tất cả yêu cầu dữ liệu phải được ký bằng kỹ thuật số và bạn phải đăng ký miền của mình.
Xem hướng dẫn để tích 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 API Dữ liệu của Google.
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 API Dữ liệu của Google.
Nâng cấp lên mã truy cập
Hãy 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 đã thu nạp thành công mã truy cập OAuth, hãy lưu trữ mã đó trong cơ sở dữ liệu để gọi lại khi cần sử dụng sau này. Bạn không cần 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) để đặt mã thông báo hiện có trên ứng dụng.
ClientLogin cho ứng dụng đã cài đặt/ứng dụng di động
ClientLogin phải được sử dụng bởi các ứng dụng đã cài đặt hoặc ứng dụng di động cần xác thực người dùng của họ 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. Trên 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 để tích 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 được kế thừa từ GDClient. Chỉ định địa chỉ email và mật khẩu của người dùng mà ứng dụng của bạn đang thay mặt để đưa ra 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ã thông báo xác thực trong cơ sở dữ liệu để gọi lại khi cần sử dụng sau này. Bạn không cần nhắc người dùng nhập mật khẩu mỗi khi 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
Bạn có thể dùng nguồn cấp dữ liệu trang web để liệt kê những trang web Google Sites mà người dùng sở hữu hoặc có quyền xem. Bạn cũng có thể sử dụng lệnh 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 tính nă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 sẽ lấy 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ế. 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. 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 của bạn.
Sau đâ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 đối số không bắt buộc là uri. Bạn có thể 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 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ó giao diện "slate" 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 sẽ là https://sites.google.com/a/example2.com/title-for-my-site.
Nếu tạo thành công trang web, máy chủ sẽ phản hồi bằng một đối tượng gdata.sites.data.SiteEntry, được điền sẵn 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 đề, 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ể 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.
Mọi trang web đã được sao chép đều có đường liên kết này và bạn có thể truy cập vào đường liên kết này thông qua entry.FindSourceLink(). Dưới đây là ví dụ về cách sao chép trang web đã 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
Các đ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 bạn chọn chế độ cài đặt "Xuất bản trang web này dưới dạng mẫu" 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 nội dung 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() để trước tiên tìm nạp SiteEntry, 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)
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. Xem phần Xác thực với dịch vụ Trang web.
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 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.
Đang tìm nạp nhật ký sửa đổi
Lưu ý: Bạn phải là cộng tác viên hoặc chủ sở hữu của Trang web thì mới có thể truy cập vào nguồn cấp dữ liệu này. Ứ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. Xem phần Xác thực với dịch vụ Trang web.
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 mọi mục nội dung. Bạn có thể sử dụng phương thức GetRevisionFeed() để tìm nạp các bản sửa đổi cho một mục nội dung nhất định. Phương thức này sử dụng 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 nội dung.
Ví dụ này truy vấn nguồn cấp dữ liệu nội dung và tìm nạp nguồn cấp dữ liệu bản 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ề một đố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 thông tin như nội dung tại lầ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 nội dung
Truy xuất nguồn cấp dữ liệu nội dung
Lưu ý: Nguồn cấp dữ liệu nội dung có thể yêu cầu xác thực 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ã AuthSub, OAuth hoặc ClientLogin. Xem phần Xác thực với dịch vụ Trang web.
Nguồn cấp dữ liệu nội dung trả về nội dung mới nhất của Trang web. Bạn có thể truy cập vào lớp này bằng cách gọi phương thức GetContentFeed() của thư viện. Phương thức này sẽ nhận một 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 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 gdata.sites.data.ContentEntry. Mỗi mục nhập đại diện cho một trang/mặt hàng 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 để hiểu 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 dữ liệu nội dung
Bạn có thể tìm kiếm nguồn cấp dữ liệu nội dung bằng một số tham số truy vấn API Dữ liệu Google tiêu chuẩn và các tham số dành riêng cho API trang web kiểu 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ề 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 Google Site, 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 nằm 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 một trang mẹ
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ả mục nhập 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 thông số, 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 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 của 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 tạo một webpage mới ở cấp cao nhất, bao gồm một số XHTML cho phần 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 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 đối số 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 đề "File Storage" (Bộ nhớ tệp), nhưng lại 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 cho đườ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. Việc chuẩn hoá là cắt bớt + 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 các trang con (con) trong một 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 dữ liệu nội dung cho announcementpage và tạo một announcement mới trong announcementpage đầ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
Tương tự như trong Google Sites, API hỗ trợ việc tải tệp đính kèm lên trang tủ hồ sơ hoặc trang mẹ. Bạn phải tải tệp đính kèm lên một trang mẹ. Do đó, bạn phải đặt đường liên kết mẹ trên ContentEntry mà bạn đang cố 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 tìm thấy trong nguồn cấp dữ liệu 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 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 quá trình tải lên thành công, attachment sẽ chứa 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
Hộp tệp trong Google Sites hỗ trợ thư mục. UploadAttachment() cung cấp một đối số từ khoá bổ sung, folder_name mà bạn có thể 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 truyền đối tượng gdata.data.MediaSource đến UploadAttachment() thay vì đường dẫn tệp. Loại này cũng không truyền 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à một loại tệp đính kèm đặc biệt. Về cơ bản, đây 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 theo 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 "GoogleBiểu trưng" và "màu sắc đẹp" tương ứng.
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 đề, pageName, v.v.) và nội dung trang của bất kỳ loại mục nhập nào bằng cách sử dụ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 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 tệp đính kèm bằng cách tạo đố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. 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ả) cũng có thể được cập nhật hoặc chỉ đơn giản là siêu dữ liệu.
Ví dụ nà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 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ể truyền phương thức Delete() đường 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 về 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 src nội dung có thể dùng để tải nội dung 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 này trong 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).
Đối với những trường hợp nà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
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 một vai trò truy cập của một 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ỉ xuất hiện cho những thực thể có quyền truy cập rõ ràng – một mục nhập sẽ xuất hiện cho mỗi địa chỉ email trong bảng "Những 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 xuất hiện, mặc dù họ có quyền truy cập ngầm 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ó. Có 4 giá trị có thể có của phần tử gAcl:role:
- reader – người xem (tương đương với quyền chỉ có thể đọc).
- writer (người ghi) – 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).
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 có thể có:
- người dùng — một giá trị địa chỉ email, ví dụ: "user@gmail.com".
- group – địa chỉ email Google Groups, ví dụ: "group@domain.com".
- domain – tên miền 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 mà bất kỳ người dùng nào có theo mặc định trên một trang web công khai.
Lưu ý: Các miền không được đặt giá trị gAcl:role thành quyền truy cập "chủ sở hữu", mà chỉ có thể là quyền đọc hoặc 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 trang web và có thể được tìm nạp bằng phương thức GetAclFeed().
Ví dụ sau đây sẽ 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 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 trong SiteFeed, thì mỗi SiteEntry sẽ chứa một đường liên kết đến nguồn cấp dữ liệu ACL của mục đó.
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 ý: 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 để cho phé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 Google bằng API, hãy tạo một gdata.sites.gdata.AclEntry có các giá trị gdata.acl.data.AclScope và gdata.acl.data.AclRole mong muốn. Hãy 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ụ 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à 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 trên Google Groups hoặc miền G Suite. Các giá trị scope cần thiết được liệt kê bên dưới.
Cách 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')
Tính năng chia sẻ ở cấp miền chỉ được hỗ trợ cho các miền G Suite và chỉ dành cho miền lưu trữ trang web. 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 phải miền2.com. Những trang web không được lưu trữ trên một 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, sửa đổi quyền như mong muốn, sau đó gọi phương thức Update() của ứng dụng để sửa đổi ACL trên máy chủ.
Ví dụ này sửa đổi acl_entry trước đó trong phần Chia sẻ trang web, bằng cách cập nhật "user@example.com" thành 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 về API Dữ liệu của Google.
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() đường liên kết edit của mục 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.
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 đó, bạn có thể cải thiện 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 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ó một đối tượng entry hiện có:
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, thì ETag của mục nhập sẽ 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 ứng dụ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à 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.