In diesem Leitfaden werden die wichtigsten Anfrage- und Antwortmethoden der Google Docs API vorgestellt und erläutert, wie Sie ein Dokument im Batchmodus 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 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.
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. Versuche, die neue documentId der URL mit der documents.get-Methode zu verwenden, führen zu einer HTTP-Statuscode-Antwort von 404. Es gibt keine Methoden, die ursprüngliche documentId über die veröffentlichte URL abzurufen. Sie können dieses Problem umgehen, indem Sie mit der Drive API das veröffentlichte Dokument in ein freigegebenes Dokument kopieren und dann stattdessen auf diese Datei zugreifen. Weitere Informationen finden Sie im Hilfeartikel Google-Dokumente, ‑Tabellen, ‑Präsentationen und ‑Formulare veröffentlichen.
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)
Unter Best Practices für Batchanfragen finden Sie ausführliche Informationen zum Batchen von Docs API-Aufrufen. In der Referenzdokumentation für 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.
Weitere Informationen
- Struktur eines Google Docs-Dokuments
- Regeln und Verhalten bei strukturellen Änderungen
- Batchanfragen