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 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ề 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 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.
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 phải xác thực. Thông thường, nhà phát triển in một số văn bản và một đường liên kết để hướng người dùng
vào 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 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 một 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 tham số truy vấn được
Trình xử lý AuthSubRequest):
- 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/ - secure, một giá trị boolean cho biết 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 (phiên), boolean thứ hai để cho biết sau này mã thông báo dùng một lần 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
Hãy xem phần 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 phần 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
Hãy 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 đã có được mã thông báo phiên dài hạn,
lưu trữ mã thông báo đó trong cơ sở dữ liệu của bạn để truy lại và sử dụng sau này. 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.
Dùng client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) để đặt mộ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/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.
Xem hướng dẫn về cách 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
Hãy xem bài viết Sử dụng OAuth với Thư viện ứng dụng Google Data API.
Cấp quyền mã thông báo yêu cầu
Hãy 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
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 đã nhận thành công mã truy cập OAuth,
lưu trữ mã thông báo đó trong cơ sở dữ liệu của bạn để truy lại và 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.
Dùng client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) để đặt một mã thông báo hiện có trên ứng dụng.
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.
Xem hướng dẫn về cách 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 được kế thừa từ
GDClient. Chỉ định địa chỉ email và
mật khẩu của người dùng mà khách hà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 của bạn 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 nhằm sử dụng sau này. Không cần phải nhắc người dùng nhập mật khẩu mỗi lần chạy ứng dụng của bạn. 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ể 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 đề, 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)
Đ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.
Đ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.
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.
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.
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:
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. 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ớia-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.
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)
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.
Đ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
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.
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.