In dieser Anleitung werden die primären Anfrage- und Antwortmethoden der Google Docs API vorgestellt. Außerdem wird beschrieben, wie Sie ein Dokument in Batches aktualisieren können.
Sie können die Google Docs API über eine HTTP-Anfrage oder durch Aufrufen einer Methode in einer sprachspezifischen Clientbibliothek aufrufen. Diese sind im Wesentlichen gleichwertig.
Die Google Docs API gibt eine HTTP-Antwort zurück, die in der Regel das Ergebnis des Anfrageaufrufs enthält. Wenn Sie eine Clientbibliothek verwenden, um Anfragen zu stellen, werden die Antworten in einer sprachspezifischen Weise zurückgegeben.
Anfragemethoden
Die Docs API unterstützt die folgenden Methoden:
documents.create: Leeres Google-Dokument erstellen.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: Senden Sie eine Liste von Bearbeitungsanfragen, die atomar auf das Dokument angewendet werden sollen, und geben Sie eine Liste von Ergebnissen 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 der Sie die documentId lesen können. Weitere Informationen zu documentId finden Sie unter Dokument-ID.
Hinweis: Mit der Methode documents.get können keine veröffentlichten Dokumente abgerufen werden. Nach der Veröffentlichung verwenden öffentliche Dokumente ein anderes URL-Format. Versuche, die neue documentId der URL mit der documents.get-Methode zu verwenden, geben eine Antwort mit dem HTTP-Statuscode 404 zurück. Es gibt keine Möglichkeit, die Originaldatei documentId über die veröffentlichte URL abzurufen. Um dieses Problem zu umgehen, können Sie die Drive API verwenden, um das veröffentlichte Dokument in ein freigegebenes Dokument zu kopieren und dann auf diese Datei zuzugreifen. Weitere Informationen finden Sie unter Google-Dokumente, ‑Tabellen, ‑Präsentationen und ‑Formulare veröffentlichen.
Batch-Updates
Die Methode documents.batchUpdate verwendet eine Liste von request-Objekten, die jeweils eine einzelne auszuführende Anfrage angeben. Formatieren Sie beispielsweise einen Absatz und fügen Sie dann ein Inlinebild ein. 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 Batch-Aktualisierung werden in kleinstmöglichen Schritten angewendet. Wenn eine Anfrage ungültig ist, schlägt das gesamte Update fehl und keine der (möglicherweise abhängigen) Änderungen wird angewendet.
Einige documents.batchUpdate-Methoden liefern Antworten mit Informationen zu den angewendeten Anfragen. Diese Methoden geben einen Antworttext mit einer Liste von response-Objekten zurück.
Bei anderen Anfragen müssen keine Informationen zurückgegeben werden. Es kann eine leere Antwort angezeigt werden. Die Objekte in der Antwortliste haben denselben Index 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)
Best Practices für Batchanfragen enthält ausführliche Informationen zur Batchverarbeitung von Docs API-Aufrufen. In der documents.batchUpdate-Referenzdokumentation finden Sie Informationen zu Anfrage- und Antworttypen.
Batch-Aktualisierungsvorgänge
Es gibt verschiedene Arten von Batch-Aktualisierungsanfragen. Hier finden Sie eine Aufschlüsselung der Antragstypen, gruppiert in verschiedene Kategorien.