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: Erstellen Sie ein leeres Google-Dokument.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: Eine Liste von Bearbeitungsanfragen einreichen, die atomar auf das Dokument angewendet werden sollen, und eine Liste von Ergebnissen 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.
Veröffentlichte Dokumente
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 mit einem separaten, öffentlichen documentId. Versuche, die öffentliche documentId mit der Methode documents.get zu verwenden, geben eine Antwort mit dem HTTP-Statuscode 404 zurück.
Ebenso können Sie die Drive API-Methode files.copy nicht verwenden, um ein veröffentlichtes Dokument zu kopieren.
Wenn Sie ein veröffentlichtes Dokument abrufen oder kopieren möchten, müssen Sie die ursprüngliche documentId verwenden. Es gibt keine Methoden, um das Original-documentId aus einer veröffentlichten URL zu extrahieren.
Weitere Informationen finden Sie unter:
- Google-Dokumente, ‑Tabellen, ‑Präsentationen und ‑Formulare veröffentlichen
- Vorhandenes Dokument kopieren
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 und keine 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 nach Kategorien.