Dokument

In diesem Leitfaden werden Konzepte vorgestellt, zum Beispiel die primären Methoden, aus denen die Google Docs API, den Zugriff auf ein Dokument und den Workflow beim Erstellen eines Dokument.

API-Methoden

Die Ressource documents bietet Methoden, mit denen Sie die Docs API aufrufen können. Mit den folgenden Methoden können Sie Google Docs-Dokumente erstellen, lesen und aktualisieren:

  • Verwenden Sie den documents.create. zum Erstellen eines Dokuments.
  • Methode documents.get verwenden um den Inhalt eines bestimmten Dokuments abzurufen.
  • Verwenden Sie den documents.batchUpdate. , um eine Reihe von Aktualisierungen für ein bestimmtes Dokument untrennbar auszuführen.

Für die Methoden documents.get und documents.batchUpdate ist ein documentId erforderlich als Parameter zum Angeben des Zieldokuments an. Die Methode documents.create gibt eine Instanz des erstellten Dokuments zurück, aus der das documentId. Weitere Informationen zu Docs API-Anfragen und erhalten Sie unter Anfragen und Antworten.

Dokument-ID

Die documentId ist die eindeutige Kennung für das Dokument und kann abgeleitet werden. aus der URL eines Dokuments. Es ist ein bestimmter String, der Buchstaben, Zahlen und Sonderzeichen eingeben. Dokument-IDs bleiben unverändert, auch wenn der Dokumentname Änderungen.

https://docs.google.com/document/d/DOCUMENT_ID/edit

Mit dem folgenden regulären Ausdruck können Sie die documentId aus einem Google Docs-URL:

/document/d/([a-zA-Z0-9-_]+)

Wenn Sie mit der Google Drive API vertraut sind, entspricht die documentId der id in der Ressource files.

Dokumente in Google Drive verwalten

Docs-Dateien werden in Google Drive gespeichert, unserem cloudbasierten Speicher. Service. Obwohl die Docs API über eigene eigenständige Methoden verfügt, ist sie häufig Google Drive API-Methoden für die Interaktion mit dem Google Docs-Dateien. Verwenden Sie beispielsweise zum Kopieren von Google Docs-Dateien files.copy der Drive API . Weitere Informationen hierzu finden Sie unter Vorhandenes Dokument.

Wenn Sie die Docs API verwenden, wird ein neues Dokument standardmäßig im Stammordner des Nutzers in Drive. Es gibt verschiedene Möglichkeiten, eine Datei zu speichern in einen Drive-Ordner. Weitere Informationen finden Sie unter Arbeiten mit Google Drive-Ordner.

Mit Google Docs-Dateien arbeiten

Es ist oft schwierig, ein Dokument aus „Meine Ablage“ bevor Sie den Drive-Speicherplatz files.list-Methode zum Abrufen der ID für eine Datei. Beim Aufrufen der Methode ohne Parameter wird eine Liste aller Dateien und Ordner für den Nutzer, einschließlich der IDs.

Der MIME-Typ eines Dokuments gibt Datentyp und Format an. Das MIME-Typ-Format für Google Docs ist application/vnd.google-apps.document. Eine Liste mit Weitere Informationen zu unterstützten MIME-Typen in Google Workspace und Google Drive .

So suchen Sie anhand des MIME-Typs nur nach Google Docs-Dateien in meinem Drive und hängen Sie den folgenden Abfragestringfilter an:

q: mimeType = 'application/vnd.google-apps.document'

Weitere Informationen zu Abfragestringfiltern finden Sie unter Nach Dateien suchen und Ordner.

Wenn Sie die documentId kennen, verwenden Sie die Methode documents.get, um eine vollständige Instanz des angegebenen Dokuments abzurufen. Weitere Informationen finden Sie unter Anfragen und Antworten.

Um Byteinhalte von Google Workspace-Dokumenten zu exportieren, verwenden Sie die Drive-Funktion files.export-Methode mit dem documentId der zu exportierenden Datei und die korrekte Export-MIME-Nachricht . Weitere Informationen finden Sie unter Exportieren Google Workspace-Dokument Inhalte.

Die Methoden Get und List vergleichen

In der folgenden Tabelle werden die Unterschiede zwischen den Drive-Versionen und Docs-Methoden sowie die jeweils zurückgegebenen Daten:

Operator Beschreibung Nutzung
drive.files.get Ruft die Metadaten einer Datei nach ID ab. Gibt eine Instanz der files-Ressource zurück. Die Metadaten für eine bestimmte Datei abrufen.
drive.files.list Ruft die Dateien eines Nutzers ab. Gibt eine Liste von Dateien zurück. Wenn Sie nicht sicher sind, welche Datei Sie ändern müssen, können Sie eine Liste der Nutzerdateien abrufen.
docs.documents.get Ruft die neueste Version des angegebenen Dokuments ab, einschließlich aller Formatierungen und Text. Gibt eine Instanz der Ressource documents zurück. Das Dokument für eine bestimmte Dokument-ID abrufen.

Workflow für die Dokumenterstellung

Das Erstellen und Ausfüllen eines neuen Dokuments ist ganz einfach, und es gibt keine Mitbearbeiter, die den Inhalt ändern können. Dokumentstatus. Konzeptionell funktioniert das wie im folgenden Sequenzdiagramm dargestellt:

Workflow zum Erstellen und in ein neues Dokument einfügen.
Abbildung 1: Workflow zum Erstellen und Ausfüllen eines neuen Dokuments.

In Abbildung 1 sieht ein Nutzer, der mit dem Ressource documents enthält Folgendes: Informationsfluss:

  1. Eine App ruft die Funktion Methode documents.create aktiviert einen Webserver.
  2. Der Webserver sendet eine HTTP-Antwort, die eine Instanz des erstellten Dokuments als documents-Ressource enthält.
  3. Optional ruft die App die Funktion documents.batchUpdate auf -Methode, um eine Reihe von Bearbeitungsanfragen atomar auszuführen, um das Dokument zu füllen mit Daten.
  4. Der Webserver sendet eine HTTP-Antwort. Einige documents.batchUpdate-Methoden einen Antworttext mit Informationen zu den angewendeten Anfragen bereitstellen, während andere eine leere Antwort.

Workflow für die Aktualisierung von Dokumenten

Das Aktualisieren bestehender Dokumente ist komplexer. Bevor Sie sinnvolle aktualisiert wird, müssen Sie seinen aktuellen Status kennen: Welche Elemente welche Inhalte sich in diesen Elementen befinden und in welcher Reihenfolge des Dokuments. Das folgende Sequenzdiagramm zeigt, wie das funktioniert:

Workflow zum Aktualisieren eines Dokument.
Abbildung 2: Workflow zum Aktualisieren eines Dokuments.

In Abbildung 2 sehen Nutzer, die mit der Ressource documents interagieren, folgenden Informationsfluss:

  1. Eine App ruft die Funktion Methode documents.get in einem Web Server mit den documentId der zu suchenden Datei.
  2. Der Webserver sendet eine HTTP-Antwort mit einer Instanz des angegebenes Dokument als documents-Ressource. Der zurückgegebene JSON-Code enthält den Dokumentinhalt, Formatierung und andere Funktionen.
  3. Die Anwendung parst den JSON-Code, damit der Nutzer bestimmen kann, welcher Inhalt oder welches Format aktualisieren.
  4. Die App ruft die Methode documents.batchUpdate auf, um einen Satz in kleinstmöglichen Schritten auszuführen. von Bearbeitungsanfragen, um das Dokument zu aktualisieren.
  5. Der Webserver sendet eine HTTP-Antwort. Einige documents.batchUpdate-Methoden einen Antworttext mit Informationen zu den angewendeten Anfragen bereitstellen, während andere eine leere Antwort.

In diesem Diagramm werden keine Workflows berücksichtigt, bei denen gleichzeitige Updates durch andere im selben Dokument erstellt werden. Weitere Informationen findest du in den im Abschnitt Best Practices für Zusammenarbeit.