In diesem Leitfaden werden die wichtigsten Anfrage- und Antwortmethoden der Google Docs API vorgestellt. Außerdem erfahren Sie, wie Sie ein Dokument im Batchmodus aktualisieren.
Sie können die Google Docs API über eine HTTP-Anfrage oder über eine Methodenaufruf in einer sprachspezifischen Clientbibliothek aufrufen. Sie sind im Großen und Ganzen gleichwertig.
Die Google Docs API gibt eine HTTP-Antwort zurück, die in der Regel das Ergebnis der Aufrufanfrage enthält. Wenn Sie Anfragen mit einer Clientbibliothek stellen, werden die Antworten sprachspezifisch zurückgegeben.
Anfragemethoden
Die Docs API unterstützt die folgenden Methoden:
documents.create: Erstellen Sie ein leeres Google Docs-Dokument.documents.get: Eine vollständige Instanz des angegebenen Dokuments wird zurückgegeben. Sie können die zurückgegebene JSON-Datei parsen, um den Dokumentinhalt, die Formatierung und andere Funktionen zu extrahieren.documents.batchUpdate: Eine Liste von Bearbeitungsanfragen einreichen, die atomar auf das Dokument angewendet werden sollen, und eine Liste der Ergebnisse zurückgeben.
Für die Methoden documents.get und documents.batchUpdate ist ein documentId als 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.
Batch-Updates
Die Methode documents.batchUpdate nimmt eine Liste von request-Objekten entgegen, 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 in der Batchaktualisierung werden in kleinstmöglichen Schritten angewendet. Wenn eine Anfrage also ungültig ist, schlägt das gesamte Update fehl und keine der (potenziell abhängigen) Änderungen wird angewendet.
Einige documents.batchUpdate-Methoden enthalten in den Antworten Informationen zu den angewandten Anfragen. Diese Methoden geben einen Antwortkörper zurück, der eine Liste von response-Objekten enthält. Andere Anfragen müssen keine Informationen zurückgeben und eine leere Antwort zurückgeben. 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 Ausführen von Docs API-Aufrufen im Batch finden Sie unter Best Practices für Batchanfragen. In der Referenzdokumentation zu documents.batchUpdate finden Sie Informationen zu Anfrage- und Antworttypen.
Batch-Aktualisierungsvorgänge
Es gibt verschiedene Arten von Batch-Aktualisierungsanfragen. Im Folgenden finden Sie eine Aufschlüsselung der Anfragetypen, die in verschiedene Kategorien unterteilt sind.