Przewodnik Pythona

Ważne: ten dokument został napisany przed 2012 r. Opcje uwierzytelniania opisane w tym dokumencie (OAuth 1.0, AuthSub i ClientLogin) zostały oficjalnie wycofane 20 kwietnia 2012 roku i nie są już dostępne. Zachęcamy do jak najszybszego przejścia na OAuth 2.0.

Interfejs Google Sites Data API umożliwia aplikacjom klienckim uzyskiwanie dostępu do treści w Witrynie Google, ich publikowanie i modyfikowanie. Aplikacja klienta może też poprosić o listę ostatniej aktywności, pobrać historię zmian i pobrać załączniki.

Oprócz ogólnych informacji o możliwościach interfejsu Sites Data API ten przewodnik zawiera przykłady interakcji z interfejsem API przy użyciu biblioteki klienta Pythona. Informacje o konfigurowaniu biblioteki klienta znajdziesz w artykule Pierwsze kroki z biblioteką klienta w języku Python w Google Data. Jeśli chcesz dowiedzieć się więcej o podstawowym protokole używanym przez bibliotekę klienta Pythona do interakcji z klasycznym interfejsem API witryn, zapoznaj się z przewodnikiem po protokole.

Odbiorcy

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienckie, które będą wchodzić w interakcje z Google Sites za pomocą biblioteki klienta Google Data w Pythonie.

Pierwsze kroki

Aby korzystać z biblioteki klienta Pythona, 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 dla Pythona, aby dowiedzieć się, jak zainstalować klienta i z niego korzystać.

Uruchamiam próbkę

Pełna wersja przykładowego kodu znajduje się w podkatalogu samples/sites w repozytorium Mercurial projektu (/samples/sites/sites_example.py).

Uruchom ten 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 nie podasz wymaganych flag, aplikacja poprosi Cię o wpisanie tych wartości. Przykład ten pozwala użytkownikowi wykonać szereg operacji, które pokazują, jak korzystać z interfejsu API klasycznej wersji Witryn. W związku z tym, aby wykonać określone operacje (np. zmodyfikować treści), musisz się uwierzytelnić. Program poprosi Cię też o uwierzytelnienie się za pomocą 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 klasycznym interfejsem API witryn. Przekaż nazwę aplikacji i nazwę witryny (z jej adresu URL):

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')

Aby pracować z witryną hostowaną 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 kodu argument source jest opcjonalny, ale zalecany do celów rejestrowania. Powinien mieć format: company-applicationname-version

Uwaga: w dalszej części tego przewodnika przyjęliśmy założenie, że w zmiennej client został utworzony obiekt SitesClient.

Uwierzytelnianie w interfejsie API klasycznych Witryn

Biblioteki klienta dla języka Python można używać do pracy z publicznymi i prywatnymi plikami danych. Interfejs Sites Data API zapewnia dostęp do prywatnych i publicznych kanałów danych w zależności od uprawnień witryny i wykonywanej operacji. Można na przykład odczytywać kanał treści witryny publicznej, ale nie można jej aktualizować, co wymaga uwierzytelnionego klienta. Można to zrobić za pomocą uwierzytelniania ClientLogin (logowanie klienta) z hasłem i nazwą użytkownika, AuthSub lub OAuth.

Więcej informacji o protokole AuthSub, OAuth i ClientLogin znajdziesz w artykule Omówienie uwierzytelniania interfejsów API danych Google.

AuthSub w przypadku aplikacji internetowych

Uwierzytelnianie AuthSub w aplikacjach internetowych powinno być używane przez aplikacje klienckie, które muszą uwierzytelniać użytkowników na kontach Google lub G Suite. Operator nie musi mieć dostępu do nazwy użytkownika i hasła użytkownika Google Sites – wymagany jest tylko token AuthSub.

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()

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)

OAuth w przypadku aplikacji internetowych lub zainstalowanych/mobilnych

OAuth może być używane jako alternatywa dla AuthSub i jest przeznaczone do aplikacji internetowych. OAuth jest podobne do korzystania z trybu bezpiecznego i zarejestrowanego w AuthSub, ponieważ wszystkie żądania danych muszą być podpisane cyfrowo, a musisz zarejestrować swoją domenę.

ClientLogin w przypadku zainstalowanych aplikacji lub aplikacji mobilnych

Interfejsu ClientLogin należy używać w przypadku zainstalowanych i mobilnych aplikacji, 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 kolejnych żądaniach przywoływany jest token uwierzytelniania.

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1')
client.ClientLogin('user@gmail.com', 'pa$$word', client.source);

Powrót do góry

Kanał witryny

Plik danych o witrynach może zawierać listę witryn Google Sites, których użytkownik jest właścicielem lub do których ma uprawnienia do wyświetlania. Możesz też użyć go do zmiany nazwy istniejącej witryny. W przypadku domen G Suite możesz też użyć tej funkcji do utworzenia lub skopiowania całej witryny.

Strony z ofertami

Aby wyświetlić listę witryn, do których użytkownik ma dostęp, użyj metody GetSiteFeed() klienta. Ta metoda korzysta z opcjonalnego argumentu uri, którego możesz użyć do podania alternatywnego identyfikatora URI kanału witryny. Domyślnie GetSiteFeed() używa nazwy witryny i domeny ustawionych w obiekcie klienta. Więcej informacji o ustawianiu tych wartości w obiekcie klienta znajdziesz w sekcji Wprowadzenie.

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 kodu wypisuje tytuł witryny, nazwę witryny, z której została skopiowana, oraz identyfikator URI kanału ACL.

Tworzenie nowych witryn

Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.

Nowe witryny można tworzyć, wywołując metodę CreateSite() biblioteki. Podobnie jak w przypadku pomocnika GetSiteFeed(), CreateSite() akceptuje również opcjonalny argument uri, którego możesz użyć, aby podać alternatywny identyfikator URI kanału witryny (w przypadku utworzenia witryny w innej domenie niż ustawiona w obiekcie SitesClient).

Oto przykład tworzenia nowej witryny z tematem „slate” oraz podawania tytułu i (opcjonalnie) opisu:

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 mieć postać https://sites.google.com/a/example2.com/title-for-my-site.

Jeśli witryna zostanie utworzona, serwer w odpowiedzi prześle obiekt gdata.sites.data.SiteEntry z elementami dodanymi przez serwer: linkiem do witryny, linkiem do pliku danych z listą kontroli dostępu witryny, nazwą witryny, tytułem, podsumowaniem itd.

Kopiowanie witryny

Uwaga: ta funkcja jest dostępna tylko w domenach G Suite.

CreateSite() można też użyć do skopiowania istniejącej witryny. W tym celu przekaż argument słowa kluczowego source_site. Każda skopiowana witryna będzie miała ten link, który jest dostępny w sekcji entry.FindSourceLink(). Oto przykład powielania witryny utworzonej 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:

• Można kopiować tylko te witryny i ich szablony, które należą do uwierzytelnionego użytkownika.
• Szablon witryny też można skopiować. Witryna jest szablonem, jeśli na stronie ustawień Witryn Google jest zaznaczone ustawienie „Opublikuj tę witrynę jako szablon”.
• 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, musisz mieć SiteEntry z odpowiednią witryną. W tym przykładzie użyliśmy metody GetEntry(), aby najpierw pobrać 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)

Powrót do góry

Pobieranie karty Aktywność

Uwaga: aby mieć dostęp do tego pliku danych, musisz być współpracownikiem lub właścicielem witryny. Klient musi się uwierzytelnić za pomocą tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.

Możesz pobrać ostatnią aktywność (zmiany) na stronie, pobierając kanał aktywności. Metoda GetActivityFeed() biblioteki 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 funkcji GetActivityFeed() zwraca obiekt gdata.sites.data.ActivityFeed zawierający listę gdata.sites.data.ActivityEntry. Każdy wpis o aktywności zawiera informacje o zmianie wprowadzonej w Witrynie.

Powrót do góry

Pobieranie historii zmian

Uwaga: aby mieć dostęp do tego pliku danych, musisz być współpracownikiem lub właścicielem witryny. Klient musi się uwierzytelnić za pomocą tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.

Plik danych z rewizjami zawiera informacje o historii rewizji każdego wpisu z treściami. Metody GetRevisionFeed() można używać do pobierania wersji określonego wpisu treści. Przyjmuje ona opcjonalny parametr uri, który akceptuje identyfikator gdata.sites.data.ContentEntry, pełny identyfikator URI wpisu treści lub identyfikator wpisu treści.

W tym przykładzie wysyłamy zapytanie do kanału treści i pobieramy plik danych z poprawkami dotyczący pierwszego wpisu treści:

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 funkcji GetRevisionFeed() zwraca obiekt gdata.sites.data.RevisionFeed zawierający listę gdata.sites.data.RevisionEntry. Każdy wpis dotyczący poprawki zawiera informacje takie jak treść w danej wersji, numer wersji i datę utworzenia nowej wersji.

Powrót do góry

Źródło treści

Pobieranie kanału treści

Uwaga: kanał danych o treściach może wymagać uwierzytelnienia lub nie, w zależności od uprawnień do udostępniania na stronie. Jeśli witryna nie jest publiczna, klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zapoznaj się z sekcją Uwierzytelnianie w usłudze Witryny.

Źródło treści zwraca najnowszą zawartość witryny. Można uzyskać do niego dostęp, wywołując metodę GetContentFeed() biblioteki lib, która wykorzystuje opcjonalny parametr uri ciągu znaków, by przekazać niestandardowe zapytanie.

Oto przykład pobierania całego pliku danych o treściach i wybierania z niego 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 gdata.sites.data.ContentFeed zawierający listę obiektów gdata.sites.data.ContentEntry. Każdy wpis reprezentuje inną stronę lub inny element w witrynie użytkownika i zawiera elementy specyficzne dla danego typu wpisu. Aby lepiej poznać niektóre właściwości dostępne w każdym typie wpisu, zapoznaj się z przykładową aplikacją.

Powrót do góry

Przykłady zapytań dotyczących źródła treści

W pliku danych o treściach możesz wyszukiwać informacje, korzystając z niektórych standardowych parametrów zapytania interfejsu Google Data API oraz parametrów specyficznych dla klasycznego interfejsu Sites API. Więcej szczegółowych informacji oraz pełną listę obsługiwanych parametrów znajdziesz w przewodniku po dokumentach referencyjnych.

Uwaga: przykłady w tej sekcji korzystają z metody pomocniczej gdata.sites.client.MakeContentFeedUri() do tworzenia podstawowego identyfikatora URI kanału treści.

Pobieranie określonych rodzajów wpisów

Aby pobrać tylko określony typ wpisu, użyj parametru kind. Na przykład ten fragment kodu zwraca tylko rekordy 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żdy kind przecinkiem. Na przykład ten fragment kodu zwraca wpisy filecabinet i listpage:

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ć. W tym przykładzie zwrócona zostanie strona o adresie 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 na stronie nadrzędnej

Jeśli znasz identyfikator wpisu treści strony (np. „1234567890” w poniższym przykładzie), możesz użyć parametru parent, by pobrać wszystkie 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 po dokumentach.

Powrót do góry

Tworzenie treści

Uwaga: zanim utworzysz treść witryny, skonfiguruj ją w kliencie.
client.site = "siteName"

Nowe treści (strony internetowe, strony list, teczki, strony z powiadomieniami itp.) można tworzyć za pomocą 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 lub stron

W tym przykładzie tworzymy nowy obiekt webpage poniżej najwyższego poziomu, zawiera on kod XHTML dla treści strony i nadaje tytuł nagłówka „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 spełnione, element entry będzie zawierać kopię utworzonego na serwerze elementu 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 ręcznie utworzyć gdata.sites.data.ContentEntry, podać odpowiednie właściwości i wywołać client.Post().

Tworzenie elementów/stron w niestandardowych ścieżkach URL

W przypadku poprzedniego przykładu strona zostanie utworzona pod adresem URL http://sites.google.com/domainName/siteName/new-webpage-title i będzie mieć nagłówek „Nowy tytuł strony internetowej”. Oznacza to, że tytuł jest znormalizowany do new-webpage-title. Aby dostosować ścieżkę URL strony, możesz ustawić w danych treści właściwości page_name. Pomocnik CreatePage() udostępnia to jako opcjonalny argument słowa kluczowego.

W tym przykładzie tworzymy nową stronę filecabinet z nagłówkiem „Pamięć plików”, ale tworzymy ją pod adresem URL http://sites.google.com/domainName/siteName/files (zamiast http://sites.google.com/domainName/siteName/file-storage), podają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

Aby nazwać ścieżkę adresu URL strony, serwer stosuje te reguły pierwszeństwa:

1. page_name (jeśli występuje). Musi spełniać warunek a-z, A-Z, 0-9, -, _.
2. title: nie może być równe null, jeśli nie ma nazwy strony. Normalizacja polega na przycięciu i zwijaniu spacji do znaku „-” oraz usunięciu znaków, które nie pasują do a-z, A-Z, 0-9, -, _.

Tworzenie podstron

Aby utworzyć podstrony (podrzędne) pod stroną nadrzędną, użyj argumentu CreatePage() parent. Wartość parent może być wartością gdata.sites.gdata.ContentEntry lub ciągiem tekstowym reprezentującym pełny identyfikator treści.

W tym przykładzie zapytanie dotyczące pliku danych treści dotyczy announcementpage i tworzy nowy announcement w ramach pierwszego znalezionego:

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 Google Sites, interfejs API obsługuje przesyłanie załączników na stronę magazynu plików lub stronę nadrzędną. Załączniki należy przesłać na stronę nadrzędną. Dlatego musisz ustawić link nadrzędny w ContentEntry, który próbujesz przesłać. Więcej informacji znajdziesz w artykule Tworzenie stron podrzędnych.

Metoda UploadAttachment() biblioteki klienta udostępnia interfejs do przesyłania załączników.

Przesyłam załączniki

W tym przykładzie plik PDF jest przesyłany do pierwszego filecabinet znalezionego w strumieniach treści użytkownika. Załącznik jest tworzony z tytułem „Nowy podręcznik pracownika” i (opcjonalnie) opisem „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ę powiedzie, attachment będzie zawierać kopię utworzonego załącznika na serwerze.

Przesyłanie załącznika do folderu

Szafki w Witrynach Google obsługują foldery. Pole UploadAttachment() zawiera dodatkowy argument słowa kluczowego (folder_name), którego możesz użyć do przesłania załącznika do folderu filecabinet. Wystarczy, że podasz 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 do UploadAttachment() obiekt gdata.data.MediaSource zamiast ś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 specjalne rodzaje załączników. Są to linki do innych plików w internecie, które możesz dodać do swoich informacji filecabinet. Ta funkcja jest analogiczna do metody przesyłania „Dodaj plik za pomocą adresu URL” w interfejsie Witryn Google.

Uwaga: załączniki internetowe można tworzyć tylko w ramach filecabinet. Nie można ich przesyłać na inne typy stron.

W tym przykładzie tworzymy załącznik internetowy w ramach pierwszego filecabinet znalezionego w strumieniach treści użytkownika. Jego tytuł i (opcjonalnie) opis mają odpowiednio wartości „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 komponencie filecabinet.

Powrót do góry

Aktualizowanie treści

Aktualizowanie metadanych lub zawartości HTML strony

Metadane (tytuł, pageName itp.) i zawartość strony dowolnego rodzaju można edytować przy użyciu metody Update() klienta.

Poniżej przedstawiamy przykład aktualizacji obiektu listpage z tymi zmianami:

• Tytuł zostaje zmieniony na „Zaktualizowany tytuł”.
• treść HTML strony jest aktualizowana na „Zaktualizowana treść HTML”;
• Nazwa pierwszej kolumny listy zmienia się 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 treści i metadanych załącznika

Treść pliku załącznika możesz zastąpić, tworząc nowy obiekt MediaSource z nowym plikiem i wywołując metodę Update() klienta. Można też zaktualizować metadane załącznika (np. tytuł i opis) lub tylko metadane. 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)

Powrót do góry

Usuwanie treści

Aby usunąć stronę lub element z Google Sites, najpierw pobierz wpis treści, a następnie wywołaj metodę Delete() klienta.

client.Delete(content_entry)

Możesz też przekazać metodzie Delete() link edit z rekordu 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.

Powrót do góry

Pobieranie załączników

Każdy wpis attachment zawiera link src do treści, za pomocą którego można pobrać zawartość pliku. Klient Witryn zawiera metodę pomocniczą umożliwiającą dostęp do pliku i pobieranie go z tego linku: DownloadAttachment(). Akceptuje on identyfikator URI gdata.sites.data.ContentEntry lub pobrany jako pierwszy argument oraz ścieżkę pliku do zapisania załącznika jako drugiego.

W tym przykładzie pobieramy konkretny wpis załącznika (poprzez wysłanie zapytania o jego link self) i pobieramy plik do określonej ścieżki:

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 deweloper aplikacji musi określić rozszerzenie pliku, które ma sens w przypadku typu załącznika. Typ treści można 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ć zawartość pliku i zapisać ją w pamięci.

Przykładowy plik do pobrania to 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

Powrót do góry

Plik danych ACL

Omówienie uprawnień do udostępniania (listy kontroli dostępu)

Każdy wpis ACL w pliku danych ACL reprezentuje rolę dostępu określonego elementu, np. użytkownika, grupy użytkowników, domeny lub domyślnego dostępu (czyli witryny publicznej). Wpisy będą wyświetlane tylko w przypadku podmiotów z wyraźnym dostępem. Na panelu „Osoby z dostępem” w ekranie udostępniania w interfejsie Google Sites będzie widoczny po jednym wpisie dla każdego adresu e-mail. W rezultacie administratorzy domen nie będą widoczni, mimo że mają domyślny dostęp do witryny.

Role

Element role reprezentuje poziom dostępu, jaki może mieć dana encja. Element gAcl:role może mieć 4 możliwe wartości:

• Odczytujący – wyświetlający (odpowiednik dostępu tylko do odczytu).
• writer (pisarz) – współpracownik (odpowiednik uprawnień do odczytu i zapisu).
• owner (właściciel) – zwykle administrator witryny (odpowiada to uprawnieniom do odczytu i zapisu).

Zakresy

Element zakresu reprezentuje element, który ma ten poziom dostępu. Element gAcl:scope może mieć 4 typy:

• 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”.
• domyślny – istnieje tylko jeden możliwy zakres typu „domyślny”, który nie ma wartości (np. <gAcl:scope type="default">). Ten konkretny zakres kontroluje dostęp, który każdy użytkownik ma domyślnie w witrynie publicznej.

Uwaga: wartości gAcl:role w domenie nie mogą mieć ustawienia „Właściciel”. Domeny mogą mieć tylko dostęp do odczytu lub zapisu.

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 pobiera plik danych ACL dla witryny, która jest obecnie ustawiona 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 przetworzeniu zapytania feed będzie obiektem gdata.sites.data.AclFeed zawierającym listę gdata.sites.data.AclEntry.

Jeśli pracujesz z rekordami w pliku SiteFeed, każdy element SiteEntry zawiera link do pliku danych ACL. Na przykład ten fragment kodu pobiera pierwszą witrynę w pliku danych o witrynach użytkownika i wysyła zapytanie do 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: niektóre uprawnienia dostępu do plików mogą być dostępne tylko wtedy, gdy domena jest skonfigurowana w taki sposób, aby zezwalać na takie uprawnienia (np. jeśli udostępnianie poza domeną w przypadku domen G Suite jest włączone).

Aby udostępnić witrynę Google za pomocą interfejsu API, utwórz element gdata.sites.gdata.AclEntry z odpowiednimi wartościami gdata.acl.data.AclScope i gdata.acl.data.AclRole. Możliwe wartości AclScope i AclRoles znajdziesz w sekcji Przegląd pliku danych ACL.

W tym przykładzie użytkownik „użytkownik@example.com” otrzymuje uprawnienia do odczytu w witrynie:

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 pojedynczemu użytkownikowi, możesz udostępnić witrynę grupie dyskusyjnej Google lub domenie G Suite. Wymagane wartości scope znajdziesz poniżej.

Udostępnianie przy użyciu adresu e-mail grupy:

scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')

Udostępnianie 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/domain1.com/siteA może udostępniać całą witrynę tylko użytkownikom z domeny domain1.com, a nie z domeny domain2.com. Witryny, które nie są hostowane w domenie G Suite (np. http://sites.google.com/site/siteB), nie mogą zapraszać domen.

Modyfikowanie uprawnień do udostępniania

Aby uzyskać istniejące uprawnienia do udostępniania w witrynie, najpierw pobierz AclEntry, którego dotyczy problem, zmień uprawnienia zgodnie z potrzebami, a następnie wywołaj metodę Update() klienta, aby zmodyfikować listę kontroli dostępu (ACL) na serwerze.

W tym przykładzie zmieniamy poprzednią wartość acl_entry w sekcji Udostępnianie witryny, aby użytkownik „użytkownik@example.com” stał się autorem (współautorem):

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 eTag znajdziesz w przewodniku po interfejsach Google Data API.

Powrót do góry

Tematy specjalne

Ponowne pobieranie pliku danych lub wpisu

Jeśli chcesz pobrać wcześniej pobrany kanał lub wpis, możesz zwiększyć wydajność, prosząc serwer o wysłanie listy lub wpisu tylko wtedy, gdy zmieniły się one od czasu ostatniego pobrania.

Aby wykonać takie wyszukiwanie warunkowe, prześlij do parametru GetEntry() wartość ETag. 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, wartość ETag wpisu będzie zgodna z wersją na serwerze, co oznacza, że masz najbardziej aktualną kopię. Jeśli jednak inny klient lub użytkownik wprowadził zmiany, nowy wpis zostanie zwrócony w elementach entry, a nie zostanie rzucony żaden wyjątek.

Więcej informacji o eTag znajdziesz w przewodniku po interfejsach Google Data API.

Powrót do góry