Kommentare und Antworten verwalten

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

Antworten sind 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 mit Ihrer App erstellt wurden. Ein Kommentar mit Antworten wird als Diskussion bezeichnet.

Parameter „fields“ verwenden

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

Einschränkungen für Kommentare

Bei der Verwendung von verankerten und nicht verankerten Kommentaren mit der Drive API gelten die folgenden Einschränkungen:

Kommentartyp	Dateityp
Verankert	Entwickler können ein eigenes Format für die Ankerspezifikation definieren. Der Anker wird gespeichert und beim Abrufen des Kommentars zurückgegeben. In den Google Workspace-Editor-Apps werden diese Kommentare jedoch als nicht verankerte Kommentare behandelt.
Nicht verankert	Wird in Google Workspace-Dokumenten unterstützt, in denen sie in der Ansicht „Alle Kommentare“ angezeigt werden. Nicht verankerte Kommentare werden nicht in PDFs angezeigt, die in der Drive-Dateivorschau gerendert werden. Sie werden jedoch gespeichert und können über die Drive API abgerufen werden.

Verankerten Kommentar zur neuesten Überarbeitung eines Dokuments hinzufügen

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

Wichtig:Anker sind unveränderlich und ihre Position relativ zum Inhalt eines Dokuments kann zwischen Überarbeitungen nicht garantiert werden. Wir empfehlen, Anker in Dokumenten zu verwenden, in denen sich die Position nicht ändert, z. B. in Bilddateien oder schreibgeschützten Dokumenten.

So fügen Sie einen verankerten Kommentar hinzu:

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

2. Rufen Sie die create Methode für die comments Ressource mit dem fileID Parameter, einer comments Ressource mit dem Kommentar und einem JSON-Anker string mit der revisionID (r) und der Region (a) auf.

Das folgende Codebeispiel zeigt, wie ein verankerter Kommentar erstellt wird:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

Die Drive API gibt eine Instanz des Ressourcenobjekts comments zurück, die den String anchor enthält.

Hinweis: Wir empfehlen, zu prüfen, ob ein Nutzer die richtigen 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 in einer anderen Rolle als der Ersteller versucht, einen Kommentar zu löschen oder zu bearbeiten. Prüfen Sie das author.me Feld der Ressource „comments“, um diese Fehler zu vermeiden.

Nicht verankerten Kommentar hinzufügen

Wenn Sie einen nicht verankerten Kommentar hinzufügen möchten, rufen Sie die create Methode mit dem fileId Parameter und einer comments Ressource mit dem Kommentar auf.

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

Das folgende Codebeispiel zeigt, wie ein nicht verankerter Kommentar erstellt wird:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

Wichtig: Wir empfehlen, zu prüfen, ob ein Nutzer die richtigen 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 in einer anderen Rolle als der Ersteller versucht, einen Kommentar zu löschen oder zu bearbeiten. Prüfen Sie das author.me Feld von der comments Ressource, um diese Fehler zu vermeiden. So können Sie prüfen, ob der Nutzer, der die Anfrage stellt, der Autor des Kommentars ist, und dann seine Berechtigungen für den Kommentar überprüfen.

Antwort auf einen Kommentar hinzufügen

Wenn Sie eine Antwort auf einen Kommentar hinzufügen möchten, verwenden Sie die create Methode für die replies Ressource mit den fileId und commentId Parametern. Im Anfragetext wird das Feld content verwendet, um die Antwort hinzuzufügen.

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

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

Anfrage

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

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 geklärt werden, indem Sie eine Antwort darauf posten.

Wenn Sie einen Kommentar als geklärt kennzeichnen möchten, verwenden Sie die create Methode für die replies Ressource mit den fileId und commentId Parametern.

Im Anfragetext wird das action Feld verwendet, um den Kommentar als geklärt zu kennzeichnen. Sie können auch das Feld content festlegen, um eine Antwort hinzuzufügen, mit der der Kommentar geschlossen wird.

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

Wenn Ihre App einen Kommentar als geklärt kennzeichnet, sollte in der Benutzeroberfläche angezeigt werden, dass der Kommentar bearbeitet wurde. Beispielsweise kann Ihre App:

• Weitere Antworten nicht zulassen und alle vorherigen Antworten sowie den ursprünglichen Kommentar ausblenden.
• Geklärte Kommentare ausblenden.

Anfrage

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

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

Kommentar abrufen

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

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

Wenn Sie gelöschte Kommentare in die Ergebnisse einbeziehen möchten, legen Sie den includedDeleted Abfrage parameter auf true fest.

Anfrage

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

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 list Methode für die comments Ressource mit dem fileId Parameter. Die Methode gibt eine Liste von Kommentaren zurück.

Übergeben Sie die folgenden Suchparameter, 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 Ergebniskommentare.

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 update Methode für die comments Ressource mit den fileId und commentId Parametern. Im Anfragetext wird das Feld content verwendet, um den Kommentar zu aktualisieren.

Das boolesche resolved Feld für die comments Ressource ist schreibgeschützt. Ein Kommentar kann nur geklärt werden, indem Sie eine Antwort darauf posten. Weitere Informationen finden Sie unter Kommentar als geklärt kennzeichnen.

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

Anfrage

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

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 delete Methode für die comments Ressource mit den fileId und commentId Parametern.

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

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

Weitere Informationen

• Übersicht über Dateien und Ordner
• Dateiüberarbeitungen verwalten