In diesem Leitfaden werden die primären Anfrage- und Antwortmethoden der Google Docs API vorgestellt. Außerdem erfahren Sie, wie Sie ein Dokument stapelweise aktualisieren können.
Sie können die Google Docs API über eine HTTP-Anfrage oder einen Methodenaufruf in einer sprachspezifischen Clientbibliothek aufrufen. Beides sind weitgehend gleichwertig.
Die Google Docs API gibt eine HTTP-Antwort zurück, die in der Regel das Ergebnis des Anfrageaufrufs enthält. Wenn Sie für Anfragen eine Clientbibliothek verwenden, werden die Antworten sprachspezifisch zurückgegeben.
Anfragemethoden
Die Docs API unterstützt die folgenden Methoden:
documents.create: Hiermit 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: Sendet eine Liste von Bearbeitungsanfragen, die in kleinstmöglichen Schritten auf das Dokument angewendet werden sollen, und geben eine Liste der Ergebnisse zurück.
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 dem Sie den documentId lesen können. Weitere Informationen zu documentId finden Sie unter Dokument-ID.
Batch-Updates
Die Methode documents.batchUpdate verwendet eine Liste von request-Objekten, von denen jedes eine einzelne auszuführende Anfrage angibt. Formatieren Sie z. B. einen Absatz und
fügen Sie dann ein Inline-Bild hinzu. Jede Anfrage wird überprüft, bevor sie angewendet wird, und die Anfragen werden in der Reihenfolge verarbeitet, in der sie in der Batchanfrage erscheinen.
Alle Anfragen in der Batch-Aktualisierung werden in kleinstmöglichen Schritten angewendet. Wenn also eine Anfrage ungültig ist, schlägt die gesamte Aktualisierung fehl und keine der (potenziell abhängigen) Änderungen wird angewendet.
Einige documents.batchUpdate-Methoden liefern Antworten mit Informationen zu den angewendeten Anfragen. Bei diesen Methoden wird ein Antworttext mit einer Liste von response-Objekten zurückgegeben. Bei anderen Anfragen müssen keine Informationen zurückgegeben und eine leere Antwort zurückgegeben werden. Die Objekte in der Antwortliste haben die gleiche Indexreihenfolge wie die entsprechende Anfrage.
Ein beliebtes Muster für Batchanfragen sieht so aus:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
In den Best Practices für Batchanfragen finden Sie ausführliche Informationen zur Batchverarbeitung Ihrer Docs API-Aufrufe. Informationen zu Anfrage- und Antworttypen finden Sie in der documents.batchUpdate-Referenzdokumentation.
Batch-Update-Vorgänge
Es gibt verschiedene Arten von Batch-Aktualisierungsanfragen. Im Folgenden finden Sie eine Aufschlüsselung der Anfragetypen in verschiedene Kategorien.