Ważne: ten dokument został napisany przed 2012 rokiem. Opcje uwierzytelniania opisane w tym dokumencie (OAuth 1.0, AuthSub i ClientLogin) zostały oficjalnie wycofane 20 kwietnia 2012 r. Zachęcamy do przejścia na OAuth 2.0.
Interfejs API danych Witryn Google umożliwia aplikacjom klienckim uzyskiwanie dostępu do treści w Witrynach Google oraz publikowanie i modyfikowanie jej zawartości. Aplikacja kliencka może również prosić o listę ostatniej aktywności, pobrać historię zmian i pobrać załączniki.
Poza ogólnymi informacjami o możliwościach interfejsu Sites Data API w tym przewodniku znajdziesz przykłady interakcji z tym interfejsem API. za pomocą biblioteki klienta w języku Python. Aby uzyskać pomoc przy konfigurowaniu biblioteki klienta, zobacz Pierwsze kroki z biblioteką klienta w języku Python Google Data Jeśli interesuje Cię jeśli chcesz dowiedzieć się więcej o podstawowym protokole używanym przez bibliotekę klienta w języku Python do interakcji z klasycznym interfejsem Sites API, zapoznaj się z artykułem przewodnika po protokołach.
Odbiorcy
Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienckie obsługujące Witryny Google. za pomocą biblioteki klienta w języku Python Google.
Pierwsze kroki
Aby korzystać z biblioteki klienta w języku Python, musisz mieć język Python 2.2 lub nowszy oraz moduły wymienione na stronie wiki DependencyModules. Po pobraniu biblioteki klienta zapoznaj się z artykułem Pierwsze kroki z biblioteką Google Data Python, aby uzyskać pomoc dotyczącą instalowania i używania klienta.
Uruchamiam próbkę
Pełna próbka robocza znajduje się w podkatalogu samples/sites repozytorium Mercurial projektu.
(/samples/sites/sites_example.py).
Uruchom przykład w ten sposób:
python sites_example.py # or python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]
Jeśli wymagane flagi nie są dostępne, aplikacja poprosi o ich podanie. Przykład pozwala użytkownikowi wykonać wiele operacji, które zademonstrować, jak korzystać z klasycznej wersji Witryn. W związku z tym, aby wykonać określone operacje (np. zmodyfikować treści), musisz się uwierzytelnić. Program pojawi się też prośba o uwierzytelnienie przez AuthSub, OAuth lub ClientLogin.
Aby umieścić w swoim kodzie przykłady z tego przewodnika, potrzebujesz tych instrukcji import:
import atom.data import gdata.sites.client import gdata.sites.data
Musisz też skonfigurować obiekt SitesClient, który reprezentuje połączenie klienta z interfejsem API klasycznej wersji Witryn.
Przekaż nazwę aplikacji i nazwę witryny (z jej adresu URL):
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Aby korzystać z witryny hostowanej w domenie G Suite, ustaw domenę za pomocą parametru domain:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')
W powyższych fragmentach argument source jest opcjonalny, ale zalecany do celów rejestrowania. Powinna
użyj formatu: company-applicationname-version
Uwaga: w pozostałej części przewodnika przyjęto założenie, że obiekt SitesClient został utworzony w zmiennej client.
Uwierzytelnianie w klasycznym interfejsie Sites API
Z biblioteki klienta w języku Python można korzystać do pracy z publicznymi lub prywatnymi kanałami. Interfejs Sites Data API zapewnia dostęp do prywatnych i publicznych danych. kanałów w zależności od uprawnień witryny i operacji, którą chcesz wykonać. Możesz na przykład odczytać źródło treści witrynę publiczną, ale nie wolno jej aktualizować (co wymaga uwierzytelnionego klienta); Można to zrobić za pomocą uwierzytelnianie ClientLogin (nazwa użytkownika i hasło), AuthSub lub OAuth.
Więcej informacji o protokole AuthSub, OAuth i ClientLogin znajdziesz w artykule Omówienie uwierzytelniania interfejsów API danych Google.
AuthSub dla aplikacji internetowych
Uwierzytelnianie AuthSub dla aplikacji internetowych powinno być używane przez aplikacje klienckie, które muszą uwierzytelniać użytkowników na kontach Google lub G Suite. Operator nie potrzebuje dostępu do nazwy użytkownika ani hasła dla użytkownika Witryn Google – wystarczy Token AuthSub jest wymagany.
Wyświetl instrukcje włączania AuthSub w aplikacji internetowej
Poproś o token jednorazowego użytku
Gdy użytkownik po raz pierwszy odwiedza Twoją aplikację, musi się uwierzytelnić. Zazwyczaj deweloperzy drukują tekst i link kierujący użytkownika
stronie zatwierdzania AuthSub, aby uwierzytelnić użytkownika i poprosić o dostęp do jego dokumentów. Biblioteka klienta Google Data w Pythonie oferuje funkcję,
generate_auth_sub_url(), aby wygenerować ten adres URL. Poniższy kod konfiguruje link do strony 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()
Jeśli chcesz uwierzytelniać użytkowników w domenie hostowanej w G Suite, przekaż jej nazwę użytkownikowi 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)
Metoda generate_auth_sub_url() bierze pod uwagę kilka parametrów (odpowiadających parametrom zapytania używanym przez
AuthSubRequest):
- adres URL następny – adres URL, na który Google przekieruje
po zalogowaniu się na konto i udzieleniu przez użytkownika dostępu;
http://www.example.com/myapp.pyw przykładzie powyżej - zakres –
https://sites.google.com/feeds/ - secure (zabezpieczony) to wartość logiczna wskazująca, czy token będzie używany w trybie bezpiecznym i zarejestrowanym.
Truew przykładzie powyżej - session: druga wartość logiczna wskazująca, czy token jednorazowego użytku zostanie później zamieniony na token sesji;
Truew przykładzie powyżej
Przechodzenie na token sesji
Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.
Pobieranie informacji o tokenie sesji
Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.
Unieważnianie tokena sesji
Zobacz Używanie AuthSub z bibliotekami klienta interfejsu Google Data API.
Wskazówka: gdy aplikacja otrzyma token długotrwałych sesji,
zapisać go w bazie danych do wycofania w celu późniejszego użycia. Nie musisz przy każdym uruchomieniu aplikacji odsyłać użytkownika do AuthSub.
Użyj client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR), aby ustawić istniejący token dla klienta.
Protokół OAuth na potrzeby aplikacji internetowych lub zainstalowanych/mobilnych
Alternatywą dla protokołu AuthSub jest protokół OAuth. Jest on przeznaczony dla aplikacji internetowych. Protokół OAuth jest podobny do korzystania z trybu bezpiecznego i zarejestrowanego AuthSub. W tym fakcie, że wszystkie wnioski o przekazanie danych muszą być podpisane cyfrowo i musisz zarejestrować swoją domenę.
Wyświetl instrukcje włączania protokołu OAuth w zainstalowanej aplikacji
Pobieranie tokena żądania
Zobacz Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.
Autoryzacja tokena żądania
Zobacz Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.
Przejście na token dostępu
Zobacz Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.
Wskazówka: gdy aplikacja uzyska token dostępu OAuth,
zapisać go w bazie danych do wycofania w celu późniejszego użycia. Nie musisz przy każdym uruchomieniu aplikacji odsyłać użytkownika przez OAuth.
Użyj client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET), aby ustawić istniejący token dla klienta.
ClientLogin dla zainstalowanych/mobilnych aplikacji
Konta ClientLogin powinny używać zainstalowane i mobilne aplikacje, które muszą uwierzytelniać użytkowników na kontach Google. Przy pierwszym uruchomieniu aplikacja prosi użytkownika o podanie nazwy użytkownika i hasła. W przypadku kolejnych próśb pojawia się odwołanie do tokena uwierzytelniania.
Wyświetl instrukcje włączania ClientLogin do zainstalowanej aplikacji
Aby użyć parametru ClientLogin, wywołaj metodę
ClientLogin()
metody obiektu SitesClient, która jest dziedziczona z
GDClient. Podaj adres e-mail
hasło użytkownika, w imieniu którego klient przesyła żądania. Na przykład:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Wskazówka: gdy aplikacja po raz pierwszy uwierzytelni użytkownika, zapisz token uwierzytelniania w bazie danych w celu późniejszego użycia. Nie musisz przy każdym uruchomieniu aplikacji prosić użytkownika o podanie hasła. Więcej informacji znajdziesz w artykule na temat wycofywania tokena uwierzytelniania.
Więcej informacji o używaniu ClientLogin w aplikacjach w języku Python znajdziesz w artykule Używanie ClientLogin z bibliotekami klienta interfejsu API danych Google (w języku angielskim).
Kanał witryny
Kanał witryn może służyć do tworzenia listy witryn Google należących do użytkownika lub do wyświetlania, do których ma uprawnienia do wyświetlania. W ten sposób możesz też zmienić nazwę istniejącej witryny. Wreszcie w przypadku domen G Suite można go też użyć do tworzenia lub kopiowania całą witrynę.
Witryny z ofertami
Aby wyświetlić listę stron, do których użytkownik ma dostęp, użyj metody GetSiteFeed() klienta. Metoda przyjmuje opcjonalne wartości
uri, którego możesz użyć do określenia alternatywnego identyfikatora URI kanału witryny. Domyślnie GetSiteFeed()
używa nazwy witryny i domeny ustawionych w obiekcie klienta. W sekcji Pierwsze kroki znajdziesz informacje
Dowiedz się więcej o ustawianiu tych wartości w obiekcie klienta.
Oto przykład pobierania listy witryn uwierzytelnionego użytkownika:
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
Powyższy fragment zawiera tytuł i nazwę witryny, witrynę, z której została skopiowana, oraz identyfikator URI kanału listy ACL.
Tworzenie nowych witryn
Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.
Można udostępniać nowe witryny przez wywołanie metody CreateSite() biblioteki.
Podobnie jak pomocnik GetSiteFeed(), CreateSite() akceptuje również
opcjonalny argument uri, którego możesz użyć do określenia alternatywnego identyfikatora URI kanału witryny (w przypadku utworzenia
w witrynie w innej domenie niż ustawiona w obiekcie SitesClient).
Oto przykład tworzenia nowej witryny z motywem „Slate” i dostarczenie tytuł i (opcjonalnie) opis:
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
Powyższe żądanie spowoduje utworzenie nowej witryny w domenie G Suite example2.com.
Adres URL witryny będzie więc wyglądać tak: https://sites.google.com/a/example2.com/title-for-my-site.
Po utworzeniu witryny serwer w odpowiedzi przesyła gdata.sites.data.SiteEntry
zawiera elementy dodane przez serwer: link do witryny, link do kanału listy kontroli dostępu witryny (ACL),
nazwa witryny, tytuł, podsumowanie itd.
Kopiowanie witryny
Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.
Pliku CreateSite() można też użyć do kopiowania istniejącej witryny. W tym celu przekaż argument słowa kluczowego source_site.
Ten link będzie dostępny w każdej skopiowanej witrynie, który jest dostępny na stronie entry.FindSourceLink(). Oto przykład duplikowania witryny
utworzone w sekcji Tworzenie nowych witryn:
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
Ważne informacje:
- Kopiowane mogą być tylko witryny i szablony witryn należące do uwierzytelnionego użytkownika.
- Możesz też skopiować szablon witryny. Witryna jest szablonem, jeśli opcja „Opublikuj tę witrynę jako szablon” jest zaznaczona na stronie ustawień Witryn Google.
- Możesz skopiować witrynę z innej domeny, dopóki nie staniesz się jej właścicielem w witrynie źródłowej.
Aktualizowanie metadanych witryny
Aby zaktualizować tytuł lub podsumowanie witryny, potrzebujesz elementu SiteEntry zawierającego jej treść. Ten
W przykładzie użyto metody GetEntry(), aby najpierw pobrać element SiteEntry, a następnie zmienić jego tytuł, opis i tag kategorii:
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)
Pobieranie kanału aktywności
Uwaga: aby uzyskać dostęp do tego kanału, musisz być współpracownikiem lub właścicielem witryny. Twój klient musi uwierzytelniać się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.
Możesz pobrać ostatnią aktywność (zmiany) w witrynie, pobierając kanał aktywności.
Metoda GetActivityFeed() biblioteki lib zapewnia dostęp do tego pliku danych:
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)
Wywołanie GetActivityFeed() zwraca obiekt gdata.sites.data.ActivityFeed zawierający listę
gdata.sites.data.ActivityEntry Każdy wpis o aktywności zawiera informacje na temat:
zmianę wprowadzoną w Witrynie.
Pobieranie historii wersji
Uwaga: aby uzyskać dostęp do tego kanału, musisz być współpracownikiem lub właścicielem witryny. Twój klient musi uwierzytelniać się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.
Kanał wersji zawiera informacje o historii zmian każdego wpisu treści. GetRevisionFeed()
można użyć do pobrania wersji określonego wpisu treści. Metoda przyjmuje opcjonalny uri
, który akceptuje wartość gdata.sites.data.ContentEntry, pełny identyfikator URI wpisu treści lub identyfikator wpisu treści.
W tym przykładzie odpytujemy plik danych o treści i pobieramy plik danych o wersjach pierwszego wpisu:
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]
Wywołanie GetRevisionFeed() zwraca obiekt gdata.sites.data.RevisionFeed zawierający listę
gdata.sites.data.RevisionEntry Każdy wpis wersji zawiera informacje takie jak treść
numer wersji oraz datę utworzenia nowej wersji.
Źródło treści
Pobieram źródło treści
Uwaga: źródło treści może wymagać uwierzytelniania, ale nie musi. w zależności od uprawnień do udostępniania w witrynie. Jeśli witryna nie jest publiczna, klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.
Źródło treści zwraca najnowszą zawartość witryny. Można uzyskać do niego dostęp przez wywołanie biblioteki lib
metody GetContentFeed(), która przyjmuje opcjonalny parametr ciągu uri w celu przekazywania
dostosowane zapytanie.
Oto przykład pobierania całego źródła treści i wydrukowania kilku interesujących elementów:
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
Wskazówka: za pomocą entry.Kind() można określić typ wpisu.
Powstały obiekt feed to obiekt typu gdata.sites.data.ContentFeed zawierający listę
z gdata.sites.data.ContentEntry. Każdy wpis reprezentuje inną stronę/produkt w obrębie
witryny użytkownika i zawiera elementy charakterystyczne dla tego rodzaju wpisu. Więcej informacji znajdziesz w przykładowej aplikacji.
z niektórych właściwości dostępnych w poszczególnych rodzajach wpisów.
Przykłady zapytań dotyczących źródła treści
Źródło treści możesz przeszukiwać, korzystając ze standardowych parametrów zapytania w interfejsie Google Data API. i tych związanych z klasycznym interfejsem Sites API. Szczegółowe informacje i pełną listę obsługiwanych parametrów znajdziesz tutaj: Przewodnik informacyjny
Uwaga: w przykładach w tej sekcji używana jest metoda pomocnicza gdata.sites.client.MakeContentFeedUri().
.
Pobieranie określonych rodzajów wpisów
Aby pobrać tylko konkretny typ wpisu, użyj parametru kind. Na przykład ten fragment zwraca tylko tyle wpisów: attachment:
kind = 'webpage' print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Aby zwrócić więcej niż 1 typ, oddziel każdą kolumnę kind przecinkiem. Na przykład ten fragment zwraca filecabinet i
listpage wpisy:
kind = ','.join(['filecabinet', 'listpage']) print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Pobieranie strony według ścieżki
Jeśli znasz względną ścieżkę strony w Witrynach Google, możesz użyć parametru path, by ją pobrać.
Ten przykład zwróci stronę znajdującą się pod adresem
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)
Pobieranie wszystkich wpisów ze strony nadrzędnej
Jeśli znasz identyfikator wpisu treści strony (np. „1234567890” w przykładzie poniżej), możesz użyć parametru parent
pobierz wszystkie jej wpisy podrzędne (jeśli występują):
parent = '1234567890' print 'Fetching all children of parent entry: ' + parent uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent) feed = client.GetContentFeed(uri=uri)
Dodatkowe parametry znajdziesz w Przewodniku.
Tworzenie treści
Uwaga: zanim utworzysz treść witryny, skonfiguruj ją w kliencie.client.site = "siteName"
Nowe treści (strony internetowe, strony z listami, magazyny plików, strony z ogłoszeniami itp.) można tworzyć przy użyciu CreatePage().
Pierwszym argumentem tej metody powinien być rodzaj strony do utworzenia, a po nim tytuł i zawartość HTML.
Listę obsługiwanych typów węzłów znajdziesz w opisie parametru kind w Przewodniku.
Tworzenie nowych elementów / stron
W tym przykładzie jest tworzony nowy webpage poniżej najwyższego poziomu, zawiera fragment XHTML dla treści strony,
i ustawia tytuł nagłówka na „Tytuł nowej strony internetowej”:
entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href
Jeśli żądanie zostanie zrealizowane, entry będzie zawierać kopię wpisu utworzonego na serwerze w postaci gdata.sites.gdata.ContentEntry.
Aby utworzyć bardziej złożony rodzaj wpisu, który jest wypełniany podczas tworzenia (np. listpage z nagłówkami kolumn), musisz utworzyć
gdata.sites.data.ContentEntry ręcznie, wypełnić interesujące Cię właściwości i wywołać client.Post().
Tworzenie elementów/stron w niestandardowych ścieżkach URL
Domyślnie poprzedni przykład jest tworzony pod adresem URL.
http://sites.google.com/domainName/siteName/new-webpage-title i
mają nagłówek „Tytuł nowej strony internetowej”. Oznacza to, że tytuł jest znormalizowany do new-webpage-title.
Aby dostosować ścieżkę adresu URL strony, możesz ustawić właściwość page_name we wpisie treści. Asystent funkcji CreatePage()
podaje ją jako opcjonalny argument słowa kluczowego.
W tym przykładzie tworzymy nową stronę filecabinet z nagłówkiem „Przechowywanie plików”, ale tworzymy stronę
z adresem URL http://sites.google.com/domainName/siteName/files
(zamiast http://sites.google.com/domainName/siteName/file-storage)
określając właściwość page_name.
entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href
Serwer używa następujących reguł pierwszeństwa przy nazywaniu ścieżki adresu URL strony:
page_name(jeśli występuje). Wymagana jest wartość w polua-z, A-Z, 0-9, -, _.title: jeśli nie ma nazwy strony, nie może mieć wartości null. Normalizacja polega na przycięciu i zwijaniu odstępów do znaku „-” oraz usuń znaki, które nie pasują doa-z, A-Z, 0-9, -, _.
Tworzenie podstron
Aby utworzyć podstrony (podrzędne) na stronie nadrzędnej, użyj argumentu słowa kluczowego parent w elemencie CreatePage().
Obiekt parent może być ciągiem znaków gdata.sites.gdata.ContentEntry lub ciągiem reprezentującym
pełny własny identyfikator wpisu treści.
W tym przykładzie odpytujemy plik danych o elementy announcementpage i tworzymy nowy element announcement na podstawie pierwszego znalezionego źródła:
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!'
Przesyłanie plików
Podobnie jak w przypadku Witryn Google interfejs API obsługuje przesyłanie załączników do strony magazynu plików lub strony nadrzędnej. Należy przesłać załączniki
do strony nadrzędnej. Dlatego musisz ustawić link nadrzędny na koncie ContentEntry, który próbujesz przesłać. Więcej informacji znajdziesz w artykule Tworzenie podstron.
Metoda UploadAttachment() biblioteki klienta udostępnia interfejs do przesyłania załączników.
Przesyłam załączniki
W tym przykładzie prześlesz plik PDF do pierwszego elementu filecabinet znalezionego w źródle treści użytkownika.
Załącznik zostanie utworzony z tytułem „Podręcznik nowego pracownika”. i (opcjonalnie) opis „Pakiet 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
Jeśli przesyłanie się uda, plik attachment będzie zawierać kopię utworzonego załącznika na serwerze.
Przesyłanie załącznika do folderu
Magazyny plików w Witrynach Google obsługują foldery. Parametr UploadAttachment() zawiera dodatkowe słowo kluczowe
folder_name, którego można użyć do przesłania załącznika do folderu filecabinet. Po prostu podaj nazwę tego folderu:
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')
Zwróć uwagę, że ten przykład przekazuje obiekt gdata.data.MediaSource do UploadAttachment()
ścieżki pliku. Nie przekazuje też typu treści. Zamiast tego typ treści jest określany w obiekcie MediaSource.
Załączniki internetowe
Załączniki internetowe to szczególne rodzaje załączników. Zasadniczo są to linki do innych plików w internecie
które możesz dodać do stron w filecabinet. Ta funkcja działa analogicznie do opcji „Add file by URL” (Dodaj plik według adresu URL). przesyłania w interfejsie Witryn Google.
Uwaga: załączniki internetowe można tworzyć tylko w domenie filecabinet. Nie można ich przesyłać na strony innego typu.
W tym przykładzie tworzony jest załącznik internetowy pod pierwszym elementem filecabinet znalezionym w źródle treści użytkownika.
Jej tytuł i (opcjonalny) opis mają wartość „GoogleLogo” i „ładne kolory”.
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!'
Wywołanie powoduje utworzenie linku wskazującego obraz pod adresem „http://www.google.com/images/logo.gif”. w filecabinet.
Aktualizowanie treści
Aktualizowanie metadanych strony i/lub treści HTML
Metadane (tytuł, nazwa strony itp.) i treść strony dowolnego rodzaju mogą być edytowane przez
za pomocą metody Update() klienta.
Poniżej znajdziesz przykład aktualizacji elementu listpage z tymi zmianami:
- Zmieniono tytuł na „Zaktualizowany tytuł”.
- Zawartość HTML strony zostanie zmieniona na „Zaktualizowana treść HTML”
- Nagłówek pierwszej kolumny listy został zmieniony na „Właściciel”.
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!'
Zastępowanie zawartości i metadanych załącznika
Możesz zastąpić zawartość pliku załącznika, tworząc nowy obiekt MediaSource
z nową zawartością pliku i wywołaniem metody Update() klienta. Atrybut
Możesz aktualizować tylko metadane (np. tytuł i opis).
Ten przykład pokazuje jednoczesne aktualizowanie treści i metadanych pliku:
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)
Usuwam treść
Aby usunąć stronę lub element z witryny Google, najpierw pobierz wpis treści, a następnie wywołaj metodę Delete() klienta.
client.Delete(content_entry)
Możesz też przekazać metodę Delete() link edit do wpisu treści lub wymusić usunięcie:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(content_entry.GetEditLink().href, force=True)
Więcej informacji o tagach ETag znajdziesz w przewodniku po interfejsach API danych Google.
Pobieranie załączników
Każdy wpis attachment zawiera link do treści src, którego można użyć do pobrania zawartości pliku.
Klient Witryn zawiera metodę pomocniczą umożliwiającą dostęp do pliku i pobieranie go z tego linku: DownloadAttachment().
Akceptuje identyfikator URI gdata.sites.data.ContentEntry lub pobrany jako pierwszy argument oraz ścieżkę pliku do zapisania załącznika
jako drugą.
Ten przykład pobiera konkretny wpis załącznika (wykonując zapytanie o link self) i pobiera plik pod określoną ścieżkę:
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!'
To programista aplikacji odpowiada za określenie rozszerzenia pliku pasującego do typu zawartości załącznika. Typ treści
znaleźć w entry.content.type.
W niektórych przypadkach nie można pobrać pliku na dysk (np. jeśli aplikacja działa w Google App Engine).
W takich sytuacjach użyj polecenia _GetFileContent(), aby pobrać treść pliku i zapisać ją w pamięci.
Ten przykład pobiera załącznik do pamięci.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
Kanał ACL
Omówienie uprawnień do udostępniania (listy kontroli dostępu)
Każdy wpis na liście kontroli dostępu (ACL) w kanale ACL reprezentuje rolę dostępu określonego podmiotu: użytkownika, grupy użytkowników, domeny lub domyślny dostęp (witryna publiczna). Wpisy będą wyświetlane tylko dla jednostek z jawnym dostępem – wyświetli się 1 wpis dla każdego adresu e-mail w polu „Osoby z dostępem” na ekranie udostępniania w interfejsie Witryn Google. Administratorzy domeny nie będą wyświetlani, nawet jeśli mają bezpośredni dostęp do witryny.
Role
Element roli reprezentuje poziom dostępu, jaki może mieć encja. Element gAcl:role może mieć 4 wartości:
- reader – przeglądający (odpowiednik dostępu tylko do odczytu).
- writer – współpracownik (odpowiednik uprawnień do odczytu i zapisu).
- owner – zwykle jest administratorem witryny (odpowiednik uprawnień do odczytu i zapisu).
Zakresy
Element zakresu reprezentuje jednostkę, która ma dany poziom dostępu. Element gAcl:scope może zawierać 4 rodzaje:
- user – wartość adresu e-mail, np. „użytkownik@gmail.com”.
- grupa – adres e-mail grupy dyskusyjnej Google, np. „grupa@domena.com”.
- domena – nazwa domeny G Suite, np. „domena.com”.
- default – jest tylko jeden możliwy zakres typu „default”, który nie zawiera wartości;
(np.
<gAcl:scope type="default">). Ten konkretny zakres określa domyślnie dostęp każdego użytkownika na stronie publicznej.
Uwaga: domeny nie mogą mieć wartości gAcl:role.
z ustawieniem „owner” dostęp do treści, mogą być tylko czytelnikami lub autorami.
Pobieranie pliku danych ACL
Pliku danych ACL można używać do kontrolowania uprawnień do udostępniania witryny i można go pobrać za pomocą metody GetAclFeed().
Poniższy przykład pokazuje pobieranie pliku danych ACL dla witryny ustawionej obecnie w obiekcie SitesClient.
i wydrukuje wpisy uprawnień:
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)
Po pomyślnym zapytaniu feed będzie obiektem gdata.sites.data.AclFeed zawierającym
informacje o produkcie gdata.sites.data.AclEntry.
Jeśli pracujesz z wpisami w kanale SiteFeed, każdy element SiteEntry zawiera link do swojego kanału ACL.
Na przykład ten fragment kodu pobiera pierwszą witrynę z kanału witryny użytkownika i wysyła zapytanie do tego pliku danych ACL:
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())
Udostępnianie witryny
Uwaga: udostępnianie określonych list kontroli dostępu (ACL) jest możliwe tylko wtedy, gdy domena jest skonfigurowana. aby zezwolić na takie uprawnienia (np. jeśli w przypadku domen G Suite udostępnianie poza domenę jest włączone).
Aby udostępnić stronę w Witrynach Google przy użyciu interfejsu API, utwórz gdata.sites.gdata.AclEntry z odpowiednim
gdata.acl.data.AclScope i gdata.acl.data.AclRole wartości. Zobacz
Sekcja Przegląd pliku danych ACL dla możliwych AclScope
i AclRoles.
W tym przykładzie przyznano uprawnienia do odczytu w witrynie użytkownikowi „użytkownik@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)
Udostępnianie na poziomie grupy i domeny
Podobnie jak w przypadku udostępniania witryny jednemu użytkownikowi, możesz udostępnić ją całej
Domena grupy dyskusyjnej Google lub domena G Suite. Niezbędne wartości scope podano poniżej.
Udostępnianie adresowi e-mail grupy:
scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')
Udostępnianie w całej domenie:
scope = gdata.acl.data.AclScope(value='example.com', type='domain')
Udostępnianie na poziomie domeny jest obsługiwane tylko w przypadku domen G Suite i tylko w przypadku domeny, w której hostowana jest witryna. Na przykład witryna http://sites.google.com/a/domena1.com/witrynaA może udostępnić całą witrynę tylko domenie domena1.com, a nie domena2.com. Witryny, które nie są hostowane w domenie G Suite (np. http://sites.google.com/site/siteB) nie mogą zapraszać domen.
Zmiana uprawnień do udostępniania
Aby uzyskać istniejące uprawnienia do udostępniania w witrynie, najpierw pobierz obiekt AclEntry, którego dotyczy problem, a następnie zmodyfikuj uprawnienia.
zgodnie z potrzebami, a następnie wywołaj metodę Update() klienta, aby zmodyfikować listę kontroli dostępu (ACL) na serwerze.
Ten przykład zmienia poprzedni acl_entry z sekcji Udostępnianie witryny,
aktualizując konto „użytkownik@example.com” pisarzem (współpracownikiem):
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)
Więcej informacji o tagach ETag znajdziesz w przewodniku po interfejsach API danych Google.
Usuwanie uprawnień do udostępniania
Aby usunąć uprawnienia do udostępniania, najpierw pobierz obiekt AclEntry, a następnie wywołaj metodę Delete() klienta.
client.Delete(acl_entry)
Możesz też przekazać metodę Delete() linku edit do wpisu listy kontroli dostępu i/lub wymusić usunięcie:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(acl_entry.GetEditLink().href, force=True)
Więcej informacji o tagach ETag znajdziesz w przewodniku po interfejsach API danych Google.
Tematy specjalne
Ponowne pobieranie kanału lub wpisu
Jeśli chcesz pobrać pobrany wcześniej kanał lub wpis, możesz poprawić wydajność, mówiąc z serwera, aby wysyłał listę lub wpis tylko wtedy, gdy zmieniły się one od ostatniego pobrania.
Aby wykonać tego rodzaju pobieranie warunkowe, przekaż wartość ETag do funkcji GetEntry(). Jeśli na przykład masz już obiekt 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
Jeśli GetEntry() zgłosi wyjątek gdata.client.NotModified, wpisowi
ETag dopasowuje się do wersji na serwerze, co oznacza, że masz najbardziej aktualną kopię.
Jeśli jednak inny klient/użytkownik wprowadzi zmiany, nowy wpis zostanie zwrócony w polu entry.
i nie zostanie zgłoszony żaden wyjątek.
Więcej informacji o tagach ETag znajdziesz w przewodniku po interfejsach API danych Google.