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, so schnell wie möglich zu OAuth 2.0 zu migrieren.
Mit der Google Sites Data API können Clientanwendungen auf Inhalte in einer Google Sites-Website zugreifen, diese veröffentlichen und ändern. Ihre Clientanwendung kann auch eine Liste der letzten Aktivitäten anfordern, den Änderungsverlauf abrufen und Anhänge herunterladen.
Dieser Leitfaden bietet nicht nur einen Überblick über die Funktionen der Sites Data API, sondern auch Beispiele für die Interaktion mit der API mithilfe der Python-Clientbibliothek. Hilfe zum Einrichten der Clientbibliothek finden Sie unter Erste Schritte mit der Google Data-Clientbibliothek für Python. 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 Clientanwendungen schreiben möchten, die mit Google Sites über die Google Data Python-Clientbibliothek interagieren.
Erste Schritte
Zur Verwendung der Python-Clientbibliothek benötigen Sie Python 2.2 oder höher sowie die auf der Wiki-Seite DependencyModules aufgeführten Module. Nachdem Sie die Clientbibliothek heruntergeladen haben, finden Sie unter Einstieg in die Google Data Python Library Informationen zur Installation und Verwendung des Clients.
Beispiel ausführen
Ein vollständiges funktionsfähiges Beispiel 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 werden, werden Sie von der App aufgefordert, diese Werte einzugeben. Mit dem Beispiel können Nutzer eine Reihe von Vorgängen ausführen, die die Verwendung der klassischen Sites API veranschaulichen. Daher müssen Sie sich authentifizieren, um bestimmte Vorgänge ausführen zu können, z. B. Inhalte zu ändern. Außerdem werden Sie aufgefordert, sich über AuthSub, OAuth oder ClientLogin zu authentifizieren.
Wenn Sie die Beispiele in 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 Sites API darstellt.
Geben Sie den Namen Ihrer Anwendung und den Webspace-Namen der Website (aus der URL) an:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Wenn Sie mit einer Website arbeiten möchten, die auf einer G Suite-Domain gehostet wird, legen Sie die Domain mit dem Parameter 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 aber zu Protokollierungszwecken empfohlen. Er sollte folgendermaßen formatiert sein: company-applicationname-version.
Hinweis: In diesem Leitfaden wird davon ausgegangen, dass Sie ein SitesClient-Objekt in der Variablen client erstellt haben.
Bei der klassischen Sites API authentifizieren
Die Python-Clientbibliothek kann sowohl mit öffentlichen als auch mit privaten Feeds verwendet werden. Die Sites Data API bietet Zugriff auf private und öffentliche Feeds, je nach den Berechtigungen einer Website und dem gewünschten Vorgang. So können Sie beispielsweise den Inhaltsfeed einer öffentlichen Website lesen, aber keine Änderungen daran vornehmen. Dafür ist ein authentifizierter Client erforderlich. Dies kann über die Nutzername/Passwort-Authentifizierung ClientLogin, AuthSub oder OAuth erfolgen.
Weitere Informationen zu AuthSub, OAuth und ClientLogin finden Sie in der Übersicht zur Authentifizierung bei Google Data APIs.
AuthSub für Webanwendungen
Die AuthSub-Authentifizierung für Webanwendungen sollte von Clientanwendungen verwendet werden, die ihre Nutzer bei Google- oder G Suite-Konten authentifizieren müssen. Der Operator benötigt keinen Zugriff auf den Nutzernamen und das Passwort für den Google Sites-Nutzer – nur ein AuthSub-Token ist erforderlich.
Anleitung zum Einbinden von AuthSub in Ihre Webanwendung
Einmaliges Token anfordern
Wenn der Nutzer Ihre Anwendung zum ersten Mal aufruft, muss er sich authentifizieren. Normalerweise drucken Entwickler Text und einen Link aus, über den der Nutzer zur AuthSub-Genehmigungsseite weitergeleitet wird, um sich zu authentifizieren und Zugriff auf seine Dokumente anzufordern. Die Google Data Python-Clientbibliothek 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 des AuthSubRequest-Handlers entsprechen:
- next: URL, zu der Google weiterleitet, nachdem sich der Nutzer in seinem Konto angemeldet und Zugriff gewährt hat;
http://www.example.com/myapp.pyim Beispiel oben - Umfang:
https://sites.google.com/feeds/ - secure: ein boolescher Wert, der angibt, ob das Token im sicheren und registrierten Modus verwendet wird oder nicht;
Trueim obigen Beispiel - session: Eine zweite boolesche Variable, die angibt, ob das Einmaltoken später gegen ein Sitzungstoken eingetauscht wird oder nicht;
Trueim Beispiel oben
Upgrade auf ein Sitzungstoken
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
Siehe AuthSub mit den Google Data API-Clientbibliotheken verwenden
Tipp: Nachdem Ihre Anwendung ein langlebiges Sitzungstoken abgerufen hat, speichern Sie es in Ihrer Datenbank, um es später wiederverwenden zu können. Sie müssen den Nutzer nicht bei jedem Ausführen Ihrer Anwendung zu AuthSub zurücksenden.
Mit client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) kannst du ein vorhandenes Token auf dem Client festlegen.
OAuth für Webanwendungen oder installierte/mobile Anwendungen
OAuth kann als Alternative zu AuthSub verwendet werden und ist für Webanwendungen bestimmt. OAuth ähnelt der Verwendung des sicheren und registrierten Modus von AuthSub insofern, als alle Datenanfragen digital signiert werden und Sie Ihre Domain registrieren müssen.
Anleitung zur Integration von OAuth in Ihrer installierten Anwendung
Anfragetoken abrufen
Weitere Informationen finden Sie unter OAuth mit den Google Data API-Clientbibliotheken verwenden.
Anfragetoken autorisieren
Siehe OAuth mit den Google Data API-Clientbibliotheken verwenden.
Auf ein Zugriffstoken umstellen
Siehe 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 später wiederverwenden zu können. Sie müssen den Nutzer nicht bei jedem Ausführen Ihrer Anwendung über OAuth zurücksenden.
Mit client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) kannst du ein vorhandenes Token auf dem Client festlegen.
ClientLogin für installierte/mobile Anwendungen
ClientLogin sollte von installierten oder mobilen Anwendungen verwendet werden, die ihre Nutzer bei Google-Konten authentifizieren müssen. Beim ersten Start wird der Nutzer von Ihrer App aufgefordert, seinen Nutzernamen und sein Passwort einzugeben. Bei nachfolgenden Anfragen wird auf ein Authentifizierungstoken verwiesen.
Anleitung zur Integration von ClientLogin in Ihre installierte Anwendung
Wenn Sie ClientLogin verwenden möchten, rufen Sie die Methode ClientLogin() des SitesClient-Objekts auf, die von GDClient übernommen wird. Geben Sie die E-Mail-Adresse und das Passwort des Nutzers an, in dessen Namen Ihr Kunde Anfragen stellt. Beispiel:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Tipp: Nachdem die Anwendung den Nutzer zum ersten Mal erfolgreich authentifiziert hat, speichern Sie das Authentifizierungstoken in Ihrer Datenbank, um es später wiederverwenden zu können. 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-Client-Bibliotheken verwenden.
Websitefeed
Im Websitefeed können die Google Sites aufgeführt werden, deren Inhaber ein Nutzer ist oder für die er Leseberechtigungen hat. Außerdem können Sie damit den Namen einer vorhandenen Website ändern. Für G Suite-Domains kann damit auch eine ganze Website erstellt und/oder kopiert werden.
Websites auflisten
Verwenden Sie die GetSiteFeed()-Methode des Clients, um die Websites aufzulisten, 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 sind. Weitere Informationen zum Festlegen dieser Werte für Ihr Clientobjekt finden Sie im Abschnitt Erste Schritte.
Hier ist 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 Snippet oben gibt den Titel der Website, den Namen der Website, die Website, von der sie kopiert wurde, und die zugehörige ACL-Feed-URI aus.
Neue Websites erstellen
Hinweis: Diese Funktion ist nur für G Suite-Domains verfügbar.
Neue Websites können bereitgestellt werden, indem die CreateSite()-Methode der Bibliothek aufgerufen wird.
Ähnlich wie der Helper GetSiteFeed() akzeptiert CreateSite() auch ein optionales Argument, uri, mit dem Sie einen alternativen Websitefeed-URI angeben können, wenn Sie die Website unter einer anderen Domain als derjenigen erstellen, die für Ihr SitesClient-Objekt festgelegt ist.
Hier siehst du ein Beispiel für die Erstellung einer neuen Website mit dem Thema „Slate“ sowie einem Titel 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 der obigen Anfrage wird eine neue Website unter der G Suite-Domain example2.com erstellt.
Die URL der Website wäre also https://sites.google.com/a/beispiel2.de/titel-für-meine-website.
Wenn die Website erfolgreich erstellt wurde, antwortet der Server mit einem gdata.sites.data.SiteEntry-Objekt, das vom Server hinzugefügte Elemente enthält: einen Link zur Website, einen Link zum ACL-Feed der Website, den Namen der Website, den Titel, die Zusammenfassung usw.
Website kopieren
Hinweis: Diese Funktion ist nur für G Suite-Domains verfügbar.
Mit CreateSite() lässt sich auch eine vorhandene Website kopieren. Übergeben Sie dazu das Keyword-Argument source_site.
Alle kopierten Websites haben diesen Link, auf den über entry.FindSourceLink() zugegriffen werden kann. Hier sehen Sie 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.
- Auch eine Website-Vorlage kann kopiert werden. Eine Website ist eine Vorlage, wenn die Einstellung "Diese Website als Vorlage veröffentlichen" in den Google Sites-Einstellungen aktiviert ist.
- Sie können Websites von einer anderen Domain kopieren, sofern Sie auf der Quellwebsite als Inhaber aufgeführt sind.
Metadaten einer Website aktualisieren
Wenn Sie den Titel oder die Zusammenfassung einer Website aktualisieren möchten, benötigen Sie eine SiteEntry mit der betreffenden Website. In diesem Beispiel wird mit der Methode GetEntry() zuerst eine SiteEntry abgerufen und dann der Titel, die Beschreibung und das 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 benötigen Zugriff als Mitbearbeiter oder Inhaber der Website, 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 Authentifizierung beim Sites-Dienst.
Sie können die letzten Aktivitäten (Änderungen) einer Website abrufen, indem Sie den Aktivitätsfeed abrufen.
Die GetActivityFeed()-Methode der Bibliothek 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)
Der Aufruf von GetActivityFeed() gibt ein gdata.sites.data.ActivityFeed-Objekt mit einer Liste von gdata.sites.data.ActivityEntry zurück. Jeder Aktivitätseintrag enthält Informationen zu einer Änderung, die an der Website vorgenommen wurde.
Überarbeitungsverlauf wird abgerufen
Hinweis: Sie benötigen Zugriff als Mitbearbeiter oder Inhaber der Website, 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 Authentifizierung beim Sites-Dienst.
Der Überarbeitungsfeed enthält Informationen zum Überarbeitungsverlauf für jeden Inhaltseintrag. Mit der Methode GetRevisionFeed() können Sie die Versionen für einen bestimmten Inhaltseintrag abrufen. Die Methode nimmt einen optionalen Parameter uri an, der einen gdata.sites.data.ContentEntry, einen vollständigen URI eines Inhaltseintrags oder eine Inhaltseintrags-ID akzeptiert.
In diesem Beispiel wird der Inhaltsfeed abgefragt und der Rezensionsfeed 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]
Wenn Sie GetRevisionFeed() aufrufen, wird ein gdata.sites.data.RevisionFeed-Objekt mit einer Liste von gdata.sites.data.RevisionEntry zurückgegeben. Jeder Revisionseintrag enthält Informationen wie den Inhalt der jeweiligen Version, die Versionsnummer und das Datum, an dem die neue Version erstellt wurde.
Inhaltsfeed
Inhaltsfeed abrufen
Hinweis: Für den Inhaltsfeed ist möglicherweise eine Authentifizierung erforderlich. Das hängt von den Freigabeberechtigungen der Website ab. Wenn die Website nicht öffentlich ist, muss sich Ihr Client mit einem AuthSub-, OAuth- oder ClientLogin-Token authentifizieren. Weitere Informationen finden Sie unter Authentifizierung beim Sites-Dienst.
Der Inhaltsfeed gibt die neuesten Inhalte einer Website zurück. Sie können darauf zugreifen, indem Sie die GetContentFeed()-Methode der lib-Bibliothek aufrufen. Dabei wird ein optionaler uri-Stringparameter zum Übergeben einer benutzerdefinierten Abfrage verwendet.
Hier ist ein Beispiel, wie Sie den gesamten Content-Feed abrufen und einige interessante Elemente ausdrucken können:
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() können Sie den Typ eines Eintrags ermitteln.
Das resultierende feed-Objekt ist eine gdata.sites.data.ContentFeed mit einer Liste von gdata.sites.data.ContentEntry. Jeder Eintrag steht für eine andere Seite/einen anderen Artikel auf der Website des Nutzers und enthält Elemente, die für die Art des Eintrags spezifisch sind. In der Beispielanwendung finden Sie weitere Informationen zu einigen der Eigenschaften, die für jede Art von Eintrag verfügbar sind.
Beispiele für Content-Feed-Abfragen
Sie können den Content-Feed mit einigen der standardmäßigen Google Data API-Abfrageparameter und solchen, die für die klassische Sites API spezifisch sind, durchsuchen. Weitere 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 Content-Feeds verwendet.
Bestimmte Arten von Einträgen abrufen
Wenn Sie nur einen bestimmten Eintragstyp abrufen möchten, verwenden Sie den Parameter kind. 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 mehrere Typen 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)
Seiten per Pfad abrufen
Wenn Sie den relativen Pfad einer Seite auf der Google-Website kennen, können Sie mit dem Parameter path diese Seite 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 Sie die Inhaltseintrags-ID einer Seite kennen (z.B. „1234567890“ im Beispiel unten), können Sie 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 (Webseiten, Listenseiten, Ordner, 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 ihrem HTML-Inhalt.
Eine Liste der unterstützten Knotentypen finden Sie im Referenzhandbuch im Parameter kind.
Neue Elemente / Seiten erstellen
In diesem Beispiel wird ein neues webpage-Element unter der obersten Ebene erstellt. Außerdem enthält es XHTML für den Seitentext und als Titel der Überschrift wird „New WebPage Title“ festgelegt:
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 Datensatzart erstellen möchten, die beim Erstellen ausgefüllt wird (z. B. eine listpage mit Spaltenüberschriften), müssen Sie die gdata.sites.data.ContentEntry manuell erstellen, die gewünschten Properties eingeben und client.Post() aufrufen.
Elemente/Seiten unter benutzerdefinierten URL-Pfaden erstellen
Standardmäßig wird das vorherige Beispiel unter der URL http://sites.google.com/domainName/siteName/new-webpage-title erstellt und hat den Seitentitel „Neuer Seitentitel“. Das heißt, der Titel wird für die URL auf new-webpage-title normalisiert.
Wenn Sie den URL-Pfad einer Seite anpassen möchten, können Sie die Property page_name für den Inhaltseintrag festlegen. Der CreatePage()-Helfer bietet dies als optionales Keyword-Argument an.
In diesem Beispiel wird eine neue filecabinet-Seite mit der Überschrift „File Storage“ erstellt. Die Seite wird jedoch unter der URL http://sites.google.com/domainName/siteName/files (anstelle von http://sites.google.com/domainName/siteName/file-storage) erstellt. Dazu wird das Attribut page_name angegeben.
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 Vorrangregeln für die Benennung des URL-Pfads einer Seite:
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 entfernen und zu minimieren und Zeichen zu entfernen, die nicht mita-z, A-Z, 0-9, -, _übereinstimmen.
Unterseiten erstellen
Wenn Sie Unterseiten (untergeordnete Seiten) unter einer übergeordneten Seite erstellen möchten, verwenden Sie das Keyword-Argument parent von CreatePage().
parent kann entweder eine gdata.sites.gdata.ContentEntry oder ein String sein, der die vollständige Selbst-ID des Eintrags des Inhalts darstellt.
In diesem Beispiel wird der Inhaltsfeed nach announcementpages abgefragt und eine neue announcement unter der ersten gefundenen 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 hochladen
Wie in Google Sites unterstützt die API das Hochladen von Anhängen an eine Ordnerseite oder eine übergeordnete Seite. Anhänge müssen auf eine übergeordnete Seite hochgeladen werden. Daher müssen Sie auf der ContentEntry, die Sie hochladen möchten, einen übergeordneten Link festlegen. Weitere Informationen finden Sie unter Unterseiten erstellen.
Die UploadAttachment()-Methode der Clientbibliothek bietet die Schnittstelle zum Hochladen von Anhängen.
Anhänge werden hochgeladen
In diesem Beispiel wird eine PDF-Datei in die erste filecabinet hochgeladen, die im Inhaltsfeed des Nutzers gefunden wird.
Der Anhang wird mit dem Titel „New Employee Handbook“ und der (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 war, enthält attachment eine Kopie des erstellten Anhangs auf dem Server.
Anhang in einen Ordner hochladen
Ordner in Google Sites unterstützen Ordner. UploadAttachment() bietet ein zusätzliches Schlüsselwortargument folder_name, mit dem Sie einen Anhang in einen filecabinet-Ordner hochladen können. Geben Sie dazu 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 entspricht der Uploadmethode Datei per URL hinzufügen in der Google Sites-Benutzeroberfläche.
Hinweis: Webanhänge können nur unter einer filecabinet erstellt werden. Sie können nicht auf andere Seitentypen hochgeladen werden.
In diesem Beispiel wird ein Webanhang unter der ersten filecabinet erstellt, die im Inhaltsfeed des Nutzers gefunden wird.
Der Titel und die (optionale) Beschreibung sind auf „GoogleLogo“ und „schöne 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 Seiteninhalte jeder Eintragsart können mit der Update()-Methode des Clients bearbeitet werden.
Im folgenden Beispiel wird eine listpage-Datei mit den folgenden Änderungen aktualisiert:
- Der Titel wird in „Aktualisierter Titel“ geändert.
- Der HTML-Inhalt der Seite wird auf „Aktualisierte HTML-Inhalte“ 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 Update()-Methode des Clients aufrufen. Auch die Metadaten des Anhangs (z. B. Titel und Beschreibung) können aktualisiert werden.
In diesem Beispiel wird gezeigt, wie Dateiinhalte 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 du eine Seite oder ein Element von einer Google Sites-Website entfernen möchtest, rufe zuerst den Inhaltseintrag ab und rufe dann die Methode Delete() des Clients auf.
client.Delete(content_entry)
Sie können auch die Methode Delete() des Links 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 Inhaltslink src, über den der Dateiinhalt heruntergeladen werden kann.
Der Sites-Client enthält eine Hilfsmethode, mit der Sie über diesen Link auf die Datei zugreifen und sie herunterladen können: DownloadAttachment().
Als erstes Argument wird ein gdata.sites.data.ContentEntry- oder Download-URI und als zweites Argument ein Dateipfad zum Speichern des Anhangs akzeptiert.
In diesem Beispiel wird ein bestimmter Anhangseintrag abgerufen (durch Abfrage des self-Links) und die Datei wird an 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!'
Es liegt in der Verantwortung des App-Entwicklers, eine Dateiendung anzugeben, die für den Inhaltstyp des Anhangs sinnvoll ist. Den Inhaltstyp finden Sie unter entry.content.type.
In einigen Fällen können Sie die Datei möglicherweise nicht auf die Festplatte herunterladen, z. B. wenn Ihre App in der Google App Engine ausgeführt wird.
Verwenden Sie in diesen Fällen _GetFileContent(), um den Dateiinhalt abzurufen und im Arbeitsspeicher zu speichern.
Dieser Beispieldownload ist ein Anhang in der Erinnerung.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
ACL-Feed
Freigabeberechtigungen (ACLs) – Übersicht
Jeder ACL-Eintrag im ACL-Feed stellt eine Zugriffsrolle eines bestimmten Elements dar, entweder eines Nutzers, einer Gruppe von Nutzern, einer Domain oder des Standardzugriffs (eine öffentliche Website). Einträge werden nur für Entitäten mit explizitem Zugriff angezeigt. Auf dem Bildschirm „Teilen“ der Google Sites-Benutzeroberfläche wird im Bereich „Personen mit Zugriff“ jeweils ein Eintrag für jede E-Mail-Adresse angezeigt. Daher werden Domainadministratoren nicht angezeigt, obwohl sie impliziten Zugriff auf eine Website haben.
Rollen
Das Rollenelement stellt eine Zugriffsebene dar, die eine Entität haben kann. Das Element gAcl:role hat vier mögliche Werte:
- reader: Betrachter (entspricht Lesezugriff).
- writer – ein Mitbearbeiter (entspricht Lese-/Schreibzugriff).
- owner: in der Regel der Website-Administrator (entspricht Lese-/Schreibzugriff).
Ebenen
Das Element „scope“ stellt die Entität dar, die diese Zugriffsebene hat. Es gibt vier mögliche Typen von gAcl:scope-Elementen:
- user: E-Mail-Adresse, z. B. „user@gmail.com“.
- group – eine E-Mail-Adresse einer Google-Gruppe, z. B. „gruppe@domain.com“.
- domain – ein G Suite-Domainname, z. B. „domain.com“.
- default: Es gibt nur einen möglichen Gültigkeitsbereich vom Typ „default“, der keinen Wert hat (z. B.
<gAcl:scope type="default">). Mit diesem Gültigkeitsbereich wird der Zugriff gesteuert, den alle Nutzer standardmäßig auf eine öffentliche Website haben.
Hinweis: Für Domains darf der Wert gAcl:role nicht auf den Zugriff „Inhaber“ gesetzt sein. Sie können nur Leser oder Autoren sein.
ACL-Feed abrufen
Mit dem ACL-Feed können die Freigabeberechtigungen einer Website gesteuert werden. Er kann mit der Methode GetAclFeed() abgerufen werden.
Im folgenden Beispiel wird der ACL-Feed für die Website abgerufen, die derzeit für das Objekt SitesClient 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 jeder SiteEntry einen Link zum entsprechenden ACL-Feed.
In diesem Snippet wird beispielsweise die erste Website im Websitefeed des Nutzers abgerufen und der ACL-Feed abgefragt:
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 ACLs für die Freigabe sind möglicherweise nur möglich, wenn die Domain so konfiguriert ist, dass solche Berechtigungen zulässig sind (z. B. wenn die Freigabe außerhalb der Domain für G Suite-Domains aktiviert ist).
Wenn Sie eine Google-Website über die API freigeben möchten, erstellen Sie eine gdata.sites.gdata.AclEntry mit den gewünschten Werten für gdata.acl.data.AclScope und gdata.acl.data.AclRole. Im Abschnitt ACL-Feed – Übersicht finden Sie die möglichen Werte für AclScope und AclRoles.
In diesem Beispiel werden dem Nutzer „nutzer@beispiel.de“ Leseberechtigungen für die 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 beim Freigeben 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.
Beim Teilen mit einer Gruppen-E-Mail-Adresse geschieht Folgendes:
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, auf der die Website gehostet wird. Beispiel: Unter http://sites.google.com/a/domain1.com/siteA kann die gesamte Website nur für domain1.com freigegeben werden, nicht für domain2.com. Bei Websites, die nicht auf einer G Suite-Domain gehostet werden (z. B. http://sites.google.com/site/siteB), können keine Domains eingeladen werden.
Freigabeberechtigungen ändern
Wenn Sie eine vorhandene Freigabeberechtigung für eine Website ändern möchten, müssen Sie zuerst die entsprechende AclEntry abrufen, die Berechtigung nach Bedarf ändern und dann die Update()-Methode des Clients aufrufen, um die ACL auf dem Server zu ändern.
In diesem Beispiel wird unsere vorherige acl_entry aus dem Abschnitt Website teilen geändert, indem „user@beispiel.de“ zum Mitbearbeiter (Bearbeiter) aktualisiert wird:
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 entfernen
Wenn du eine Freigabeberechtigung entfernen möchtest, musst du zuerst die AclEntry abrufen und dann die Delete()-Methode des Clients aufrufen.
client.Delete(acl_entry)
Sie können auch die Delete()-Methode des edit-Links des ACL-Eintrags ü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.
Besondere Themen
Feed oder Eintrag noch einmal abrufen
Wenn Sie einen Feed oder Eintrag abrufen möchten, den Sie schon einmal abgerufen haben, können Sie die Effizienz verbessern, indem Sie dem Server mitteilen, dass er die Liste oder den Eintrag nur senden soll, wenn er sich seit dem letzten Abruf geändert hat.
Wenn Sie eine solche bedingte Abfrage ausführen möchten, geben Sie einen ETag-Wert an GetEntry() weiter. Angenommen, Sie haben bereits ein entry-Objekt:
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 gdata.client.NotModified-Ausnahme auslöst, stimmt das ETag des Eintrags mit der Version auf dem Server überein. Sie haben also die aktuellste Kopie.
Wenn jedoch ein anderer Client/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.