Kommentare und Antworten verwalten

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

Hinweis :Die Drive API unterstützt nur Kommentare auf Dateiebene zu Blob-Dateien. Verankerte Kommentare in Blob-Dateien oder Dateien aus Google Docs-Editoren werden nicht unterstützt.

Antworten werden an Kommentare angehängt und stellen die Antwort eines Nutzers auf den Kommentar dar. Mit der Google Drive API können Nutzer Kommentare und Antworten zu Dokumenten hinzufügen, die von Ihrer Anwendung erstellt wurden. Zusammen wird ein Kommentar mit Antworten 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, das für die Anzeige formatierten Inhalt enthält.

Wichtig: Wir empfehlen Ihnen, zu prüfen, ob ein Nutzer die erforderlichen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem kann nur der Verfasser eines Kommentars oder einer Antwort einen Kommentar oder eine Antwort löschen oder bearbeiten. Fehler treten auf, wenn ein Nutzer ohne die Rolle „Nicht-Ersteller“ versucht, einen Kommentar zu löschen oder zu bearbeiten. Prüfen Sie zur Vermeidung dieser Fehler das Feld author.me der Ressource comments. Achten Sie darauf, dass der Nutzer, der die Anfrage stellt, der Autor des Kommentars ist. Prüfen Sie dann seine Berechtigungen zum Kommentar.

Antwort zu Kommentar hinzufügen

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

Die Antwort wird im Nur-Text-Format eingefügt, aber der Antworttext enthält ein htmlContent-Feld, das für die Anzeige formatierten Inhalt enthält.

Einen verankerten Kommentar zur letzten Überarbeitung eines Dokuments hinzufügen

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

Hinweis :Die Drive API unterstützt nur Kommentare auf Dateiebene zu Blob-Dateien. Verankerte Kommentare in Blob-Dateien oder Dateien aus Google Docs-Editoren werden nicht unterstützt.

Wichtig: Anker sind unveränderlich und ihre Position im Verhältnis zum Inhalt eines Dokuments kann nicht zwischen Überarbeitungen garantiert werden. Wir empfehlen die Verwendung von Ankern in Dokumenten, in denen sich die Position nicht ändert, z. B. in Bilddateien oder in 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, verwenden 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 auf, der revisionID (r) und Region (a) enthält.

Wie Sie eine Region definieren, hängt vom Typ des Dokumentinhalts ab, mit dem Sie arbeiten. Weitere Informationen finden Sie unten im Abschnitt 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 Verfasser 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 eine 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, eine Zeitdauer in einem Video usw. sein. Wenn Sie eine Region definieren möchten, wählen Sie den Regionsklassifikator aus, der dem Inhaltstyp entspricht, in dem Sie verankern 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, der Kommentare in Zeilen in zwei separaten Bereichen eines Dokuments verankert:

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

    {
      '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 Anwendung mehrere Überarbeitungen eines Dokuments aktualisieren und freigeben können, gelten Kommentare zu älteren Überarbeitungen möglicherweise nicht mehr für den verankerten Speicherort. Daher müssen Sie in der UI eindeutig 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 der Anwendung das Attribut resolved auf true festgelegt wird, sollte in der UI angezeigt werden, dass der Kommentar bearbeitet 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. Wenn ein Kommentar gelöscht wird, markiert 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.