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.

Sie müssen den Parameter fields festlegen, um die Felder aufzulisten, die in der Antwort zurückgegeben werden sollen, wenn Sie alle in der Ressource comments aufgeführten Methoden aufrufen. Wenn Sie den Parameter weglassen, gibt die Methode einen Fehler zurück. Wie Sie genau die benötigten Felder zurückgeben, erfahren Sie unter Bestimmte Felder zurückgeben.

Kommentar ohne Anker hinzufügen

Wenn Sie einem Dokument einen losgelösten Kommentar hinzufügen möchten, rufen Sie die Methode 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 richtigen Berechtigungen hat, um Kommentare hinzuzufügen. 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 Ressource comments, 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, verwende die Methode replies.create() für die Ressource replies mit den Parametern fileId und commentId. Im Anfragetext wird die Antwort über das Feld content hinzugefügt.

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

Die Methode gibt die im Feld fields aufgeführten Felder zurück.

Beispiel ansehen

Anfrage

In diesem Beispiel werden die Pfadparameter fileId und commentId sowie mehrere Felder angegeben.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Anfragetext

{
  "content": "This is a reply to a comment."
}

Kommentar klären

Ein Kommentar kann nur durch das Posten einer Antwort auf einen Kommentar geschlossen werden.

Verwenden Sie die Methode replies.create() für die Ressource replies mit den Parametern fileId und commentId, um einen Kommentar zu schließen.

Im Anfragetext wird das Feld action verwendet, um den Kommentar zu verarbeiten. Sie können auch das Feld content so einstellen, dass eine Antwort hinzugefügt wird, die den Kommentar schließt.

Wenn ein Kommentar geklärt wurde, wird die Kommentarressource in Google Drive als resolved: true markiert. Im Gegensatz zu gelöschten Kommentaren können in den Feldern htmlContent oder content von geklärten Kommentaren Werte enthalten sein.

Wenn Ihre App einen Kommentar behebt, sollte die Benutzeroberfläche darauf hinweisen, dass der Kommentar bearbeitet wurde. Beispiele:

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

Beispiel ansehen

Anfrage

In diesem Beispiel werden die Pfadparameter fileId und commentId sowie mehrere Felder angegeben.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Anfragetext

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

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 die Region in einer Datei, auf die 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 angepinnten 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 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. Prüfe das Feld author.me der comments-Ressource, um diese Fehler zu vermeiden.

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, beziehen sich Kommentare zu älteren Versionen möglicherweise nicht mehr auf die angedockte Stelle. Daher müssen Sie in Ihrer Benutzeroberfläche klar angeben, zu welcher Version jeder Kommentar gehört.

Kommentar abrufen

Wenn Sie einen Kommentar zu einer Datei abrufen möchten, verwenden Sie die Methode get() für die Ressource comments mit den Parametern fileId und commentId. Wenn du die Kommentar-ID nicht kennst, kannst du mit der Methode list() alle Kommentare auflisten.

Die Methode gibt eine Instanz einer comments-Ressource zurück.

Wenn gelöschte Kommentare in den Ergebnissen berücksichtigt werden sollen, setzen Sie den Abfrageparameter includedDeleted auf true.

Beispiel ansehen

Anfrage

In diesem Beispiel werden die Pfadparameter fileId und commentId sowie mehrere Felder angegeben.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Kommentare auflisten

Wenn Sie Kommentare zu einer Datei auflisten möchten, verwenden Sie die Methode list() für die Ressource comments mit dem Parameter fileId. Die Methode gibt eine Liste von Kommentaren zurück.

Mit den folgenden Abfrageparametern kannst du die Paginierung von Kommentaren anpassen oder sie filtern:

• includeDeleted: Legen Sie true fest, um gelöschte Kommentare einzubeziehen. Gelöschte Kommentare enthalten keine Felder vom Typ htmlContent oder content.

• pageSize: Die maximale Anzahl von Kommentaren, die pro Seite zurückgegeben werden sollen.

• pageToken: Ein Seitentoken, das von einem vorherigen Listenaufruf empfangen wurde. Geben Sie dieses Token an, um die nachfolgende Seite abzurufen.

• startModifiedTime: Der Mindestwert des Felds modifiedTime für die Ergebniskommentare.

Beispiel ansehen

Anfrage

In diesem Beispiel geben wir den Pfadparameter fileId, den Abfrageparameter includeDeleted und mehrere Felder an.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Kommentar aktualisieren

Wenn Sie einen Kommentar zu einer Datei aktualisieren möchten, verwenden Sie die Methode update() für die Ressource comments mit den Parametern fileId und commentId. Im Anfragetext wird das Feld content verwendet, um den Kommentar zu aktualisieren.

Die Methode gibt die im Abfrageparameter fields aufgeführten Felder zurück.

Beispiel ansehen

Anfrage

In diesem Beispiel werden die Pfadparameter fileId und commentId sowie mehrere Felder angegeben.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

Anfragetext

{
  "content": "This comment is now updated."
}

Kommentare löschen

Wenn Sie einen Kommentar zu einer Datei löschen möchten, verwenden Sie die Methode delete() für die Ressource comments mit den Parametern fileId und commentId.

Wenn ein Kommentar gelöscht wird, wird die Kommentarressource in Google Drive als deleted: true markiert. Gelöschte Kommentare enthalten die Felder htmlContent oder content nicht.

Beispiel ansehen

Anfrage

In diesem Beispiel geben wir die Pfadparameter fileId und commentId an.

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID