Przewodnik Pythona

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

Interfejs API danych Witryn Google umożliwia aplikacjom klienckim dostęp do Witryn Google oraz ich publikowanie i modyfikowanie. Aplikacja kliencka może również prosić o listę ostatnich działań, historię zmian i załączniki.

Oprócz podania ogólnych informacji o możliwościach interfejsu Sites Data API, w tym przewodniku znajdziesz przykłady interakcji z interfejsem API za pomocą biblioteki klienta w języku Python. Informacje o konfigurowaniu biblioteki klienta znajdziesz w artykule o pierwszych krokach z biblioteką klienta Google Data Python. Jeśli chcesz dowiedzieć się więcej o protokole używanym przez bibliotekę klienta w języku Python do interakcji z klasycznym interfejsem Sites API, zapoznaj się z przewodnikiem po protokołach.

Odbiorcy

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienckie korzystające z Witryn Google przy użyciu biblioteki klienta Google Data w Pythonie.

Pierwsze kroki

Aby korzystać z biblioteki klienta w Pythonie, musisz mieć Pythona 2.2 lub nowszego oraz moduły wymienione na stronie wiki DependencyModules. Po pobraniu biblioteki klienta przeczytaj artykuł Pierwsze kroki z biblioteką Google Data Python, aby uzyskać pomoc dotyczącą instalacji i używania klienta.

Uruchamiam próbkę

Pełna wersja 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 zostaną podane, aplikacja poprosi o wpisanie tych wartości. Przykład pozwala użytkownikowi wykonać wiele operacji, które pokazują, jak korzystać z klasycznego interfejsu Sites API. W związku z tym należy dokonać uwierzytelnienia, aby wykonać niektóre operacje (na przykład zmodyfikować treść). Program poprosi też o uwierzytelnienie za pomocą AuthSub, OAuth lub ClientLogin.

Aby umieścić przykłady z tego przewodnika w swoim kodzie, 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 Sites API. Podaj nazwę aplikacji i nazwę przestrzeni internetowej 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ę przy użyciu 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 logowania. Powinien mieć format: company-applicationname-version

Uwaga: w pozostałej części przewodnika założono, że masz utworzony obiekt SitesClient w zmiennej client.

Uwierzytelnianie w klasycznej wersji interfejsu API Witryn

Biblioteki klienta w Pythonie można używać do pracy z publicznymi lub prywatnymi kanałami. Interfejs Sites Data API zapewnia dostęp do prywatnych i publicznych kanałów w zależności od uprawnień witryny i operacji, którą chcesz wykonać. Możesz na przykład odczytywać kanał treści witryny publicznej, ale nie wprowadzać w niej aktualizacji – co wymaga uwierzytelnionego klienta. Możesz to zrobić za pomocą uwierzytelniania za pomocą nazwy użytkownika/hasła ClientLogin, AuthSub lub OAuth.

Zapoznaj się z omówieniem uwierzytelniania interfejsów API danych Google, aby dowiedzieć się więcej o AuthSub, OAuth i ClientLogin.

AuthSub dla aplikacji internetowych

Z uwierzytelniania AuthSub w aplikacjach internetowych powinny korzystać aplikacje klienckie, które muszą uwierzytelniać użytkowników na kontach Google lub G Suite. Operator nie wymaga dostępu do nazwy użytkownika i hasła użytkownika Witryn Google – wymagany jest tylko token AuthSub.

Wyświetl instrukcje włączania AuthSub do aplikacji internetowej

Poproś o token jednorazowy

Gdy użytkownik po raz pierwszy korzysta z Twojej aplikacji, musi się uwierzytelnić. Zwykle deweloperzy drukują tekst i link przekierowujący użytkownika na stronę zatwierdzania AuthSub, aby uwierzytelnić użytkownika i poprosić o dostęp do dokumentów. Biblioteka klienta Google Data Python udostępnia funkcję generate_auth_sub_url() służącą do wygenerowania tego adresu URL. Poniższy kod tworzy 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 G Suite, przekaż nazwę domeny do 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() przyjmuje kilka parametrów (odpowiadających parametrom zapytania używanym przez moduł obsługi AuthSubRequest):

  • next URL (następny adres URL) – adres URL, na który Google przekieruje użytkownika po zalogowaniu się na konto i przyznaniu dostępu; http://www.example.com/myapp.py w przykładzie powyżej.
  • zakres – https://sites.google.com/feeds/
  • secure – wartość logiczna wskazująca, czy token będzie używany w trybie zabezpieczonym i zarejestrowanym; True w powyższym przykładzie;
  • session: druga wartość logiczna wskazująca, czy token jednorazowy będzie później wymieniany na token sesji; True w powyższym przykładzie.

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 uzyska token długotrwałych sesji, zapisz go w bazie danych, aby móc go przywrócić do użytku w przyszłości. Nie musisz odsyłać użytkownika z powrotem do AuthSub przy każdym uruchomieniu aplikacji. Użyj client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR), aby skonfigurować istniejący token w kliencie.

OAuth w przypadku aplikacji internetowych lub zainstalowanych/mobilnych

Protokół OAuth może być używany jako alternatywa dla protokołu AuthSub i jest przeznaczony dla aplikacji internetowych. Protokół OAuth przypomina korzystanie z trybu bezpiecznego i zarejestrowanego AuthSub, ponieważ wszystkie żądania danych muszą być podpisane cyfrowo i trzeba zarejestrować swoją domenę.

Wyświetl instrukcje wdrażania protokołu OAuth w zainstalowanej aplikacji

Pobieram token żądania

Przeczytaj artykuł Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.

Autoryzacja tokena żądania

Przeczytaj artykuł Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.

Przejście na token dostępu

Przeczytaj artykuł Używanie protokołu OAuth z bibliotekami klienta interfejsu Google Data API.

Wskazówka: gdy aplikacja uzyska token dostępu OAuth, zapisz go w bazie danych, aby móc go przywrócić do późniejszego użycia. Nie musisz odsyłać użytkownika z powrotem za pomocą protokołu OAuth przy każdym uruchomieniu aplikacji. Użyj client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET), aby skonfigurować istniejący token w kliencie.

ClientLogin dla aplikacji zainstalowanych/mobilnych

ClientLogin powinien być używany przez zainstalowane lub mobilne aplikacje, które muszą uwierzytelniać użytkowników na kontach Google. Przy pierwszym uruchomieniu aplikacja prosi o podanie nazwy użytkownika i hasła. W kolejnych żądaniach odwołuje się do tokena uwierzytelniania.

Wyświetl instrukcje włączania ClientLogin do zainstalowanej aplikacji

Aby użyć ClientLogin, wywołaj metodę ClientLogin() obiektu SitesClient, która jest dziedziczona z elementu GDClient. Podaj adres e-mail i hasło użytkownika, w imieniu którego Twój klient wysył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 w bazie danych token uwierzytelniania, aby móc go przywrócić do użytku w przyszłości. Nie trzeba prosić użytkownika o podanie hasła przy każdym uruchomieniu aplikacji. Więcej informacji znajdziesz w artykule Wycofywanie tokena uwierzytelniania.

Więcej informacji o korzystaniu z ClientLogin w aplikacjach w Pythonie znajdziesz w artykule Using ClientLogin with the Google Data API Client Libraries.

Powrót do góry

Kanał witryny

Kanał witryny może służyć do wyświetlania listy Witryn Google, które należą do użytkownika lub do których ma uprawnienia do wyświetlania. Za jego pomocą można również zmienić nazwę istniejącej witryny. W przypadku domen G Suite można też używać tej usługi do tworzenia lub kopiowania całej witryny.

Wyświetlanie listy witryn

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ć, aby określić alternatywny identyfikator URI kanału witryny. Domyślnie GetSiteFeed() używa nazwy witryny i domeny ustawione w obiekcie klienckim. Więcej informacji o ustawianiu tych wartości w obiekcie klienta znajdziesz w sekcji Pierwsze kroki.

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ł witryny, jej nazwę, stronę, 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 udostępniać, wywołując metodę CreateSite() biblioteki. Podobnie jak w przypadku pliku pomocniczego GetSiteFeed(), CreateSite() akceptuje również opcjonalny argument uri, którego możesz użyć, by określić alternatywny identyfikator URI kanału witryny (w przypadku utworzenia witryny w domenie innej niż ta ustawiona w obiekcie SitesClient).

Oto przykład tworzenia nowej witryny z motywem „Plansza” oraz podaniem 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. W takim przypadku adres URL witryny będzie wyglądał tak: https://sites.google.com/a/example2.com/tytuł-dla-mojej-witryny.

Jeśli witryna zostanie utworzona, serwer w odpowiedzi zwróci obiekt gdata.sites.data.SiteEntry zawierający elementy dodane przez serwer: link do witryny, link do kanału ACL witryny, nazwę witryny, tytuł, podsumowanie itd.

Kopiowanie witryny

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

CreateSite() może też służyć do kopiowania dotychczasowej witryny. W tym celu przekaż argument słowa kluczowego source_site. Wszystkie skopiowane witryny będą miały ten link dostępny tutaj: entry.FindSourceLink(). Oto przykład duplikowania 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 uwagi:

  • Można kopiować tylko witryny i szablony witryn należące do uwierzytelnionego użytkownika.
  • Szablon witryny można też skopiować. Witryna jest szablonem, jeśli na stronie ustawień Witryn Google zaznaczone jest ustawienie „Opublikuj tę witrynę jako szablon”.
  • Możesz skopiować witrynę z innej domeny – jeśli nie jesteś właścicielem witryny źródłowej.

Aktualizowanie metadanych witryny

Aby zaktualizować tytuł lub podsumowanie witryny, potrzebujesz elementu SiteEntry zawierającego odpowiednią witrynę. W tym przykładzie użyto metody GetEntry() do najpierw pobrania elementu SiteEntry, a następnie zmiany jego tytułu, opisu i tagu 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 sekcji aktywności

Uwaga: aby uzyskać dostęp do tego kanału, musisz być współpracownikiem lub właścicielem witryny. Twój klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.

Możesz pobrać ostatnią aktywność w witrynie (zmiany), 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żda pozycja o aktywności zawiera informacje o zmianie wprowadzonej w witrynie.

Powrót do góry

Pobieranie historii zmian

Uwaga: aby uzyskać dostęp do tego kanału, musisz być współpracownikiem lub właścicielem witryny. Twój klient musi uwierzytelnić się przy użyciu tokena AuthSub, OAuth lub ClientLogin. Zobacz Uwierzytelnianie w usłudze Witryny.

Kanał wersji zawiera informacje o historii zmian dowolnego wpisu z treściami. Za pomocą metody GetRevisionFeed() można pobierać wersje danego wpisu treści. Ta metoda przyjmuje opcjonalny parametr uri, który akceptuje gdata.sites.data.ContentEntry, pełny identyfikator URI wpisu treści lub identyfikator wpisu treści.

Ten przykład wysyła zapytanie do kanału treści i pobiera kanał wersji dla 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 GetRevisionFeed() zwraca obiekt gdata.sites.data.RevisionFeed zawierający listę gdata.sites.data.RevisionEntry. Każdy wpis wersji zawiera takie informacje jak treść danej wersji, numer wersji i data utworzenia nowej wersji.

Powrót do góry

Źródło treści

Pobieranie źródła treści

Uwaga: źródło treści może wymagać uwierzytelniania lub nie w zależności od uprawnień do udostępniania obowiązujących 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 zawiera najnowszą treść witryny. Aby uzyskać do niego dostęp, wywołaj metodę GetContentFeed() biblioteki, która do przekazywania niestandardowego zapytania wymaga opcjonalnego parametru ciągu znaków uri.

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: entry.Kind() można użyć do określenia typu wpisu.

Powstały obiekt feed to obiekt gdata.sites.data.ContentFeed zawierający listę gdata.sites.data.ContentEntry. Każdy wpis reprezentuje inną stronę/element w witrynie użytkownika i zawiera elementy specyficzne dla wpisu. Zobacz przykładową aplikację, aby dowiedzieć się więcej o niektórych właściwościach dostępnych w poszczególnych rodzajach wpisów.

Powrót do góry

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

W źródle treści możesz przeszukiwać niektóre standardowe parametry zapytań interfejsu Google Data API oraz parametry charakterystyczne dla klasycznej wersji interfejsu Sites API. Szczegółowe informacje i pełną listę obsługiwanych parametrów znajdziesz w przewodniku.

Uwaga: w przykładach w tej sekcji użyto metody pomocniczej gdata.sites.client.MakeContentFeedUri() do utworzenia podstawowego identyfikatora URI źródła 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 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żdy z nich kind przecinkiem. Na przykład ten fragment 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 stron według ścieżki

Jeśli znasz względną ścieżkę strony w Witrynach Google, możesz użyć parametru path, aby pobrać tę konkretną stronę. W tym przykładzie zostanie zwrócona strona 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 podanym niżej przykładzie), możesz użyć parametru parent do pobrania wszystkich jej wpisów podrzędnych (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.

Powrót do góry


Tworzenie treści

Uwaga: zanim utworzysz treść witryny, upewnij się, że jest ona skonfigurowana w kliencie.
client.site = "siteName"

Nowe treści (strony internetowe, strony list, magazyny plików, strony z ogłoszeniami itp.) można tworzyć za pomocą CreatePage(). Pierwszym argumentem tej metody powinien być rodzaj strony do utworzenia, a po niej 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 tworzony jest nowy element webpage poniżej najwyższego poziomu, zawierający w treści strony kod XHTML oraz 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 zrealizowane, entry będzie zawierać kopię wpisu utworzonego na serwerze jako gdata.sites.gdata.ContentEntry.

Aby utworzyć bardziej złożony rodzaj wpisu, który zostanie wypełniony podczas tworzenia (np. listpage z nagłówkami kolumn), musisz ręcznie utworzyć właściwość gdata.sites.data.ContentEntry, wypełnić interesujące Cię właściwości i wywołać funkcję client.Post().

Tworzenie elementów/stron w ramach niestandardowych ścieżek adresów URL

Domyślnie poprzedni przykład ma adres URL http://sites.google.com/domainName/siteName/new-webpage-title i jego nagłówek to „Tytuł nowej strony internetowej”. Oznacza to, że tytuł adresu URL jest znormalizowany do wartości new-webpage-title. Aby dostosować ścieżkę adresu URL strony, możesz ustawić we wpisie treści właściwość page_name. Narzędzie pomocnicze CreatePage() podaje tę wartość jako opcjonalny argument słowa kluczowego.

W tym przykładzie tworzymy nową stronę filecabinet o nagłówku „Magazyn plików”, ale strona ma URL http://sites.google.com/domainName/siteName/files (zamiast http://sites.google.com/domainName/siteName/file-storage) przez określenie właściwości 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 tych reguł pierwszeństwa do nazewnictwa ścieżki adresu URL strony:

  1. page_name (jeśli występuje). Musi spełniać następujące kryteria: a-z, A-Z, 0-9, -, _.
  2. title, jeśli nazwa strony nie występuje, nie może mieć wartości null. Normalizacja polega na obcięciu i zwinięciu odstępów do znaku „-” oraz usuwaniu znaków, które nie pasują do a-z, A-Z, 0-9, -, _.

Tworzenie podstron

Aby utworzyć podstrony (podrzędne) w ramach strony nadrzędnej, użyj argumentu słowa kluczowego parent w tabeli CreatePage(). Element parent może mieć typ gdata.sites.gdata.ContentEntry lub ciąg znaków reprezentujący pełny własny identyfikator pozycji treści.

W tym przykładzie wysyłamy zapytanie do źródła treści announcementpage i tworzymy nowy element announcement pod pierwszym znalezionym elementem:

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łam pliki

Podobnie jak w przypadku Witryn Google, interfejs API obsługuje przesyłanie załączników na stronę magazynu plików lub stronę nadrzędną. Załączniki muszą być przesłane na stronę nadrzędną. W związku z tym musisz ustawić link nadrzędny na urządzeniu ContentEntry, który próbujesz przesłać. Więcej informacji znajdziesz w artykule Tworzenie podstron.

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

Przesyłam załączniki

W tym przykładzie plik PDF został przesłany do pierwszego elementu filecabinet znalezionego w źródle treści użytkownika. Załącznik zostanie utworzony z tytułem „Podręcznik dla nowych pracowników” i (opcjonalnym) opisem „Pakiet kadr”.

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 znajdzie na serwerze kopię utworzonego załącznika.

Przesyłanie załącznika do folderu

Magazyny plików w Witrynach Google obsługują foldery. Element UploadAttachment() zawiera dodatkowy argument słów kluczowych folder_name, za pomocą którego możesz przesłać załącznik do folderu filecabinet. 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 w tym przykładzie zamiast ścieżki do pliku do UploadAttachment() jest przekazywany obiekt gdata.data.MediaSource. Nie przekazuje też typu treści. Zamiast tego typ treści jest określony 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 wizytówek w filecabinet. Ta funkcja działa analogicznie do metody przesyłania „Dodaj plik według adresu URL” 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 tworzymy załącznik internetowy w pierwszej kolejności (filecabinet) znaleziony w źródle treści użytkownika. Jego tytuł i (opcjonalny) opis są ustawione na „Logo Google” 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!'

Powoduje ono utworzenie linku wskazującego obraz pod adresem „http://www.google.com/images/logo.gif” w elemencie filecabinet.

Powrót do góry


Aktualizowanie treści

Aktualizowanie metadanych strony lub treści HTML

Metadane (tytuł, nazwa strony itp.) oraz zawartość strony dowolnego rodzaju wpisu można edytować za pomocą metody Update() klienta.

Poniżej znajduje się przykład zaktualizowania elementu listpage za pomocą tych zmian:

  • Tytuł został zmieniony na „Zaktualizowany tytuł”
  • Zawartość HTML strony zostaje zaktualizowana do zaktualizowanej treści HTML
  • Nagłówek pierwszej kolumny na liście 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 treści i metadanych załącznika

Możesz zastąpić zawartość pliku załącznika przez utworzenie nowego obiektu MediaSource z nową zawartością pliku i wywołanie metody Update() klienta. Możesz też zaktualizować metadane załącznika (np. tytuł i opis) lub po prostu metadane. Ten przykład pokazuje jednoczesne aktualizowanie zawartości pliku i metadanych:

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


Usuwam treści

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

client.Delete(content_entry)

Możesz też przekazać metodę Delete() do linku edit 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 klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.

Powrót do góry


Pobieranie załączników

Każdy wpis attachment zawiera link do treści src, za pomocą którego można pobrać zawartość pliku. Klient Witryn zawiera pomocniczą metodę uzyskiwania dostępu do pliku i pobierania go z tego linku: DownloadAttachment(). Akceptuje identyfikator gdata.sites.data.ContentEntry lub identyfikator URI pobierania dla pierwszego argumentu oraz ścieżkę do pliku, w której załącznik jest zapisywany jako drugi.

W tym przykładzie pobierany jest konkretny wpis załącznika (za pomocą zapytania dotyczącego tego linku self) i pobiera plik na 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 deweloper aplikacji może określić rozszerzenie pliku pasujące do typu treści załącznika. Typ treści znajdziesz tutaj: entry.content.type.

W niektórych przypadkach pobranie pliku na dysk może być niemożliwe (np. jeśli aplikacja jest uruchomiona w Google App Engine). W takich sytuacjach użyj polecenia _GetFileContent(), aby pobrać zawartość pliku i zapisać ją w pamięci.

W tym przykładzie pobierany jest 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

Kanał ACL

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

Każdy wpis na liście kontroli dostępu (ACL) reprezentuje rolę dostępu określonego elementu: użytkownika, grupy użytkowników, domeny lub domyślnego dostępu (witryny publicznej). Wpisy będą wyświetlane tylko w przypadku jednostek z jednoznacznym dostępem. Dla każdego adresu e-mail będzie wyświetlany jeden wpis w panelu „Osoby z dostępem” na ekranie udostępniania w interfejsie Witryn Google. Z tego względu administratorzy domen nie będą widoczni, nawet jeśli mają pośredni dostęp do witryny.

Role

Element roli określa poziom dostępu, który 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).
  • właściciel – zwykle administrator witryny (odpowiednik uprawnień do odczytu i zapisu).

Zakresy

Element zakresu reprezentuje jednostkę, która ma ten poziom dostępu. Istnieją 4 rodzaje elementów gAcl:scope:

  • 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 – istnieje tylko jeden możliwy zakres typu „default”, który nie ma żadnej wartości (np.<gAcl:scope type="default">). Ten konkretny zakres kontroluje domyślne uprawnienia dostępu każdego użytkownika do witryny publicznej.

Uwaga: domeny nie mogą mieć wartości gAcl:role ustawionej na dostęp „właściciel”. Mogą to być tylko czytelnicy lub pisarze.

Pobieranie kanału ACL

Kanału listy kontroli dostępu można używać do kontrolowania uprawnień do udostępniania witryny i można go pobrać za pomocą metody GetAclFeed().

Poniższy przykład umożliwia pobranie kanału listy kontroli dostępu dla witryny ustawionej obecnie w obiekcie SitesClient i wydrukowanie wpisów 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 udanym zapytaniu feed stanie się obiektem gdata.sites.data.AclFeed zawierającym listę gdata.sites.data.AclEntry.

Jeśli pracujesz z pozycjami w pliku SiteFeed, każdy element SiteEntry zawiera link do swojego kanału ACL. Na przykład ten fragment pobiera pierwszą witrynę z kanału witryny użytkownika i wysyła zapytanie do jej kanału 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 listy kontroli dostępu (ACL) mogą być dostępne tylko wtedy, gdy domena jest skonfigurowana tak, by zezwalać na takie uprawnienia (np.włączone jest udostępnianie poza domenę w przypadku domen G Suite itp.).

Aby udostępnić witrynę Google za pomocą interfejsu API, utwórz 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 Omówienie pliku danych ACL.

W tym przykładzie przyznajemy 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ć witrynę w grupie dyskusyjnej Google lub domenie G Suite. Niezbędne wartości parametru scope są wymienione poniżej.

Udostępnianie adresu 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 domenach G Suite i tylko w domenie, w której znajduje się 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/witryna/witrynaB), nie mogą zapraszać domen.

Modyfikowanie uprawnień do udostępniania

Aby dodać istniejące uprawnienia udostępniania do witryny, najpierw pobierz dany AclEntry, w razie potrzeby zmień uprawnienia, a następnie wywołaj metodę Update() klienta, aby zmodyfikować listę kontroli dostępu na serwerze.

Ten przykład modyfikuje poprzedni element acl_entry z sekcji Udostępnianie witryny przez zmianę adresu „użytkownik@example.com” na autora (współpracownika):

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 klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.

Usuwanie uprawnień do udostępniania

Aby usunąć uprawnienia do udostępniania, najpierw pobierz AclEntry, a następnie wywołaj metodę Delete() klienta.

client.Delete(acl_entry)

Możesz też przekazać metodę Delete() linku edit wpisu ACL 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 klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.

Powrót do góry

Tematy specjalne

Ponowne pobieranie kanału lub wpisu

Jeśli chcesz pobrać pobrany wcześniej kanał lub wpis, możesz zwiększyć wydajność, informując serwer, że ma wysłać listę lub wpis tylko wtedy, gdy zmieniły się od czasu ostatniego pobrania.

Aby skorzystać z tego rodzaju warunkowego pobierania, przekaż do klasy 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łasza wyjątek gdata.client.NotModified, ETag wpisu odpowiada wersji na serwerze, co oznacza, że masz najbardziej aktualną kopię. Jeśli jednak inny klient lub inny użytkownik wprowadzi zmiany, nowy wpis zostanie zwrócony w funkcji entry i nie zostanie zgłoszony żaden wyjątek.

Więcej informacji o klasach ETag znajdziesz w Przewodniku po interfejsach API danych Google.

Powrót do góry