Wichtig:Dieses Dokument wurde vor 2012 verfasst. Die in diesem Dokument beschriebenen Authentifizierungsoptionen (OAuth 1.0, AuthSub und ClientLogin) wurden am 20. April 2012 offiziell eingestellt und sind nicht mehr verfügbar. Wir empfehlen Ihnen, so schnell wie möglich zu OAuth 2.0 zu migrieren.
Mit der Google Sites Data API können Client-Anwendungen auf Inhalte innerhalb einer Google Sites-Website zugreifen, diese veröffentlichen und ändern. Ihre Client-Anwendung kann auch eine Liste der letzten Aktivitäten anfordern, den Überarbeitungsverlauf abrufen und Anhänge herunterladen.
Neben Informationen zu den Funktionen der Sites Data API finden Sie in diesem Leitfaden auch Beispiele für die Interaktion mit der API mithilfe der Python-Clientbibliothek. Informationen zum Einrichten der Clientbibliothek finden Sie unter Erste Schritte mit der Google Data Python-Clientbibliothek. Weitere Informationen zum zugrunde liegenden Protokoll, das von der Python-Clientbibliothek für die Interaktion mit der klassischen Sites API verwendet wird, finden Sie im Protokollleitfaden.
Zielgruppe
Dieses Dokument richtet sich an Entwickler, die mithilfe der Google Data-Clientbibliothek für Python Clientanwendungen erstellen möchten, die mit Google Sites interagieren.
Erste Schritte
Für die Verwendung der Python-Clientbibliothek benötigen Sie Python 2.2 oder höher und die auf der Wiki-Seite DependencyModules aufgeführten Module. Nach dem Herunterladen der Clientbibliothek finden Sie unter Erste Schritte mit der Google Data Python-Bibliothek weitere Informationen zur Installation und Verwendung des Clients.
Beispiel ausführen
Ein vollständiges Arbeitsbeispiel befindet sich im Unterverzeichnis samples/sites des Mercurial-Repositorys des Projekts (/samples/sites/sites_example.py).
Führen Sie das Beispiel so aus:
python sites_example.py # or python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]
Wenn die erforderlichen Flags nicht angegeben sind, werden Sie von der App zur Eingabe dieser Werte aufgefordert. In diesem Beispiel kann der Nutzer eine Reihe von Vorgängen ausführen, um zu zeigen, wie die klassische Google Sites API verwendet wird. Daher ist für bestimmte Vorgänge (z.B. das Ändern von Inhalten) eine Authentifizierung erforderlich. Das Programm fordert Sie außerdem auf, sich über AuthSub, OAuth oder ClientLogin zu authentifizieren.
Wenn Sie die Beispiele aus diesem Leitfaden in Ihren eigenen Code einbinden möchten, benötigen Sie die folgenden import-Anweisungen:
import atom.data import gdata.sites.client import gdata.sites.data
Außerdem müssen Sie ein SitesClient-Objekt einrichten, das eine Clientverbindung zur klassischen Google Sites API darstellt.
Übergeben Sie den Namen Ihrer Anwendung und den Webspace-Namen der Website (aus der URL):
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Wenn Sie eine Website verwenden möchten, die in einer G Suite-Domain gehostet wird, legen Sie die Domain mithilfe des Parameters domain fest:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')
In den obigen Snippets ist das Argument source optional, wird jedoch für Logging-Zwecke empfohlen. Sie sollte das folgende Format haben: company-applicationname-version
Hinweis: Im weiteren Verlauf dieses Leitfadens wird davon ausgegangen, dass Sie ein SitesClient-Objekt in der Variablen client erstellt haben.
Bei der klassischen Google Sites API authentifizieren
Die Python-Clientbibliothek kann entweder für öffentliche oder private Feeds verwendet werden. Die Sites Data API bietet Zugriff auf private und öffentliche Feeds, abhängig von den Berechtigungen einer Website und dem Vorgang, den Sie ausführen möchten. Sie können beispielsweise den Content-Feed einer öffentlichen Website lesen, aber keine Aktualisierungen vornehmen. Dafür ist ein authentifizierter Client erforderlich. Dies kann über die ClientLogin-Authentifizierung mit Nutzername/Passwort, AuthSub oder OAuth erfolgen.
Weitere Informationen zu AuthSub, OAuth und ClientLogin finden Sie in der Authentifizierungsübersicht der Google Data APIs.
AuthSub für Webanwendungen
Die AuthSub-Authentifizierung für Webanwendungen sollte von Clientanwendungen verwendet werden, die ihre Nutzer für Google- oder G Suite-Konten authentifizieren müssen. Der Operator benötigt keinen Zugriff auf den Nutzernamen und das Passwort des Google Sites-Nutzers – nur ein AuthSub-Token ist erforderlich.
Anleitung zum Einbinden von AuthSub in Ihre Webanwendung ansehen
Einmaltoken anfordern
Wenn der Nutzer Ihre Anwendung zum ersten Mal aufruft, muss er sich authentifizieren. Normalerweise drucken Entwickler etwas Text und einen Link aus, über den der Nutzer zur AuthSub-Genehmigungsseite gelangt, um ihn zu authentifizieren und Zugriff auf seine Dokumente anzufordern. Die Google Data-Clientbibliothek für Python bietet die Funktion generate_auth_sub_url() zum Generieren dieser URL. Mit dem folgenden Code wird ein Link zur Seite AuthSubRequest eingerichtet.
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()
Wenn Sie Nutzer in einer von G Suite gehosteten Domain authentifizieren möchten, übergeben Sie den Domainnamen an 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)
Die Methode generate_auth_sub_url() verwendet mehrere Parameter, die den Abfrageparametern entsprechen, die vom AuthSubRequest-Handler verwendet werden:
- Die nächste URL: URL, zu der Google den Nutzer weiterleitet, nachdem sich der Nutzer in seinem Konto angemeldet und Zugriff gewährt hat; im obigen Beispiel
http://www.example.com/myapp.py. - scope:
https://sites.google.com/feeds/ - secure, ein boolescher Wert, der angibt, ob das Token im sicheren und registrierten Modus verwendet wird oder nicht; im obigen Beispiel
True - session, ein zweiter boolescher Wert, der angibt, ob das Einmaltoken später gegen ein Sitzungstoken ausgetauscht wird oder nicht;
Trueim obigen Beispiel.
Upgrade auf ein Sitzungstoken ausführen
Weitere Informationen finden Sie unter AuthSub mit den Google Data API-Clientbibliotheken verwenden.
Informationen zu einem Sitzungstoken abrufen
Weitere Informationen finden Sie unter AuthSub mit den Google Data API-Clientbibliotheken verwenden.
Sitzungstoken widerrufen
Weitere Informationen finden Sie unter AuthSub mit den Google Data API-Clientbibliotheken verwenden.
Tipp: Nachdem Ihre Anwendung ein langlebiges Sitzungstoken abgerufen hat, speichern Sie dieses Token in Ihrer Datenbank, um es zur späteren Verwendung abzurufen. Der Nutzer muss nicht bei jeder Ausführung Ihrer Anwendung zu AuthSub zurückgeschickt werden.
Verwenden Sie client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR), um ein vorhandenes Token auf dem Client festzulegen.
OAuth für Web-Apps oder installierte/mobile Anwendungen
OAuth kann als Alternative zu AuthSub verwendet werden und ist für Webanwendungen vorgesehen. OAuth ähnelt der Verwendung des sicheren und registrierten Modus von AuthSub insofern, als alle Datenanfragen digital signiert sein müssen und Sie Ihre Domain registrieren müssen.
Anleitung zum Integrieren von OAuth in die installierte Anwendung
Anfragetoken abrufen
Weitere Informationen finden Sie unter OAuth mit den Google Data API-Clientbibliotheken verwenden.
Anfragetoken autorisieren
Weitere Informationen finden Sie unter OAuth mit den Google Data API-Clientbibliotheken verwenden.
Upgrade auf ein Zugriffstoken durchführen
Weitere Informationen finden Sie unter OAuth mit den Google Data API-Clientbibliotheken verwenden.
Tipp: Nachdem Ihre Anwendung ein OAuth-Zugriffstoken abgerufen hat, speichern Sie dieses Token in Ihrer Datenbank, um es zur späteren Verwendung abzurufen. Der Nutzer muss nicht bei jeder Ausführung Ihrer Anwendung über OAuth zurückgeschickt werden.
Verwenden Sie client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET), um ein vorhandenes Token auf dem Client festzulegen.
ClientLogin für installierte/mobile Anwendungen
ClientLogin sollte von installierten oder mobilen Anwendungen verwendet werden, die ihre Nutzer für Google-Konten authentifizieren müssen. Bei der ersten Ausführung wird der Nutzer von der Anwendung zur Eingabe seines Nutzernamens und Passworts aufgefordert. Bei nachfolgenden Anfragen wird auf ein Authentifizierungstoken verwiesen.
Anleitung zum Einbinden von ClientLogin in die installierte Anwendung
Um ClientLogin zu verwenden, rufen Sie die Methode ClientLogin() des Objekts SitesClient auf, die von GDClient übernommen wird. Geben Sie die E-Mail-Adresse und das Passwort des Nutzers an, in dessen Namen Ihr Client Anfragen sendet. Beispiel:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Tipp: Nachdem Ihre Anwendung den Nutzer zum ersten Mal authentifiziert hat, speichern Sie das Authentifizierungstoken in Ihrer Datenbank, um es für die spätere Verwendung abzurufen. Der Nutzer muss nicht bei jeder Ausführung Ihrer Anwendung zur Eingabe seines Passworts aufgefordert werden. Weitere Informationen finden Sie unter Authentifizierungstoken zurückrufen.
Weitere Informationen zur Verwendung von ClientLogin in Ihren Python-Anwendungen finden Sie unter ClientLogin mit den Google Data API-Clientbibliotheken verwenden.
Website-Feed
Im Website-Feed können die Google Sites-Websites aufgelistet werden, die einem Nutzer gehören oder für die er eine Anzeigeberechtigung hat. Es kann auch verwendet werden, um den Namen einer vorhandenen Website zu ändern. Bei G Suite-Domains kann damit auch eine gesamte Website erstellt und/oder kopiert werden.
Websites auflisten
Mit der Methode GetSiteFeed() des Clients kannst du die Websites auflisten, auf die ein Nutzer Zugriff hat. Die Methode verwendet das optionale Argument uri, mit dem Sie einen alternativen Websitefeed-URI angeben können. Standardmäßig verwendet GetSiteFeed() den Websitenamen und die Domain, die für das Clientobjekt festgelegt wurden. Weitere Informationen zum Festlegen dieser Werte für Ihr Clientobjekt finden Sie im Abschnitt Erste Schritte.
Hier sehen Sie ein Beispiel für das Abrufen der Websiteliste des authentifizierten Nutzers:
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
Das obige Snippet gibt den Titel der Website, den Namen der Website, die Website, von der sie kopiert wurde, sowie ihre ACL-Feed-URI aus.
Neue Websites erstellen
Hinweis: Diese Funktion ist nur für G Suite-Domains verfügbar.
Durch Aufrufen der Methode CreateSite() der Bibliothek können neue Websites bereitgestellt werden.
Ähnlich wie der Helper GetSiteFeed() akzeptiert CreateSite() auch das optionale Argument uri, mit dem Sie einen alternativen Websitefeed-URI angeben können, wenn Sie die Website unter einer anderen Domain als der erstellen, die in Ihrem SitesClient-Objekt festgelegt ist.
Hier ist ein Beispiel für die Erstellung einer neuen Website mit dem Thema „Slate“ und Angabe eines Titels und einer (optionalen) Beschreibung:
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
Mit dieser Anfrage wird eine neue Website unter der G Suite-Domain example2.com erstellt.
Die URL der Website lautet also https://sites.google.com/a/beispiel2.de/titel-für-meine-website.
Wenn die Website erfolgreich erstellt wurde, gibt der Server ein gdata.sites.data.SiteEntry-Objekt zurück, das mit Elementen gefüllt ist, die vom Server hinzugefügt wurden: ein Link zur Website, ein Link zum ACL-Feed der Website, der Websitename, der Titel, eine Zusammenfassung usw.
Websites kopieren
Hinweis: Diese Funktion ist nur für G Suite-Domains verfügbar.
CreateSite() kann auch zum Kopieren einer vorhandenen Website verwendet werden. Übergeben Sie dazu das Schlüsselwortargument source_site.
Jede kopierte Website erhält diesen Link, auf den Sie über entry.FindSourceLink() zugreifen können. Hier ist ein Beispiel für das Duplizieren der Website, die im Abschnitt Neue Websites erstellen erstellt wurde:
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
Wichtige Punkte:
- Nur Websites und Websitevorlagen, die dem authentifizierten Nutzer gehören, können kopiert werden.
- Eine Websitevorlage kann auch kopiert werden. Eine Website ist eine Vorlage, wenn die Einstellung „Diese Website als Vorlage veröffentlichen“ auf der Seite mit den Google Sites-Einstellungen aktiviert ist.
- Solange Sie als Inhaber auf der Quellwebsite aufgeführt sind, können Sie Websites aus einer anderen Domain kopieren.
Metadaten einer Website aktualisieren
Um den Titel oder die Zusammenfassung einer Website zu aktualisieren, benötigst du ein SiteEntry, das die betreffende Website enthält. In diesem Beispiel wird mit der Methode GetEntry() zuerst ein SiteEntry abgerufen und dann dessen Titel, Beschreibung und Kategorie-Tag geändert:
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)
Aktivitätsfeed abrufen
Hinweis: Sie müssen ein Mitbearbeiter oder Inhaber der Website sein, um auf diesen Feed zugreifen zu können. Ihr Client muss sich mit einem AuthSub-, OAuth- oder ClientLogin-Token authentifizieren. Weitere Informationen finden Sie unter Beim Sites-Dienst authentifizieren.
Sie können die letzten Aktivitäten (Änderungen) einer Website abrufen, indem Sie den Aktivitätsfeed abrufen.
Die Methode GetActivityFeed() der Lib bietet Zugriff auf diesen Feed:
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)
Beim Aufrufen von GetActivityFeed() wird ein gdata.sites.data.ActivityFeed-Objekt mit einer Liste von gdata.sites.data.ActivityEntry zurückgegeben. Jeder Aktivitätseintrag enthält Informationen
zu einer Änderung, die an der Website vorgenommen wurde.
Überarbeitungsverlauf wird abgerufen
Hinweis: Sie müssen ein Mitbearbeiter oder Inhaber der Website sein, um auf diesen Feed zugreifen zu können. Ihr Client muss sich mit einem AuthSub-, OAuth- oder ClientLogin-Token authentifizieren. Weitere Informationen finden Sie unter Beim Sites-Dienst authentifizieren.
Der Überarbeitungsfeed enthält Informationen zum Überarbeitungsverlauf eines Inhaltseintrags. Mit der Methode GetRevisionFeed() können die Überarbeitungen eines bestimmten Inhaltseintrags abgerufen werden. Die Methode verwendet einen optionalen uri-Parameter, der eine gdata.sites.data.ContentEntry, einen vollständigen URI eines Inhaltseintrags oder eine Inhaltseintrags-ID akzeptiert.
In diesem Beispiel wird der Inhaltsfeed abgefragt und der Überarbeitungsfeed für den ersten Inhaltseintrag abgerufen:
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]
Beim Aufrufen von GetRevisionFeed() wird ein gdata.sites.data.RevisionFeed-Objekt mit einer Liste von gdata.sites.data.RevisionEntry zurückgegeben. Jeder Überarbeitungseintrag enthält Informationen wie den Inhalt dieser Überarbeitung, die Versionsnummer und das Erstellungsdatum der neuen Version.
Inhaltsfeed
Content-Feed abrufen
Hinweis: Abhängig von den Freigabeberechtigungen der Website ist für den Content-Feed möglicherweise eine Authentifizierung erforderlich. Wenn die Website nicht öffentlich ist, muss sich Ihr Client mithilfe eines AuthSub-, OAuth- oder ClientLogin-Tokens authentifizieren. Weitere Informationen finden Sie unter Beim Sites-Dienst authentifizieren.
Der Content-Feed gibt den neuesten Content einer Website zurück. Sie können darauf zugreifen, indem Sie die Methode GetContentFeed() der lib aufrufen. Sie verwendet einen optionalen uri-Stringparameter, um eine benutzerdefinierte Abfrage zu übergeben.
Hier ist ein Beispiel für das Abrufen des gesamten Content-Feeds und das Drucken einiger interessanter Elemente:
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
Tipp: Mit entry.Kind() kann der Typ eines Eintrags ermittelt werden.
Das resultierende feed-Objekt ist ein gdata.sites.data.ContentFeed-Objekt, das eine Liste von gdata.sites.data.ContentEntry enthält. Jeder Eintrag steht für eine andere Seite oder ein anderes Element auf der Website des Nutzers und verfügt über spezielle Elemente für die Art des Eintrags. Eine bessere Vorstellung von einigen der in jedem Eintragstyp verfügbaren Eigenschaften finden Sie in der Beispielanwendung.
Beispiele für Content-Feed-Suchanfragen
Sie können im Inhaltsfeed mit einigen der standardmäßigen Google Data API-Suchparameter sowie mithilfe von Parametern suchen, die für die klassische Google Sites API spezifisch sind. Ausführlichere Informationen und eine vollständige Liste der unterstützten Parameter finden Sie im Referenzhandbuch.
Hinweis: In den Beispielen in diesem Abschnitt wird die Hilfsmethode gdata.sites.client.MakeContentFeedUri() zum Erstellen des Basis-URI des Inhaltsfeeds verwendet.
Bestimmte Eintragstypen abrufen
Verwenden Sie den Parameter kind, um nur einen bestimmten Eintragstyp abzurufen. Dieses Snippet gibt beispielsweise nur attachment-Einträge zurück:
kind = 'webpage' print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Wenn Sie mehr als einen Typ zurückgeben möchten, trennen Sie die einzelnen kind durch Kommas. Dieses Snippet gibt beispielsweise die Einträge filecabinet und listpage zurück:
kind = ','.join(['filecabinet', 'listpage']) print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Seite über Pfad abrufen
Wenn Sie den relativen Pfad einer Seite innerhalb der Google Sites-Website kennen, können Sie diese Seite mithilfe des path-Parameters abrufen.
In diesem Beispiel wird die Seite unter http://sites.google.com/domainName/siteName/path/to/the/page zurückgegeben:
path = '/path/to/the/page' print 'Fetching page by its path: ' + path uri = '%s?path=%s' % (client.MakeContentFeedUri(), path) feed = client.GetContentFeed(uri=uri)
Alle Einträge unter einer übergeordneten Seite abrufen
Wenn du die Inhaltseintrags-ID einer Seite kennst (z.B. „1234567890“ im folgenden Beispiel), kannst du mit dem Parameter parent alle untergeordneten Einträge abrufen (falls vorhanden):
parent = '1234567890' print 'Fetching all children of parent entry: ' + parent uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent) feed = client.GetContentFeed(uri=uri)
Weitere Parameter finden Sie im Referenzhandbuch.
Inhalte erstellen
Hinweis: Bevor Sie Inhalte für eine Website erstellen, prüfen Sie, ob Sie Ihre Website im Client festgelegt haben.client.site = "siteName"
Neue Inhalte (Web-, Listen-, Dateiablagen, Ankündigungsseiten usw.) können mit CreatePage() erstellt werden.
Das erste Argument für diese Methode sollte die Art der zu erstellenden Seite sein, gefolgt vom Titel und dem HTML-Inhalt.
Eine Liste der unterstützten Knotentypen finden Sie im Referenzhandbuch unter dem Parameter kind.
Neue Elemente / Seiten erstellen
In diesem Beispiel wird eine neue webpage unter der obersten Ebene erstellt, einige XHTML für den Seitentext enthalten und der Titel der Überschrift auf „Neuer Titel der Webseite“ gesetzt wird:
entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href
Wenn die Anfrage erfolgreich ist, enthält entry eine Kopie des auf dem Server erstellten Eintrags als gdata.sites.gdata.ContentEntry.
Wenn Sie eine komplexere Eintragsart erstellen möchten, die bei der Erstellung ausgefüllt wird (z.B. ein listpage mit Spaltenüberschriften), müssen Sie gdata.sites.data.ContentEntry manuell erstellen, die entsprechenden Attribute ausfüllen und client.Post() aufrufen.
Elemente/Seiten unter benutzerdefinierten URL-Pfaden erstellen
Das vorherige Beispiel würde standardmäßig unter der URL http://sites.google.com/domainName/siteName/new-webpage-title erstellt werden und die Seitenüberschrift „Neuer Webseitentitel“ haben. Das heißt, der Titel wird für die URL auf new-webpage-title normalisiert.
Um den URL-Pfad einer Seite anzupassen, kannst du die page_name-Eigenschaft im Inhaltseintrag festlegen. Der Helper CreatePage() stellt dies als optionales Schlüsselwortargument bereit.
In diesem Beispiel wird eine neue filecabinet-Seite mit der Überschrift „File Storage“ (Dateispeicher) erstellt, die Seite jedoch unter der URL http://sites.google.com/domainName/siteName/files (anstelle von http://sites.google.com/domainName/siteName/file-storage) erstellt, indem das Attribut page_name angegeben wird.
entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href
Der Server verwendet die folgenden Prioritätsregeln, um den URL-Pfad einer Seite zu benennen:
page_name, falls vorhanden. Mussa-z, A-Z, 0-9, -, _erfüllen.title, darf nicht null sein, wenn kein Seitenname vorhanden ist. Normalisierung besteht darin, Leerzeichen auf „-“ zu kürzen und zu minimieren und Zeichen zu entfernen, die nicht mita-z, A-Z, 0-9, -, _übereinstimmen.
Unterseiten erstellen
Verwenden Sie zum Erstellen untergeordneter Seiten (untergeordnete Seiten) einer übergeordneten Seite das Schlüsselwortargument parent von CreatePage().
Die parent kann entweder eine gdata.sites.gdata.ContentEntry oder ein String sein, der die vollständige Self-ID des Inhaltseintrags darstellt.
In diesem Beispiel wird der Content-Feed nach announcementpage-Werten abgefragt und unter dem ersten gefundenen Element ein neues announcement-Element erstellt:
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!'
Dateien werden hochgeladen
Genau wie in Google Sites unterstützt die API das Hochladen von Anhängen auf eine Ordnerseite oder übergeordnete Seite. Anhänge müssen auf eine übergeordnete Seite hochgeladen werden. Daher musst du einen übergeordneten Link für die ContentEntry festlegen, die du hochladen möchtest. Weitere Informationen finden Sie unter Unterseiten erstellen.
Die Methode UploadAttachment() der Clientbibliothek bietet die Schnittstelle zum Hochladen von Anhängen.
Anhänge werden hochgeladen
In diesem Beispiel wird eine PDF-Datei in das erste filecabinet im Content-Feed des Nutzers hochgeladen.
Der Anhang wird mit dem Titel „Handbuch für neue Mitarbeiter“ und einer (optionalen) Beschreibung „HR-Paket“ erstellt.
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
Wenn der Upload erfolgreich ist, enthält attachment eine Kopie des erstellten Anhangs auf dem Server.
Anhang in einen Ordner hochladen
Ordner in Google Sites-Ordnern werden unterstützt. UploadAttachment() enthält das zusätzliche Schlüsselwortargument folder_name, mit dem Sie einen Anhang in einen filecabinet-Ordner hochladen können. Geben Sie einfach den Namen des Ordners an:
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')
In diesem Beispiel wird ein gdata.data.MediaSource-Objekt anstelle eines Dateipfads an UploadAttachment() übergeben. Es wird auch kein Inhaltstyp übergeben. Stattdessen wird der Inhaltstyp im MediaSource-Objekt angegeben.
Webanhänge
Webanhänge sind spezielle Arten von Anhängen. Im Wesentlichen handelt es sich dabei um Links zu anderen Dateien im Web, die Sie Ihren filecabinet-Einträgen hinzufügen können. Diese Funktion ist analog zur Uploadmethode Datei per URL hinzufügen in der Google Sites-Benutzeroberfläche.
Hinweis: Webanhänge können nur unter einem filecabinet erstellt werden. Sie können nicht auf andere Seitentypen hochgeladen werden.
In diesem Beispiel wird ein Webanhang unter dem ersten filecabinet im Content-Feed des Nutzers erstellt.
Für den Titel und die optionale Beschreibung sind „GoogleLogo“ bzw. „netten Farben“ festgelegt.
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!'
Durch den Aufruf wird ein Link erstellt, der auf das Bild unter "http://www.google.com/images/logo.gif" im filecabinet verweist.
Inhalte aktualisieren
Metadaten und/oder HTML-Inhalte einer Seite aktualisieren
Die Metadaten (title, pageName usw.) und der Seiteninhalt beliebiger Eintragstypen können mit der Methode Update() des Clients bearbeitet werden.
Im Folgenden finden Sie ein Beispiel für das Aktualisieren einer listpage mit den folgenden Änderungen:
- Der Titel wird in „Aktualisierter Titel“ geändert.
- Der HTML-Inhalt der Seite wird zu „Aktualisierter HTML-Inhalt“ aktualisiert.
- Die erste Spaltenüberschrift der Liste wird in "Inhaber" geändert.
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!'
Inhalt und Metadaten eines Anhangs ersetzen
Sie können den Dateiinhalt eines Anhangs ersetzen, indem Sie ein neues MediaSource-Objekt mit dem neuen Dateiinhalt erstellen und die Methode Update() des Clients aufrufen. Auch die Metadaten des Anhangs (z. B. Titel und Beschreibung) können oder einfach nur die Metadaten aktualisiert werden.
In diesem Beispiel wird veranschaulicht, wie Dateiinhalt und Metadaten gleichzeitig aktualisiert werden:
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)
Inhalte löschen
Wenn Sie eine Seite oder ein Element von einer Google Sites-Website entfernen möchten, rufen Sie zuerst den Inhaltseintrag ab und rufen Sie dann die Methode Delete() des Clients auf.
client.Delete(content_entry)
Sie können auch die Methode Delete() übergeben und den Link edit des Inhaltseintrags übergeben und/oder das Löschen erzwingen:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(content_entry.GetEditLink().href, force=True)
Weitere Informationen zu ETags finden Sie im Referenzhandbuch für Google Data APIs.
Anhänge herunterladen
Jeder attachment-Eintrag enthält einen src-Content-Link, über den der Dateiinhalt heruntergeladen werden kann.
Der Sites-Client enthält eine Hilfsmethode, um über diesen Link auf die Datei zuzugreifen und sie herunterzuladen: DownloadAttachment().
Er akzeptiert als erstes Argument einen gdata.sites.data.ContentEntry- oder Download-URI und als zweites Argument einen Dateipfad, in dem der Anhang gespeichert werden soll.
In diesem Beispiel wird ein bestimmter Anhangseintrag abgerufen (durch Abfrage des Links self) und die Datei in den angegebenen Pfad heruntergeladen:
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!'
Der App-Entwickler muss eine Dateiendung angeben, die für den Inhaltstyp des Anhangs sinnvoll ist. Der Inhaltstyp ist in entry.content.type zu finden.
In einigen Fällen können Sie die Datei möglicherweise nicht auf die Festplatte herunterladen, z.B. wenn Ihre Anwendung in Google App Engine ausgeführt wird.
Verwenden Sie in diesen Situationen _GetFileContent(), um den Dateiinhalt abzurufen und im Arbeitsspeicher zu speichern.
Dieser Beispieldownload ist ein Anhang im Arbeitsspeicher.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
ACL-Feed
Übersicht über Freigabeberechtigungen (ACLs)
Jeder ACL-Eintrag im ACL-Feed steht für eine Zugriffsrolle einer bestimmten Entität, entweder eines Nutzers, einer Gruppe von Nutzern, einer Domain oder dem Standardzugriff (eine öffentliche Website). Einträge werden nur für Entitäten mit explizitem Zugriff angezeigt. Auf dem Freigabebildschirm der Google Sites-Benutzeroberfläche wird im Bereich "Personen mit Zugriff" für jede E-Mail-Adresse ein Eintrag angezeigt. Daher werden Domainadministratoren nicht angezeigt, auch wenn sie impliziten Zugriff auf eine Website haben.
Rollen
Das Rollenelement stellt eine Zugriffsebene dar, die eine Entität haben kann. Für das Element gAcl:role gibt es vier mögliche Werte:
- reader – ein Betrachter (entspricht dem Lesezugriff).
- writer – ein Mitbearbeiter (entspricht dem Lese-/Schreibzugriff).
- owner: normalerweise der Administrator der Website (entspricht Lese-/Schreibzugriff)
Ebenen
Das Bereichselement stellt die Entität dar, die diese Zugriffsebene hat. Es gibt vier mögliche Typen des gAcl:scope-Elements:
- Nutzer: Ein E-Mail-Adresswert, z. B. „nutzer@gmail.com“.
- Gruppe: E-Mail-Adresse einer Google Groups-Gruppe, z. B. "gruppe@domain.com".
- domain: ein G Suite-Domainname, z. B. "domain.com".
- default: Es gibt nur einen möglichen Bereich vom Typ „default“, der keinen Wert hat (z. B.
<gAcl:scope type="default">). Mit diesem speziellen Bereich wird der Zugriff gesteuert, den jeder Nutzer standardmäßig auf einer öffentlichen Website hat.
Hinweis: Für Domains kann der Wert gAcl:role nicht auf „Inhaber“ festgelegt sein. Sie können nur Leser oder Autoren sein.
ACL-Feed abrufen
Über den ACL-Feed können die Freigabeberechtigungen einer Website gesteuert werden. Er kann mithilfe der GetAclFeed()-Methode abgerufen werden.
Im folgenden Beispiel wird der ACL-Feed für die Website abgerufen, die derzeit für das SitesClient-Objekt festgelegt ist, und die Berechtigungseinträge werden ausgegeben:
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)
Nach einer erfolgreichen Abfrage ist feed ein gdata.sites.data.AclFeed-Objekt mit einer Liste von gdata.sites.data.AclEntry.
Wenn Sie mit Einträgen im SiteFeed arbeiten, enthält jede SiteEntry einen Link zum zugehörigen ACL-Feed.
Das Snippet ruft beispielsweise die erste Website im Website-Feed des Nutzers ab und fragt den ACL-Feed ab:
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())
Website freigeben
Hinweis: Bestimmte Freigabe-ACLs sind möglicherweise nur möglich, wenn die Domain entsprechend konfiguriert ist, z.B. wenn die Freigabe außerhalb der Domain für G Suite-Domains aktiviert ist usw.
Wenn Sie eine Google Sites-Website über die API freigeben möchten, erstellen Sie ein gdata.sites.gdata.AclEntry mit den gewünschten gdata.acl.data.AclScope- und gdata.acl.data.AclRole-Werten. Im Abschnitt Übersicht über den ACL-Feed finden Sie die möglichen Werte für AclScope und AclRoles.
Im folgenden Beispiel wird dem Nutzer „nutzer@beispiel.de“ Leseberechtigungen auf der Website gewährt:
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)
Freigabe auf Gruppen- und Domainebene
Ähnlich wie bei der Freigabe einer Website für einen einzelnen Nutzer können Sie eine Website für eine Google-Gruppe oder G Suite-Domain freigeben. Die erforderlichen scope-Werte sind unten aufgeführt.
Freigabe für eine Gruppen-E-Mail-Adresse:
scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')
Freigabe für eine gesamte Domain:
scope = gdata.acl.data.AclScope(value='example.com', type='domain')
Die Freigabe auf Domainebene wird nur für G Suite-Domains und nur für die Domain unterstützt, in der die Website gehostet wird. Beispielsweise kann http://sites.google.com/a/domain1.com/siteA nur die gesamte Website für domain1.com freigeben, nicht für domain2.com. Websites, die nicht auf einer G Suite-Domain gehostet werden (z.B. http://sites.google.com/site/siteB), können keine Domains einladen.
Freigabeberechtigungen ändern
Wenn Sie eine vorhandene Freigabeberechtigung für eine Website freigeben möchten, rufen Sie zuerst die betreffende AclEntry ab, ändern Sie die Berechtigung wie gewünscht und rufen Sie dann die Methode Update() des Clients auf, um die ACL auf dem Server zu ändern.
In diesem Beispiel wird acl_entry aus dem Abschnitt Website freigeben geändert. Dabei wird „nutzer@beispiel.de“ als Autor (Mitbearbeiter) festgelegt:
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)
Weitere Informationen zu ETags finden Sie im Referenzhandbuch für Google Data APIs.
Freigabeberechtigungen werden entfernt
Wenn Sie eine Freigabeberechtigung entfernen möchten, rufen Sie zuerst das AclEntry ab und rufen Sie dann die Methode Delete() des Clients auf.
client.Delete(acl_entry)
Sie können auch die Methode Delete() des ACL-Eintrags den edit-Link übergeben und/oder das Löschen erzwingen:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(acl_entry.GetEditLink().href, force=True)
Weitere Informationen zu ETags finden Sie im Referenzhandbuch für Google Data APIs.
Spezielle Themen
Feed oder Eintrag noch einmal abrufen
Wenn Sie einen zuvor abgerufenen Feed oder Eintrag abrufen möchten, können Sie die Effizienz verbessern, indem Sie den Server anweisen, die Liste oder den Eintrag nur dann zu senden, wenn er sich seit dem letzten Abruf geändert hat.
Für diese Art von bedingten Abruf übergeben Sie einen ETag-Wert an GetEntry(). Wenn beispielsweise bereits ein entry-Objekt vorhanden ist:
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
Wenn GetEntry() die Ausnahme gdata.client.NotModified auslöst, stimmt das ETag des Eintrags mit der Version auf dem Server überein, d. h., Sie haben die aktuelle Kopie.
Wenn jedoch ein anderer Client oder Nutzer Änderungen vorgenommen hat, wird der neue Eintrag in entry zurückgegeben und es wird keine Ausnahme ausgelöst.
Weitere Informationen zu ETags finden Sie im Referenzhandbuch für Google Data APIs.