In dieser Anleitung werden die wichtigsten Anfrage- und Antwortmethoden der Google Docs API sowie die Batch-Aktualisierung von Dokumenten vorgestellt.
Sie können die Google Docs API über eine HTTP-Anfrage oder durch einen Methoden aufruf in einer sprachspezifischen Client bibliothek aufrufen. Beide Methoden sind im Wesentlichen gleichwertig.
Die Google Docs API gibt eine HTTP-Antwort zurück, die in der Regel das Ergebnis des Methodenaufrufs enthält. Wenn Sie Anfragen mit einer Clientbibliothek senden, werden die Antworten in einer sprachspezifischen Weise zurückgegeben.
Anfragemethoden
Die Docs API unterstützt die folgenden Methoden:
documents.create: Erstellt ein leeres Google-Dokument.documents.get: Gibt eine vollständige Instanz des angegebenen Dokuments zurück. Sie können das zurückgegebene JSON parsen, um den Dokumentinhalt, die Formatierung und andere Funktionen zu extrahieren.documents.batchUpdate: Sendet eine Liste von Bearbeitungsanfragen, die atomar auf das Dokument angewendet werden sollen, und gibt eine Liste von Ergebnissen zurück.
Für die Methoden documents.get und documents.batchUpdate ist ein documentId-Parameter erforderlich, um das Zieldokument anzugeben. Die Methode documents.create gibt eine Instanz des erstellten Dokuments zurück, aus der Sie die documentId lesen können. Weitere Informationen zu documentId finden Sie unter Dokument
ID.
Veröffentlichte Dokumente
Sie können die Methode documents.get nicht verwenden, um veröffentlichte Dokumente abzurufen. Nach der Veröffentlichung verwenden öffentliche Dokumente ein anderes URL-Format mit einer eindeutigen, öffentlichen documentId. Wenn Sie versuchen, die öffentliche documentId mit der Methode documents.get zu verwenden, wird eine Antwort mit dem HTTP-Statuscode 404 zurückgegeben.
Ebenso können Sie die Drive API
files.copy-Methode nicht verwenden, um ein
veröffentlichtes Dokument zu kopieren.
Wenn Sie ein veröffentlichtes Dokument abrufen oder kopieren möchten, müssen Sie die ursprüngliche documentId verwenden. Es gibt keine Methoden, um die ursprüngliche documentId aus einer veröffentlichten URL zu extrahieren.
Weitere Informationen finden Sie unter:
- Google-Dokumente, ‑Tabellen, ‑Präsentationen und ‑Formulare veröffentlichen
- Vorhandenes Dokument kopieren
Batch-Aktualisierungen
Die
documents.batchUpdate
Methode verwendet eine Liste von
request Objekten,
die jeweils eine einzelne Anfrage angeben. Sie können beispielsweise einen Absatz formatieren und dann ein Inline-Bild hinzufügen. Jede Anfrage wird vor der Anwendung validiert und die Anfragen werden in der Reihenfolge verarbeitet, in der sie in der Batchanfrage erscheinen.
Alle Anfragen im Batch-Update werden atomar angewendet. Wenn eine Anfrage ungültig ist, schlägt die gesamte Aktualisierung fehl und keine der (potenziell abhängigen) Änderungen wird angewendet.
Einige documents.batchUpdate-Methoden geben Antworten mit Informationen zu den angewendeten Anfragen zurück. Diese Methoden geben einen Antwort
text
zurück, der eine Liste von
response-Objekten enthält.
Andere Anfragen müssen keine Informationen zurückgeben und geben eine leere Antwort zurück. Die Objekte in der Antwortliste haben dieselbe Indexreihenfolge wie die entsprechende Anfrage.
Ein gängiges Muster für Batchanfragen sieht so aus:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Ausführliche Informationen zum Batch-Verarbeiten von Docs API-Aufrufen finden Sie unter Best Practices für Batchanfragen. Die
documents.batchUpdate
Referenzdokumentation enthält Informationen zu Anfrage- und Antworttypen.
Batch-Updates
Es gibt verschiedene Arten von Batch-Aktualisierungsanfragen. Hier ist eine Aufschlüsselung der Anfragetypen, gruppiert in verschiedene Kategorien.