In dieser Anleitung werden die primären Anfrage- und Antwortmethoden vorgestellt, aus denen die Google Docs API besteht. Außerdem erfahren Sie, wie Sie ein Dokument stapelweise aktualisieren können.
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 im Allgemeinen das Ergebnis des Anfrageaufrufs enthält. Wenn Sie eine Clientbibliothek für Anfragen verwenden, werden die Antworten in einer sprachspezifischen Weise zurückgegeben.
Anfragemethoden
Die Docs API unterstützt die folgenden Methoden:
documents.create: Erstellen Sie ein leeres Google Docs-Dokument.documents.get: Gibt eine vollständige Instanz des angegebenen Dokuments zurück. 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.
Die Methoden documents.get und documents.batchUpdate erfordern einen documentId als Parameter, 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 Antworttext mit einer Liste von response-Objekten zurück. Andere Anfragen müssen keine Informationen zurückgeben und eine leere Antwort zurückgeben. Die Objekte in der Antwortliste belegen die gleiche 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.