Kommentare und Antworten verwalten

Kommentare sind Feedback von Nutzern zu einer Datei, z. B. von einem Leser eines Textverarbeitungsdokuments, das vorschlägt, einen Satz umzuformulieren. Es gibt zwei Arten von Kommentaren: verankerte Kommentare und nicht verankerte Kommentare. Ein verankerter Kommentar ist einer bestimmten Stelle in einer bestimmten Version eines Dokuments zugeordnet, z. B. einem Satz in einem Textverarbeitungsdokument. Umgekehrt wird ein nicht verankerter Kommentar nur mit dem Dokument verknüpft.

Hinweis :Bei Blob-Dateien unterstützt die Google Drive API nur Kommentare ohne verankerte Elemente. verankerte Kommentare in Blob-Dateien oder Dateien im Google Docs-Editor werden nicht unterstützt.

Antworten werden an Kommentare angehängt und stellen die Antwort eines Nutzers auf den Kommentar dar. Mit der Drive API können Nutzer Kommentare und Antworten zu Dokumenten hinzufügen, die von der App erstellt wurden. Ein Kommentar mit Antworten wird zusammen als Diskussion bezeichnet.

Unverankerten Kommentar hinzufügen

Wenn Sie einem Dokument einen nicht verankerten Kommentar hinzufügen möchten, rufen Sie die Methode comments.create mit dem Parameter fileId und einer comments-Ressource auf, die den Kommentar enthält.

Der Kommentar wird als Nur-Text eingefügt, aber der Antworttext enthält ein htmlContent-Feld mit für die Anzeige formatierten Inhalten.

Wichtig :Wir empfehlen Ihnen, zu prüfen, ob ein Nutzer die erforderlichen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem kann nur der Ersteller eines Kommentars oder einer Antwort einen Kommentar oder eine Antwort löschen oder bearbeiten. Fehler treten auf, wenn ein Nutzer mit der Rolle „Nicht-Ersteller“ versucht, einen Kommentar zu löschen oder zu bearbeiten. Um diese Fehler zu vermeiden, prüfen Sie im Feld author.me der Ressource Kommentare, ob der Nutzer, der die Anfrage stellt, der Autor des Kommentars ist. Prüfen Sie dann seine Berechtigungen im Verhältnis zum Kommentar.

Antwort zu Kommentar hinzufügen

Wenn Sie eine Antwort zu einem Kommentar hinzufügen möchten, rufen Sie die Methode replies.create mit dem Kommentar, dem Parameter fileId und einer replies-Ressource auf, die die Antwort enthält.

Die Antwort wird als Nur-Text eingefügt, der Antworttext enthält jedoch ein htmlContent-Feld mit für die Anzeige formatierten Inhalten.

Der letzten Version eines Dokuments einen verankerten Kommentar hinzufügen

Wenn Sie einen Kommentar hinzufügen, können Sie ihn in einem Bereich in der Datei verankern. Ein Anker definiert die Dateiversion und den Bereich in einer Datei, auf die sich ein Kommentar bezieht. Die Ressource comments definiert das Feld anchor als JSON-String.

Hinweis :Bei Blob-Dateien unterstützt die Drive API nur Kommentare ohne Anker. Verankerte Kommentare in Blob-Dateien oder Dateien im Google Docs-Editor werden nicht unterstützt.

Wichtig: Anker sind unveränderlich und ihre Position relativ zum Inhalt eines Dokuments kann zwischen Versionen nicht garantiert werden. Wir empfehlen die Verwendung von Ankern in Dokumenten, bei denen sich die Position nicht ändert, wie z. B. in Bilddateien oder schreibgeschützten Dokumenten.

So fügen Sie einen verankerten Kommentar hinzu:

1. Optional: Rufen Sie die Methode revisions.list auf, um alle revisionID für ein Dokument aufzulisten. Führen Sie diesen Schritt nur aus, wenn Sie einen Kommentar mit einer anderen Überarbeitung als der letzten verankern möchten. Wenn Sie die neueste Version verwenden möchten, nutzen Sie head für revisionID.

2. Rufen Sie die Methode comments.create mit dem Parameter fileID, einer comments-Ressource, die den Kommentar enthält, und einem JSON-Ankerstring mit dem revisionID (r) und der Region (a) auf.

Wie Sie eine Region definieren, hängt von der Art des Dokumentinhalts ab, mit dem Sie arbeiten. Weitere Informationen finden Sie unter Region definieren.

Hinweis :Wir empfehlen, zu prüfen, ob ein Nutzer die erforderlichen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem kann nur der Ersteller eines Kommentars oder einer Antwort einen Kommentar oder eine Antwort löschen oder bearbeiten. Fehler treten auf, wenn eine Person mit der Rolle „Nicht-Ersteller“ versucht, einen Kommentar zu löschen oder zu bearbeiten. Prüfen Sie das Feld author.me der Ressource comments, um diese Fehler zu vermeiden.

Region definieren

Wie bereits erwähnt, enthält der JSON-Ankerstring einen revisionID (r) und eine Region (a). Die Region (a) ist ein JSON-Array mit Regionsklassifikatoren, die das Format und den Ort angeben, an dem ein Kommentar verankert ist. Ein Klassifikator kann ein zweidimensionales Rechteck für ein Bild, eine Textzeile in einem Dokument oder eine Zeitdauer in einem Video sein. Um eine Region zu definieren, wählen Sie den Regionenklassifikator aus, der dem Inhaltstyp entspricht, mit dem Sie eine Verankerung vornehmen möchten. Wenn Ihr Inhalt beispielsweise Text ist, verwenden Sie wahrscheinlich den Regionsklassifikator txt oder line.

Eine Liste der Regionsklassifikatoren in der Drive API finden Sie unter Regionsklassifikatoren.

Das folgende Beispiel zeigt einen JSON-Ankerstring, mit dem Kommentare an Zeilen in zwei separaten Bereichen eines Dokuments verankert werden:

• Der erste Bereich beginnt bei Zeile 12 ('n':12) und erstreckt sich über drei Linien ('l':3).
• Der zweite Bereich umfasst nur Zeile 18 ('n':18, 'l':1).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Ersetzen Sie REVISION_ID durch head oder die ID einer bestimmten Überarbeitung.

Wichtig: Wenn Nutzer in Ihrer App mehrere Versionen eines Dokuments aktualisieren und freigeben können, gelten Kommentare zu älteren Überarbeitungen möglicherweise nicht mehr am verankerten Speicherort. Daher müssen Sie in Ihrer UI deutlich angeben, zu welcher Überarbeitung jeder Kommentar gehört.

Kommentar klären

Verwenden Sie die Methode comment.update, um das Attribut resolved in der Ressource comments auf true festzulegen, wenn ein Kommentar bearbeitet wurde.

Wenn in Ihrer App die Eigenschaft resolved auf true gesetzt wird, sollte in der UI angezeigt werden, dass der Kommentar berücksichtigt wurde. Ihre Anwendung könnte beispielsweise:

• Keine weiteren Antworten zulassen und alle vorherigen Antworten sowie den ursprünglichen Kommentar schwärzen.
• Geklärte Kommentare ausblenden.

Kommentare löschen

Verwenden Sie die Methode comments.delete, um Kommentare zu löschen. Wird ein Kommentar gelöscht, markiert Google Drive die Kommentarressource als "deleted": "true".

Kommentare auflisten

Verwenden Sie die Methode comments.list, um Kommentare aufzulisten. Wenn gelöschte Kommentare in die Ergebnisse aufgenommen werden sollen, legen Sie das Feld includedDeleted auf true fest.