Kommentare und Antworten verwalten

Kommentare sind von Nutzern bereitgestelltes Feedback zu einer Datei, z. B. wenn ein Leser eines Textverarbeitungsdokuments vorschlägt, wie ein Satz umformuliert werden könnte. 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. Ein nicht verankerter Kommentar ist dagegen nur dem Dokument zugeordnet.

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

Für alle Methoden (außer delete) für die Ressource comments müssen Sie den fields-Systemparameter festlegen, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen. In den meisten Drive-Methoden ist diese Aktion nur erforderlich, um nicht standardmäßige Felder zurückzugeben. Für die comments-Ressource ist sie jedoch obligatorisch. Wenn Sie den Parameter weglassen, gibt die Methode einen Fehler zurück. Weitere Informationen finden Sie unter Bestimmte Felder zurückgeben.

Nicht verankerten Kommentar hinzufügen

Wenn Sie einem Dokument einen nicht verankerten 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 Inhalten, die für die Anzeige formatiert sind.

Auf einen Kommentar antworten

Verwenden Sie die Methode replies.create für die Ressource replies mit den Parametern fileId und commentId, um einem Kommentar eine Antwort hinzuzufügen. Im Anfragetext wird das Feld content verwendet, um die Antwort hinzuzufügen.

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

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

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 als geklärt kennzeichnen

Ein Kommentar kann nur durch eine Antwort auf einen Kommentar aufgelöst 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 schließen. Sie können auch das Feld content festlegen, um eine Antwort hinzuzufügen, mit der der Kommentar geschlossen wird.

Wenn ein Kommentar geklärt wird, markiert Drive die Kommentarressource als resolved: true. Im Gegensatz zu gelöschten Kommentaren können gelöste Kommentare die Felder htmlContent oder content enthalten.

Wenn Ihre App einen Kommentar auflöst, sollte in der Benutzeroberfläche angezeigt werden, dass der Kommentar bearbeitet wurde. Beispiele:

  • Weitere Antworten sind nicht zulässig und alle vorherigen Antworten sowie der ursprüngliche Kommentar werden ausgeblendet.
  • Geklärte Kommentare ausblenden.

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."
}

Verankerten Kommentar zur neuesten Version eines Dokuments hinzufügen

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

So fügst du 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 einer anderen als der neuesten Version verankern möchten. Wenn Sie die neueste Version verwenden möchten, verwenden Sie head für die revisionID.

  2. Rufen Sie 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 vom Typ der Dokumentinhalte ab, mit denen Sie arbeiten. Weitere Informationen finden Sie unter Region definieren.

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 Regionenklassifizierungen, die das Format und den Ort angeben, an dem ein Kommentar verankert ist. Ein Classifier kann ein zweidimensionales Rechteck für ein Bild, eine Textzeile in einem Dokument oder eine Zeitspanne in einem Video sein. Um eine Region zu definieren, wählen Sie die Regionenklassifizierung aus, die dem Typ des Inhalts entspricht, an den Sie die Verankerung vornehmen möchten. Wenn Ihre Inhalte beispielsweise Text sind, verwenden Sie wahrscheinlich entweder den Regionsklassifikator txt oder line.

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

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

  • Der erste Bereich beginnt in Zeile 12 ('n':12) und erstreckt sich über drei Zeilen ('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 Revision.

Kommentar erhalten

Verwenden Sie die Methode get für die Ressource comments mit den Parametern fileId und commentId, um einen Kommentar zu einer Datei abzurufen. Wenn Sie die Kommentar-ID nicht kennen, können Sie alle Kommentare mit der Methode list auflisten.

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

Wenn Sie gelöschte Kommentare in die Ergebnisse einbeziehen möchten, setzen Sie den Abfrageparameter includedDeleted auf true.

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

Verwenden Sie die Methode list für die Ressource comments mit dem Parameter fileId, um Kommentare zu einer Datei aufzulisten. Die Methode gibt eine Liste von Kommentaren zurück.

Übergeben Sie die folgenden Abfrageparameter, um die Paginierung von Kommentaren anzupassen oder Kommentare zu filtern:

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

  • pageSize: Die maximale Anzahl der Kommentare, 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 Ergebnisbemerkungen.

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

Verwenden Sie zum Aktualisieren eines Kommentars zu einer Datei 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.

Das boolesche Feld resolved in der Ressource comments ist schreibgeschützt. Ein Kommentar kann nur geklärt werden, indem Sie auf ihn antworten. Weitere Informationen finden Sie unter Kommentar auflösen.

Die Methode gibt die Felder zurück, die im Abfrageparameter fields aufgeführt sind.

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 Drive als deleted: true markiert. Gelöschte Kommentare enthalten die Felder htmlContent oder content nicht.

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