Kommentare und Antworten verwalten

Kommentare sind von Nutzern bereitgestelltes Feedback zu einer Datei. Ein Leser eines Textverarbeitungsdokuments könnte beispielsweise vorschlagen, wie ein Satz umformuliert werden könnte. Es gibt zwei Arten von Kommentaren: angedockte Kommentare und nicht angedockte Kommentare. Ein verankerter Kommentar ist mit einem bestimmten Ort in einer bestimmten Version eines Dokuments verknüpft, z. B. mit einem Satz in einem Textverarbeitungsdokument. Ein nicht verankerter Kommentar ist dagegen nur mit dem Dokument verknüpft.

Hinweis: Bei Blob-Dateien unterstützt die Google Drive API nur losgelöste Kommentare. Angedockte Kommentare in Blob-Dateien oder Google Docs-Editordateien werden nicht unterstützt.

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

Kommentar ohne Anker hinzufügen

Wenn Sie einem Dokument einen losgelösten 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 Feld htmlContent mit für die Anzeige formatierten Inhalten.

Wichtig :Prüfen Sie, ob ein Nutzer die erforderlichen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem kann nur der Verfasser eines Kommentars oder einer Antwort diesen löschen oder bearbeiten. Fehler treten auf, wenn ein Nutzer ohne Creator-Rolle versucht, einen Kommentar zu löschen oder zu bearbeiten. Um diese Fehler zu vermeiden, prüfen Sie im Feld author.me der Kommentare-Ressource, ob der Nutzer, der die Anfrage stellt, der Autor des Kommentars ist. Prüfen Sie dann seine Berechtigungen für den Kommentar.

Auf einen Kommentar antworten

Wenn du auf einen Kommentar antworten möchtest, rufe 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-Format eingefügt, aber der Antworttext enthält das Feld htmlContent mit für die Anzeige formatiertem Inhalt.

Der neuesten Version eines Dokuments einen verankerten Kommentar hinzufügen

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

Hinweis: Bei Blob-Dateien unterstützt die Drive API nur losgelöste Kommentare. Angedockte Kommentare in Blob-Dateien oder Google Docs-Editordateien werden nicht unterstützt.

Wichtig: Anker sind unveränderlich und ihre Position im Verhältnis zum Inhalt eines Dokuments kann zwischen den Überarbeitungen nicht garantiert werden. Wir empfehlen, Anker in Dokumenten zu verwenden, deren Position sich nicht ändert, z. B. in Bilddateien oder nur-Lese-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 an eine andere Version als die neueste Version anhängen möchten. Wenn Sie die neueste Version verwenden möchten, geben Sie head für revisionID ein.

2. Rufe die Methode comments.create mit dem Parameter fileID, einer comments-Ressource mit dem Kommentar und einem JSON-Ankerstring mit revisionID (r) und Region (a) auf.

Wie Sie eine Region definieren, hängt davon ab, mit welcher Art von Dokumentinhalten Sie arbeiten. Weitere Informationen finden Sie unter Region definieren.

Hinweis: Prüfen Sie, ob ein Nutzer die richtigen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem kann nur der Verfasser eines Kommentars oder einer Antwort diesen löschen oder bearbeiten. Fehler treten auf, wenn eine Person ohne Creator-Rolle versucht, einen Kommentar zu löschen oder zu bearbeiten. Um diese Fehler zu vermeiden, prüfen Sie das Feld author.me der Kommentare-Ressource.

Region definieren

Wie bereits erwähnt, enthält der JSON-Ankersting ein revisionID (r) und eine Region (a). Die Region (a) ist ein JSON-Array mit Regionenklassifikatoren, die das Format und den Speicherort angeben, an dem ein Kommentar verankert ist. Ein Klassifikator kann ein zweidimensionales Rechteck für ein Bild, eine Textzeile in einem Dokument oder eine Zeitspanne in einem Video sein. Wählen Sie zum Definieren einer Region den Regionenklassifikator aus, der dem Inhaltstyp entspricht, an dem Sie die Karte verankern möchten. Wenn Ihre Inhalte beispielsweise Text sind, verwenden Sie wahrscheinlich den Region-Klassifikator txt oder line.

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

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

• Der erste Bereich beginnt in 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 Version.

Wichtig :Wenn Nutzer in Ihrer App mehrere Versionen eines Dokuments aktualisieren und freigeben können, gelten Kommentare zu älteren Versionen möglicherweise nicht mehr für die angedockte Stelle. Daher müssen Sie in Ihrer Benutzeroberfläche klar angeben, zu welcher Version jeder Kommentar gehört.

Kommentar klären

Verwenden Sie die Methode comment.update, um die Property resolved in der Ressource comments auf true zu setzen, wenn ein Kommentar beantwortet wurde.

Wenn in Ihrer App die Property resolved auf true festgelegt ist, sollte in der Benutzeroberfläche angezeigt werden, dass der Kommentar berücksichtigt wurde. Beispiele:

• Weitere Antworten werden nicht mehr zugelassen und alle bisherigen Antworten sowie der ursprüngliche Kommentar werden ausgeblendet.
• Geklärte Kommentare ausblenden.

Kommentare löschen

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

Kommentare auflisten

Verwenden Sie die Methode comments.list, um Kommentare aufzulisten. Wenn gelöschte Kommentare in den Ergebnissen enthalten sein sollen, legen Sie das Feld includedDeleted auf true fest.