Penting: Dokumen ini ditulis sebelum tahun 2012. Opsi autentikasi yang dijelaskan dalam dokumen ini (OAuth 1.0, AuthSub, dan ClientLogin) secara resmi tidak digunakan lagi sejak 20 April 2012 dan tidak lagi tersedia. Sebaiknya Anda bermigrasi ke OAuth 2.0 sesegera mungkin.
Google Sites Data API memungkinkan aplikasi klien mengakses, memublikasikan, dan mengubah konten dalam Situs Google. Aplikasi klien juga dapat meminta daftar aktivitas terbaru, mengambil histori revisi, dan mendownload lampiran.
Selain memberikan beberapa latar belakang tentang kemampuan Sites Data API, panduan ini memberikan contoh untuk berinteraksi dengan API menggunakan library klien Python. Untuk mendapatkan bantuan terkait penyiapan library klien, lihat Mulai Menggunakan Library Klien Python Data Google. Jika Anda ingin memahami lebih lanjut protokol dasar yang digunakan oleh library klien Python untuk berinteraksi dengan Sites API klasik, lihat panduan protokol.
Audiens
Dokumen ini ditujukan untuk developer yang ingin menulis aplikasi klien yang berinteraksi dengan Google Sites menggunakan Library Klien Python Google Data.
Memulai
Untuk menggunakan library klien Python, Anda memerlukan Python 2.2+ dan modul yang tercantum pada halaman wiki DependencyModules. Setelah mendownload library klien, lihat Memulai Library Google Data Python untuk mendapatkan bantuan tentang cara menginstal dan menggunakan klien.
Menjalankan contoh
Contoh yang berfungsi penuh terletak di subdirektori samples/sites dari repositori Mercurial project
(/samples/sites/sites_example.py).
Jalankan contoh sebagai berikut:
python sites_example.py # or python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]
Jika tanda yang diperlukan tidak diberikan, aplikasi akan meminta Anda untuk memasukkan nilai-nilai tersebut. Contoh ini memungkinkan pengguna melakukan sejumlah operasi yang menunjukkan cara menggunakan Sites API klasik. Karena itu, Anda harus melakukan autentikasi untuk melakukan operasi tertentu (misalnya, memodifikasi konten). Program ini juga akan meminta Anda untuk melakukan autentikasi melalui AuthSub, OAuth, atau ClientLogin.
Untuk menyertakan contoh dalam panduan ini ke dalam kode Anda sendiri, Anda memerlukan pernyataan import berikut:
import atom.data import gdata.sites.client import gdata.sites.data
Anda juga perlu menyiapkan objek SitesClient, yang mewakili koneksi klien ke Sites API klasik.
Teruskan nama aplikasi Anda dan nama ruang web Situs (dari URL-nya):
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Untuk bekerja dengan Situs yang dihosting di domain G Suite, setel domain menggunakan parameter domain:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')
Dalam cuplikan di atas, argumen source bersifat opsional, tetapi direkomendasikan untuk tujuan logging. Formatnya
harus mengikuti: company-applicationname-version
Catatan: Bagian selanjutnya dari panduan ini mengasumsikan bahwa Anda membuat objek SitesClient dalam variabel client.
Mengautentikasi ke Sites API klasik
Library klien Python dapat digunakan untuk bekerja dengan feed publik atau pribadi. Sites Data API menyediakan akses ke feed pribadi dan publik, bergantung pada izin Situs dan operasi yang Anda coba lakukan. Misalnya, Anda mungkin dapat membaca feed konten Situs publik tetapi tidak dapat memperbaruinya - sesuatu yang memerlukan klien terautentikasi. Hal ini dapat dilakukan melalui autentikasi nama pengguna/sandi ClientLogin, AuthSub, atau OAuth.
Lihat Ringkasan Autentikasi Google Data API untuk mengetahui informasi selengkapnya tentang AuthSub, OAuth, dan ClientLogin.
AuthSub untuk aplikasi web
AuthSub Authentication untuk Aplikasi Web harus digunakan oleh aplikasi klien yang perlu mengautentikasi penggunanya ke akun Google atau G Suite. Operator tidak memerlukan akses ke nama pengguna dan sandi untuk pengguna Google Sites - hanya token AuthSub yang diperlukan.
Lihat petunjuk untuk memasukkan AuthSub ke dalam aplikasi web Anda
Meminta token sekali pakai
Saat pengguna pertama kali mengunjungi aplikasi Anda, mereka harus melakukan autentikasi. Biasanya, developer akan mencetak sejumlah teks dan link yang mengarahkan pengguna ke halaman persetujuan AuthSub untuk mengautentikasi pengguna dan meminta akses ke dokumen mereka. Library klien Python Google Data menyediakan fungsi, generate_auth_sub_url() untuk membuat URL ini. Kode di bawah ini mengatur link ke halaman 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()
Jika Anda ingin mengautentikasi pengguna di domain yang dihosting G Suite, teruskan nama domain tersebut ke 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)
Metode generate_auth_sub_url() memerlukan beberapa parameter (sesuai dengan parameter kueri yang digunakan oleh pengendali AuthSubRequest):
- URL next — URL yang akan dialihkan oleh Google
setelah pengguna login ke akun mereka dan memberikan akses;
http://www.example.com/myapp.pydalam contoh di atas - cakupan —
https://sites.google.com/feeds/ - secure, boolean untuk menunjukkan apakah token akan digunakan dalam mode aman dan terdaftar atau tidak;
Truepada contoh di atas - session, boolean kedua untuk menunjukkan apakah token sekali pakai nantinya akan ditukar dengan token sesi atau tidak;
Truedalam contoh di atas
Mengupgrade ke token sesi
Lihat Menggunakan AuthSub dengan Library Klien Google Data API.
Mengambil informasi tentang token sesi
Lihat Menggunakan AuthSub dengan Library Klien Google Data API.
Mencabut token sesi
Lihat Menggunakan AuthSub dengan Library Klien Google Data API.
Tips: Setelah aplikasi Anda berhasil memperoleh token sesi yang berumur panjang,
simpan token tersebut di database Anda agar dapat diingat untuk digunakan nanti. Tidak perlu mengarahkan pengguna kembali ke AuthSub setiap kali aplikasi dijalankan.
Gunakan client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) untuk menetapkan token yang ada di klien.
OAuth untuk web atau aplikasi terinstal/seluler
OAuth dapat digunakan sebagai alternatif untuk AuthSub, dan ditujukan untuk aplikasi web. OAuth mirip dengan menggunakan mode aman dan terdaftar dari AuthSub, yaitu semua permintaan data harus ditandatangani secara digital dan Anda harus mendaftarkan domain Anda.
Lihat petunjuk untuk menyertakan OAuth ke dalam aplikasi yang terinstal
Mengambil token permintaan
Lihat Menggunakan OAuth dengan Library Klien Google Data API.
Memberi otorisasi token permintaan
Lihat Menggunakan OAuth dengan Library Klien Google Data API.
Mengupgrade ke token akses
Lihat Menggunakan OAuth dengan Library Klien Google Data API.
Tips: Setelah aplikasi Anda berhasil memperoleh token akses OAuth,
simpan token tersebut di database Anda agar dapat diingat kembali untuk digunakan di lain waktu. Anda tidak perlu mengirim kembali pengguna melalui OAuth pada setiap kali aplikasi dijalankan.
Gunakan client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) untuk menetapkan token yang ada di klien.
ClientLogin untuk aplikasi yang diinstal/seluler
ClientLogin harus digunakan oleh aplikasi seluler atau yang terinstal yang perlu mengautentikasi penggunanya ke akun Google. Saat pertama kali dijalankan, aplikasi Anda akan meminta nama pengguna/sandi kepada pengguna. Pada permintaan berikutnya, token autentikasi akan direferensikan.
Lihat petunjuk untuk menggabungkan ClientLogin ke dalam aplikasi yang terinstal
Untuk menggunakan ClientLogin, panggil metode
ClientLogin()
dari objek SitesClient, yang diwarisi dari
GDClient. Tentukan alamat email dan sandi pengguna yang diatasnamakan untuk klien Anda membuat permintaan. Contoh:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Tips: Setelah aplikasi Anda berhasil mengautentikasi pengguna untuk pertama kalinya, simpan token autentikasi di database Anda agar dapat diingat untuk digunakan nanti. Tidak perlu meminta sandi kepada pengguna setiap kali aplikasi Anda dijalankan. Lihat Mengingat kembali token autentikasi untuk informasi selengkapnya.
Untuk informasi selengkapnya tentang penggunaan ClientLogin pada aplikasi Python, lihat Menggunakan ClientLogin dengan Library Klien Google Data API.
Feed Situs
Feed situs dapat digunakan untuk mencantumkan Google Sites yang dimiliki pengguna atau izin lihatnya dimiliki pengguna. Parameter ini juga dapat digunakan untuk mengubah nama situs yang ada. Terakhir, untuk domain G Suite, domain ini juga dapat digunakan untuk membuat dan/atau menyalin seluruh situs.
Mencantumkan situs
Untuk menampilkan daftar situs yang dapat diakses pengguna, gunakan metode GetSiteFeed() klien. Metode ini mengambil argumen opsional, uri, yang dapat Anda gunakan untuk menentukan URI feed situs alternatif. Secara default, GetSiteFeed()
menggunakan nama situs dan domain yang ditetapkan pada objek klien. Lihat bagian Memulai untuk
mengetahui informasi selengkapnya tentang cara menetapkan nilai ini pada objek klien.
Berikut adalah contoh pengambilan daftar situs pengguna yang diautentikasi:
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
Cuplikan di atas mencetak judul situs, nama situs, situs tempatnya disalin, dan URI feed aclnya.
Membuat situs baru
Catatan: Fitur ini hanya tersedia untuk domain G Suite.
Situs baru dapat disediakan dengan memanggil metode CreateSite() library.
Serupa dengan helper GetSiteFeed(), CreateSite() juga menerima
argumen opsional, uri, yang dapat Anda gunakan untuk menentukan URI feed situs alternatif (dalam kasus membuat
situs dalam domain yang berbeda selain yang ditetapkan pada objek SitesClient).
Berikut contoh pembuatan situs baru dengan tema 'slate' serta memberikan judul dan deskripsi (opsional):
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
Permintaan di atas akan membuat situs baru di bawah domain G Suite example2.com.
Dengan demikian, URL situs tersebut akan menjadi https://sites.google.com/a/example2.com/title-for-my-site.
Jika situs berhasil dibuat, server akan merespons dengan objek gdata.sites.data.SiteEntry, yang diisi dengan elemen yang ditambahkan oleh server: link ke situs, link ke feed acl situs,
nama situs, judul, ringkasan, dan sebagainya.
Menyalin situs
Catatan: Fitur ini hanya tersedia untuk domain G Suite.
CreateSite() juga dapat digunakan untuk menyalin situs yang sudah ada. Untuk melakukannya, teruskan argumen kata kunci source_site.
Setiap situs yang telah disalin akan memiliki link ini, yang dapat diakses melalui entry.FindSourceLink(). Berikut adalah contoh duplikasi situs yang dibuat di bagian Membuat situs baru:
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
Poin penting:
- Hanya situs dan template situs milik pengguna terautentikasi yang dapat disalin.
- Template situs juga dapat disalin. Situs adalah template jika setelan "Publikasikan situs ini sebagai template" dicentang di halaman setelan Google Sites.
- Anda dapat menyalin situs dari domain lain, dengan menunggu Anda terdaftar sebagai pemilik di situs sumber.
Memperbarui metadata situs
Untuk memperbarui judul atau ringkasan situs, Anda memerlukan SiteEntry yang berisi situs yang dimaksud. Contoh ini menggunakan metode GetEntry() untuk mengambil SiteEntry terlebih dahulu, lalu mengubah judul, deskripsi, dan tag kategorinya:
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)
Mengambil Feed Aktivitas
Catatan: Untuk mengakses feed ini, Anda harus menjadi kolaborator atau pemilik Situs. Klien Anda harus melakukan autentikasi dengan menggunakan token AuthSub, OAuth, atau ClientLogin. Baca bagian Mengautentikasi ke layanan Sites.
Anda dapat mengambil aktivitas terbaru (perubahan) Situs dengan mengambil feed aktivitas.
Metode GetActivityFeed() library memberikan akses ke feed ini:
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)
Memanggil GetActivityFeed() akan menampilkan objek gdata.sites.data.ActivityFeed yang berisi daftar
gdata.sites.data.ActivityEntry. Setiap entri aktivitas berisi informasi
tentang perubahan yang dilakukan pada Situs.
Mengambil Histori Revisi
Catatan: Untuk mengakses feed ini, Anda harus menjadi kolaborator atau pemilik Situs. Klien Anda harus melakukan autentikasi dengan menggunakan token AuthSub, OAuth, atau ClientLogin. Baca bagian Mengautentikasi ke layanan Sites.
Feed revisi menyediakan informasi tentang histori revisi untuk setiap entri konten. Metode GetRevisionFeed()
dapat digunakan untuk mengambil revisi untuk entri konten tertentu. Metode ini memerlukan parameter uri
opsional yang menerima gdata.sites.data.ContentEntry, URI lengkap entri konten, atau ID entri konten.
Contoh ini membuat kueri feed konten, dan mengambil feed revisi untuk entri konten pertama:
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]
Memanggil GetRevisionFeed() akan menampilkan objek gdata.sites.data.RevisionFeed yang berisi daftar
gdata.sites.data.RevisionEntry. Setiap entri revisi berisi informasi seperti konten pada revisi tersebut, nomor versi, dan kapan versi baru dibuat.
Feed konten
Mengambil feed konten
Catatan: Feed konten mungkin memerlukan atau tidak memerlukan autentikasi; bergantung pada izin berbagi Situs. Jika Situs bersifat non-publik, klien Anda harus mengautentikasi dengan menggunakan token AuthSub, OAuth, atau ClientLogin. Baca bagian Mengautentikasi ke layanan Sites.
Feed konten menampilkan konten terbaru Situs. Library ini dapat diakses dengan memanggil metode GetContentFeed()
lib, yang menggunakan parameter string uri opsional untuk meneruskan
kueri yang disesuaikan.
Berikut contoh pengambilan seluruh feed konten dan mencetak beberapa elemen yang menarik:
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
Tips: entry.Kind() dapat digunakan untuk menentukan jenis entri.
Objek feed yang dihasilkan adalah gdata.sites.data.ContentFeed yang berisi daftar
gdata.sites.data.ContentEntry. Setiap entri mewakili halaman/item yang berbeda dalam
Situs pengguna dan memiliki elemen khusus untuk jenis entrinya. Lihat contoh aplikasi untuk memahami
beberapa properti yang tersedia di setiap jenis entri.
Contoh kueri feed konten
Anda dapat menelusuri feed konten menggunakan beberapa parameter kueri Google Data API standar dan parameter khusus untuk Sites API klasik. Untuk mengetahui informasi lebih mendetail dan daftar lengkap parameter yang didukung, lihat Panduan Referensi.
Catatan: Contoh di bagian ini menggunakan metode helper gdata.sites.client.MakeContentFeedUri()
untuk menyusun URI dasar feed konten.
Mengambil jenis entri tertentu
Untuk mengambil jenis entri tertentu saja, gunakan parameter kind. Sebagai contoh, cuplikan ini hanya menampilkan entri attachment:
kind = 'webpage' print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Untuk menampilkan lebih dari satu jenis, pisahkan setiap kind dengan koma. Misalnya, cuplikan ini menampilkan entri filecabinet dan
listpage:
kind = ','.join(['filecabinet', 'listpage']) print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Mengambil halaman berdasarkan jalur
Jika Anda mengetahui jalur relatif halaman dalam Situs Google, Anda dapat menggunakan parameter path untuk mengambil halaman tertentu tersebut.
Contoh ini akan menampilkan halaman yang terletak di 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)
Mengambil semua entri pada halaman induk
Jika mengetahui ID entri konten halaman (misalnya, "1234567890" dalam contoh di bawah), Anda dapat menggunakan parameter parent untuk mengambil semua entri turunannya (jika ada):
parent = '1234567890' print 'Fetching all children of parent entry: ' + parent uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent) feed = client.GetContentFeed(uri=uri)
Untuk parameter tambahan, lihat Panduan Referensi.
Membuat Konten
Catatan: Sebelum membuat konten untuk suatu situs, pastikan Anda telah menetapkan situs Anda di klien.client.site = "siteName"
Konten baru (halaman web, halaman daftar, lemari file, halaman pengumuman, dll.) dapat dibuat menggunakan CreatePage().
Argumen pertama untuk metode ini harus berupa jenis halaman yang akan dibuat, diikuti oleh judul, dan konten HTML-nya.
Untuk mengetahui daftar jenis node yang didukung, lihat parameter kind di Panduan Referensi.
Membuat item / halaman baru
Contoh ini membuat webpage baru di bawah level teratas, menyertakan beberapa Xcode untuk isi halaman, dan menetapkan judul judul ke 'New WebPage Title':
entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href
Jika permintaan berhasil, entry akan berisi salinan entri yang dibuat di server, sebagai gdata.sites.gdata.ContentEntry.
Untuk membuat jenis entri yang lebih kompleks yang diisi saat pembuatan (misalnya, listpage dengan judul kolom), Anda harus membuat
gdata.sites.data.ContentEntry secara manual, mengisi properti yang diinginkan, dan memanggil client.Post().
Membuat item/halaman pada jalur URL kustom
Secara default, contoh sebelumnya akan dibuat di URL
http://sites.google.com/domainName/siteName/new-webpage-title dan
memiliki judul halaman 'Judul Halaman Web Baru'. Artinya, judul dinormalkan ke new-webpage-title untuk URL.
Untuk menyesuaikan jalur URL halaman, Anda dapat menetapkan properti page_name di entri konten. Helper CreatePage() menyediakannya sebagai argumen kata kunci opsional.
Contoh ini membuat halaman filecabinet baru dengan judul 'File Storage', tetapi membuat halaman di bawah URL http://sites.google.com/domainName/siteName/files (bukan http://sites.google.com/domainName/siteName/file-storage) dengan menentukan properti page_name.
entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href
Server menggunakan aturan prioritas berikut untuk memberi nama jalur URL halaman:
page_name, jika ada. Harus memenuhia-z, A-Z, 0-9, -, _.title, tidak boleh null jika nama halaman tidak ada. Normalisasi adalah memangkas + menciutkan spasi kosong menjadi '-' dan menghapus karakter yang tidak cocok dengana-z, A-Z, 0-9, -, _.
Membuat sub-halaman
Untuk membuat subhalaman (turunan) di halaman induk, gunakan argumen kata kunci parent dari CreatePage().
parent dapat berupa gdata.sites.gdata.ContentEntry atau string yang mewakili
ID mandiri lengkap entri konten.
Contoh ini membuat kueri feed konten untuk announcementpage dan membuat announcement baru di bawah feed pertama yang ditemukan:
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!'
Mengupload file
Sama seperti di Google Sites, API mendukung upload lampiran ke halaman lemari file atau halaman induk. Lampiran harus diupload
ke halaman induk. Oleh karena itu, Anda harus menetapkan link induk di ContentEntry yang Anda coba upload. Lihat Membuat subhalaman untuk informasi selengkapnya.
Metode UploadAttachment() library klien menyediakan antarmuka untuk mengupload lampiran.
Mengupload lampiran
Contoh ini mengupload file PDF ke filecabinet pertama yang ada di feed konten pengguna.
Lampiran dibuat dengan judul 'Buku Pegangan Karyawan Baru' dan deskripsi (opsional), 'paket 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
Jika upload berhasil, attachment akan berisi salinan lampiran yang dibuat di server.
Mengupload lampiran ke folder
Lemari file di folder dukungan Google Sites. UploadAttachment() menyediakan argumen kata kunci
tambahan, folder_name, yang dapat Anda gunakan untuk mengupload lampiran ke dalam folder filecabinet. Cukup tentukan nama folder tersebut:
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')
Perhatikan bahwa contoh ini meneruskan objek gdata.data.MediaSource ke UploadAttachment(), bukan
jalur file. Kode ini juga tidak meneruskan jenis konten. Sebagai gantinya, jenis konten ditetapkan pada objek MediaSource.
Lampiran web
Lampiran web adalah jenis lampiran khusus. Pada dasarnya, link ini adalah link ke file lain di web
yang dapat Anda tambahkan ke listingan filecabinet Anda. Fitur ini serupa dengan metode upload 'Add file by URL' di UI Google Sites.
Catatan: Lampiran web hanya dapat dibuat di filecabinet. Materi iklan tersebut tidak dapat diupload ke jenis halaman lain.
Contoh ini membuat lampiran web di filecabinet pertama yang ditemukan di feed konten pengguna.
Judul dan deskripsinya (opsional) masing-masing ditetapkan ke 'GoogleLogo' dan 'warna yang bagus'.
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!'
Panggilan tersebut akan membuat link yang mengarah ke gambar di 'http://www.google.com/images/logo.gif' di filecabinet.
Memperbarui Konten
Memperbarui metadata dan/atau konten html halaman
Metadata (judul, pageName, dll.) dan konten halaman dari jenis entri apa pun dapat diedit menggunakan metode Update() klien.
Berikut adalah contoh pembaruan listpage dengan perubahan berikut:
- Judul diubah menjadi 'Judul yang Diperbarui'
- Konten HTML halaman telah diperbarui menjadi 'Konten HTML yang diperbarui'
- Judul kolom pertama dalam daftar diubah menjadi "Pemilik"
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!'
Mengganti konten + metadata lampiran
Anda dapat mengganti konten file lampiran dengan membuat objek MediaSource baru
dengan konten file baru tersebut dan memanggil metode Update() klien. Metadata lampiran (seperti judul dan deskripsi) juga dapat diperbarui, atau hanya metadata.
Contoh ini menunjukkan cara mengupdate konten dan metadata file secara bersamaan:
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)
Menghapus Konten
Untuk menghapus halaman atau item dari Situs Google, ambil entri konten terlebih dahulu, lalu panggil metode Delete() klien.
client.Delete(content_entry)
Anda juga dapat meneruskan link edit entri konten ke metode Delete() dan/atau memaksa penghapusan:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(content_entry.GetEditLink().href, force=True)
Untuk informasi selengkapnya tentang ETag, lihat panduan referensi API Data Google.
Mendownload Lampiran
Setiap entri attachment berisi link src konten yang dapat digunakan untuk mendownload konten file.
Klien Sites berisi metode bantuan untuk mengakses dan mendownload file dari link ini: DownloadAttachment().
Class ini menerima gdata.sites.data.ContentEntry atau URI download untuk argumen pertamanya, dan jalur file untuk menyimpan lampiran sebagai yang kedua.
Contoh ini mengambil entri lampiran tertentu (dengan membuat kueri link self-nya) dan mendownload file ke jalur yang ditentukan:
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!'
Developer aplikasi bebas menentukan ekstensi file yang sesuai untuk jenis konten lampiran. Jenis konten
dapat ditemukan di entry.content.type.
Terkadang, Anda mungkin tidak dapat mengunduh file ke disk (mis. jika aplikasi Anda berjalan di Google App Engine).
Untuk situasi ini, gunakan _GetFileContent() untuk mengambil konten file dan menyimpannya dalam memori.
Contoh ini mengunduh lampiran ke memori.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
Feed ACL
Ringkasan Izin Berbagi (ACL)
Setiap entri ACL dalam feed ACL mewakili peran akses entitas tertentu, baik pengguna, grup pengguna, domain, atau akses default (yang merupakan situs publik). Entri hanya akan ditampilkan untuk entitas yang memiliki akses eksplisit - satu entri akan ditampilkan untuk setiap alamat email di panel "Orang dengan Akses" di layar berbagi UI Google Sites. Dengan demikian, admin domain tidak akan ditampilkan, meskipun mereka memiliki akses implisit ke situs.
Peran
Elemen peran mewakili tingkat akses yang dapat dimiliki suatu entitas. Ada empat kemungkinan nilai elemen gAcl:role:
- pembaca — pelihat (setara dengan akses hanya baca).
- writer — seorang kolaborator (setara dengan akses baca/tulis).
- pemilik — biasanya admin situs (setara dengan akses baca/tulis).
Cakupan
Elemen cakupan mewakili entitas yang memiliki tingkat akses ini. Ada empat kemungkinan jenis elemen gAcl:scope:
- pengguna — nilai alamat email, misalnya "pengguna@gmail.com".
- grup — alamat email Google Grup, mis. "grup@domain.com".
- domain — nama domain G Suite, misalnya "domain.com".
- default — Hanya ada satu kemungkinan cakupan jenis "default", yang tidak memiliki nilai (misalnya
<gAcl:scope type="default">). Cakupan khusus ini mengontrol akses yang dimiliki setiap pengguna secara default di situs publik.
Catatan: Domain tidak boleh memiliki nilai gAcl:role
yang ditetapkan ke akses "pemilik". Domain hanya dapat menjadi pembaca atau penulis.
Mengambil feed ACL
Feed ACL dapat digunakan untuk mengontrol izin berbagi situs dan dapat diambil menggunakan metode GetAclFeed().
Contoh berikut mengambil feed ACL untuk situs yang saat ini ditetapkan pada objek SitesClient, dan mencetak entri izin:
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)
Setelah kueri berhasil, feed akan menjadi objek gdata.sites.data.AclFeed yang berisi
listingan gdata.sites.data.AclEntry.
Jika Anda menangani entri di SiteFeed, setiap SiteEntry berisi link ke feed ACL-nya.
Misalnya, cuplikan ini mengambil situs pertama di feed Situs pengguna dan mengkueri feed ACL-nya:
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())
Berbagi situs
Catatan: ACL berbagi tertentu hanya dapat dilakukan jika domain dikonfigurasi untuk memberikan izin tersebut (misalnya, jika berbagi di luar domain untuk domain G Suite diaktifkan, dll.).
Untuk membagikan Situs Google menggunakan API, buat gdata.sites.gdata.AclEntry dengan nilai gdata.acl.data.AclScope dan gdata.acl.data.AclRole yang diinginkan. Lihat bagian Ringkasan feed ACL untuk mengetahui kemungkinan nilai AclScope dan AclRoles.
Contoh ini memberikan izin baca di Situs kepada pengguna 'pengguna@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)
Berbagi tingkat Grup dan Domain
Serupa dengan berbagi situs dengan satu pengguna, Anda dapat berbagi situs di seluruh domain grup Google atau G Suite. Nilai scope yang diperlukan tercantum di bawah.
Berbagi ke alamat email grup:
scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')
Berbagi ke seluruh domain:
scope = gdata.acl.data.AclScope(value='example.com', type='domain')
Berbagi di tingkat domain hanya didukung untuk domain G Suite, dan hanya untuk domain tempat situs dihosting. Misalnya, http://sites.google.com/a/domain1.com/siteA hanya dapat membagikan keseluruhan Situs dengan domain1.com, bukan domain2.com. Situs yang tidak dihosting di domain G Suite (misalnya, http://sites.google.com/site/siteB) tidak dapat mengundang domain.
Mengubah izin berbagi
Untuk izin berbagi yang ada di Situs, pertama-tama ambil AclEntry yang dimaksud, ubah izin sesuai keinginan, lalu panggil metode Update() klien untuk mengubah ACL di server.
Contoh ini mengubah acl_entry sebelumnya dari bagian Membagikan situs,
dengan memperbarui 'user@example.com' menjadi penulis (kolaborator):
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)
Untuk informasi selengkapnya tentang ETag, lihat panduan referensi API Data Google.
Menghapus izin berbagi
Untuk menghapus izin berbagi, ambil AclEntry terlebih dahulu, lalu panggil metode Delete() klien.
client.Delete(acl_entry)
Anda juga dapat meneruskan link edit entri acl ke metode Delete() dan/atau memaksa penghapusan:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(acl_entry.GetEditLink().href, force=True)
Untuk informasi selengkapnya tentang ETag, lihat panduan referensi API Data Google.
Topik Khusus
Mengambil feed atau entri lagi
Jika ingin mengambil feed atau entri yang telah diambil sebelumnya, Anda dapat meningkatkan efisiensi dengan memberi tahu server untuk mengirim daftar atau entri hanya jika daftar atau entri tersebut telah berubah sejak terakhir kali Anda mengambilnya.
Untuk melakukan pengambilan kondisional ini, teruskan nilai ETag ke GetEntry(). Misalnya, jika Anda sudah memiliki objek 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
Jika GetEntry() menampilkan pengecualian gdata.client.NotModified, ETag entri akan cocok dengan versi di server, yang berarti Anda memiliki salinan terbaru.
Namun, jika klien/pengguna lain telah melakukan perubahan, entri baru akan ditampilkan di entry dan tidak ada pengecualian yang akan ditampilkan.
Untuk informasi selengkapnya tentang ETag, lihat panduan referensi API Data Google.