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, z. B. einem Satz in einem Textverarbeitungsdokument, in einer bestimmten Version eines Dokuments zugeordnet. 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.

Parameter „fields“ verwenden

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. Bei den meisten Drive-Ressourcenmethoden 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 fields weglassen, gibt die Methode einen Fehler zurück. Weitere Informationen finden Sie unter Bestimmte Felder zurückgeben.

Einschränkungen bei Kommentaren

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

Kommentartyp	Dateityp
Verankert	Entwickler können ihr eigenes Format für die Ankerspezifikation definieren. Der Anker wird gespeichert und zurückgegeben, wenn der Kommentar abgerufen wird. Google Workspace-Editor-Apps behandeln diese Kommentare jedoch als nicht verankerte Kommentare.
Nicht verankert	Wird in Google Workspace-Dokumenten unterstützt und in der Ansicht „Alle Kommentare“ angezeigt. 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 Version eines Dokuments hinzufügen

Wenn Sie einen Kommentar hinzufügen, möchten Sie ihn vielleicht an einen Bereich in der Datei anhängen. Mit einem Anker wird ein Bereich in einer Datei definiert, auf den sich ein Kommentar bezieht. In der Ressource comments wird das Feld anchor als JSON-String definiert.

Wichtig :Anker sind unveränderlich und ihre Position relativ zum Inhalt eines Dokuments kann zwischen Revisionen 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ügst du einen angepinnten Kommentar hinzu:

1. Optional: Rufen Sie die Methode list für die Ressource revisions 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, geben Sie head für revisionID ein.

2. Rufen Sie die Methode create für die Ressource comments mit dem Parameter fileID, einer comments-Ressource mit dem Kommentar und einem JSON-Ankerstring mit revisionID (r) und 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 comments-Ressourcenobjekts zurück, das den anchor-String enthält.

Hinweis :Wir empfehlen, dass Sie prüfen, ob ein Nutzer die richtigen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem können nur der Ersteller eines Kommentars oder einer Antwort einen Kommentar oder eine Antwort löschen oder bearbeiten. Fehler treten auf, wenn eine Person mit einer Rolle, die nicht die Rolle „Creator“ ist, versucht, einen Kommentar zu löschen oder zu bearbeiten. Prüfen Sie das Feld author.me 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 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 das Feld htmlContent mit für die Anzeige formatiertem Inhalt.

Das folgende Codebeispiel zeigt, wie Sie einen nicht verankerten Kommentar erstellen:

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 Ihnen, zu prüfen, ob ein Nutzer die richtigen Berechtigungen zum Hinzufügen von Kommentaren hat. Außerdem können nur der Ersteller eines Kommentars oder einer Antwort einen Kommentar oder eine Antwort löschen oder bearbeiten. Fehler treten auf, wenn ein Nutzer mit einer Rolle, die nicht die Rolle „Creator“ ist, versucht, einen Kommentar zu löschen oder zu bearbeiten. Um diese Fehler zu vermeiden, prüfen Sie das Feld author.me der Ressource comments, um sicherzustellen, dass der Nutzer, der die Anfrage stellt, der Autor des Kommentars ist. Prüfen Sie dann seine Berechtigungen in Bezug auf den Kommentar.

Auf Kommentare antworten

Verwenden Sie die Methode 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.

Ersuchen

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 zum Schließen eines Kommentars die Methode create für die Ressource replies mit den Parametern fileId und commentId.

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, wird die comments-Ressource in Drive als resolved: true markiert. 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.

Ersuchen

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

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 mit der Methode list alle Kommentare 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.

Ersuchen

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.

Ersuchen

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 durch eine Antwort auf den Kommentar geschlossen werden. Weitere Informationen finden Sie unter Kommentar bearbeiten.

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

Ersuchen

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.

Ersuchen

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