Gérer les commentaires et les réponses

Les commentaires sont des avis fournis par les utilisateurs sur un fichier. Par exemple, un lecteur d'un document de traitement de texte peut suggérer une autre formulation pour une phrase. Il existe deux types de commentaires : les commentaires ancrés et les commentaires non ancrés. Un commentaire ancré est associé à un emplacement spécifique, par exemple une phrase dans un document de traitement de texte, dans une version spécifique d'un document. À l'inverse, un commentaire non ancré est simplement associé au document.

Les réponses sont associées aux commentaires et représentent la réponse d'un utilisateur au commentaire. L'API Google Drive permet à vos utilisateurs d'ajouter des commentaires et des réponses aux documents créés par votre application. Un commentaire et ses réponses sont appelés discussion.

Utiliser le paramètre "fields"

Pour toutes les méthodes (à l'exception de delete) sur la comments ressource, vous devez définir le fields paramètre système pour spécifier les champs à renvoyer dans la réponse. Dans la plupart des méthodes de ressource Drive, cette action n'est requise que pour renvoyer des champs non définis par défaut, mais elle est obligatoire pour la ressource comments. Si vous omettez le paramètre fields, la méthode renvoie une erreur. Pour en savoir plus, consultez la section Renvoyer des champs spécifiques.

Contraintes liées aux commentaires

Les contraintes suivantes sont appliquées lorsque vous utilisez des commentaires ancrés et non ancrés avec l'API Drive :

Type de commentaire	Type de fichier
Ancré	Les développeurs peuvent définir leur propre format pour la spécification de l'ancre. L'ancre est enregistrée et renvoyée lors de la récupération du commentaire, mais les applications d'édition Google Workspace traitent ces commentaires comme des commentaires non ancrés. Lorsque vous récupérez des commentaires sur des fichiers Google Workspace (tels que Google Docs, Google Sheets ou Google Slides) créés dans l'éditeur, le champ anchor contient des données d'ancrage internes spécifiques à l'éditeur (par exemple, une chaîne JSON workbook-range dans les fichiers Sheets). L'API Drive traite ces données comme opaques et ne peut pas résoudre les régions internes du document, les coordonnées de cellule ni les éléments de diapositive. Pour utiliser directement des commentaires ancrés sur ces types de fichiers, utilisez leurs API respectives : API Google Docs, API Google Sheets, ou API Google Slides.
Non ancré	Compatible avec les documents Google Workspace, qui les affichent dans la "Tous les commentaires" view. Les commentaires non ancrés ne s'affichent pas dans les PDF rendus dans l' aperçu de fichier Drive, mais ils sont enregistrés et peuvent être récupérés via l'API Drive.

Ajouter un commentaire ancré

Lorsque vous ajoutez un commentaire, vous pouvez l'ancrer à une région du fichier. Une ancre définit une région d'un fichier à laquelle un commentaire fait référence. La ressource comments définit le champ anchor comme une chaîne JSON.

Important : Les ancres sont immuables, et leur position par rapport au contenu d’ un document ne peut pas être garantie entre les révisions. Nous vous recommandons d'utiliser des ancres dans les documents dont la position ne change pas, tels que les fichiers image ou les documents en lecture seule. De plus, les applications d'édition Google Workspace (telles que Docs, Sheets et Slides) ne rendent pas les commentaires créés avec l'API Drive ancrés au contenu. Elles les traitent comme des commentaires non ancrés. Pour utiliser directement des commentaires ancrés dans ces types de fichiers, utilisez l'API Docs, l'API Sheets ou l'API Slides.

Pour ajouter un commentaire ancré :

1. (Facultatif) Appelez la list méthode sur la ressource revisions pour lister chaque revisionID d'un document. Ne suivez cette étape que si vous souhaitez ancrer un commentaire à une révision autre que la dernière. Si vous souhaitez utiliser la dernière révision, utilisez head pour revisionID.

2. Appelez la méthode create sur la ressource comments avec le paramètre fileId , une ressource comments contenant le commentaire et une chaîne d'ancrage JSON définie par votre application.

L'exemple de code suivant montre comment créer un commentaire ancré :

Python

import json

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
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 in your application to anchor the comment to.
# Note: Google Workspace editor apps (such as Google Docs, Sheets, and
# Slides) treat comments created using the Drive API as unanchored
# comments. Custom anchors are intended for your own applications or
# custom file viewers.
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 with a custom application-defined anchor.

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

        # Define a custom anchor specification for your application.
        # The Drive API stores the anchor as an opaque string. Your custom
        # application or file viewer can parse this JSON string to position
        # the comment in your UI.
        anchor_data = {
            'line': ANCHOR_LINE,
            'revision': 'head'
        }

        # The comment body. The 'anchor' field must be a serialized
        # JSON string.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': json.dumps(anchor_data)
        }

        # 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()

L'API Drive renvoie une instance de l'objet de ressource comments, qui inclut la chaîne anchor.

Remarque : Nous vous recommandons de vérifier qu'un utilisateur dispose des autorisations appropriées pour ajouter des commentaires. De plus, seul le créateur d'un commentaire ou d'une réponse peut supprimer ou modifier un commentaire ou une réponse. Des erreurs se produisent lorsqu'une personne qui n'est pas le créateur tente de supprimer ou de modifier un commentaire. Pour éviter ces erreurs, vérifiez le author.me champ de la comments ressource.

Ajouter un commentaire non ancré

Pour ajouter un commentaire non ancré, appelez la create méthode avec le fileId paramètre et une comments ressource contenant le commentaire.

Le commentaire est inséré sous forme de texte brut, mais le corps de la réponse fournit un htmlContent champ contenant du contenu mis en forme pour l'affichage.

L'exemple de code suivant montre comment créer un commentaire non ancré :

Python

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
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 file in Drive.

    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()

Important : Nous vous recommandons de vérifier qu'un utilisateur dispose des autorisations appropriées pour ajouter des commentaires. De plus, seul le créateur d'un commentaire ou d'une réponse peut supprimer ou modifier un commentaire ou une réponse. Des erreurs se produisent lorsqu'un utilisateur qui n'est pas le créateur tente de supprimer ou de modifier un commentaire. Pour éviter ces erreurs, vérifiez le author.me champ de la comments ressource pour vous assurer que l'utilisateur qui effectue la requête est l'auteur du commentaire, puis vérifiez ses autorisations par rapport au commentaire.

Ajouter une réponse à un commentaire

Pour ajouter une réponse à un commentaire, utilisez la create méthode sur la replies ressource avec les fileId et commentId paramètres. Le corps de la requête utilise le champ content pour ajouter la réponse.

La réponse est insérée sous forme de texte brut, mais le corps de la réponse fournit un champ htmlContent contenant du contenu mis en forme pour l'affichage.

La méthode renvoie les champs listés dans le champ fields.

Demande

Dans cet exemple, nous fournissons les paramètres de chemin fileId et commentId, ainsi que plusieurs champs.

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

Corps de la requête

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

Fermer un commentaire

Un commentaire ne peut être fermé qu'en publiant une réponse à celui-ci.

Pour fermer un commentaire, utilisez la create méthode sur la ressource replies avec les paramètres fileId et commentId.

Le corps de la requête utilise le action champ pour fermer le commentaire. Vous pouvez également définir le champ content pour ajouter une réponse qui ferme le commentaire.

Lorsqu'un commentaire est fermé, Drive marque la ressource comments comme resolved: true. Contrairement aux commentaires supprimés, les commentaires fermés peuvent inclure les champs htmlContent ou content.

Lorsque votre application ferme un commentaire, son interface utilisateur doit indiquer que le commentaire a été traité. Par exemple, votre application peut :

• Interdire d'autres réponses et estomper toutes les réponses précédentes, ainsi que le commentaire d'origine.
• Masquer les commentaires fermés.

Demande

Dans cet exemple, nous fournissons les paramètres de chemin fileId et commentId, ainsi que plusieurs champs.

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

Corps de la requête

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

Obtenir un commentaire

Pour obtenir un commentaire sur un fichier, utilisez la get méthode sur la comments ressource avec les fileId et commentId paramètres. Si vous ne connaissez pas l'ID du commentaire, vous pouvez lister tous les commentaires à l'aide de la méthode list.

La méthode renvoie une instance d'une ressource comments.

Pour inclure les commentaires supprimés dans les résultats, définissez le includeDeleted paramètre de requête sur true.

Demande

Dans cet exemple, nous fournissons les paramètres de chemin fileId et commentId, ainsi que plusieurs champs.

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

Répertorier les commentaires

Pour lister les commentaires sur un fichier, utilisez la list méthode sur la ressource comments avec le fileId paramètre. La méthode renvoie une liste de commentaires.

Transmettez les paramètres de requête suivants pour personnaliser la pagination ou filtrer les commentaires :

• includeDeleted : définissez la valeur sur true pour inclure les commentaires supprimés. Les commentaires supprimés n'incluent pas les champs htmlContent ni content.

• pageSize : nombre maximal de commentaires à renvoyer par page.

• pageToken : jeton de page reçu d'un appel de liste précédent. Fournissez ce jeton pour récupérer la page suivante.

• startModifiedTime: valeur minimale du champ modifiedTime pour les commentaires de résultat.

Demande

Dans cet exemple, nous fournissons le paramètre de chemin d'accès fileId, le paramètre de requête includeDeleted et plusieurs champs.

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

Modifier un commentaire

Pour modifier un commentaire sur un fichier, utilisez la update méthode sur la comments ressource avec les fileId et commentId paramètres. Le corps de la requête utilise le champ content pour modifier le commentaire.

Le champ booléen resolved du ressource comments est en lecture seule. Un commentaire ne peut être fermé qu'en publiant une réponse à celui-ci. Pour en savoir plus, consultez la section Fermer un commentaire.

La méthode renvoie les champs listés dans le paramètre de requête fields.

Demande

Dans cet exemple, nous fournissons les paramètres de chemin fileId et commentId, ainsi que plusieurs champs.

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

Corps de la requête

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

Supprimer un commentaire

Pour supprimer un commentaire sur un fichier, utilisez la delete méthode sur la comments ressource avec les fileId et commentId paramètres.

Lorsqu'un commentaire est supprimé, Drive marque la ressource de commentaire comme deleted: true. Les commentaires supprimés n'incluent pas les champs htmlContent ni content.

Demande

Dans cet exemple, nous fournissons les paramètres de chemin fileId et commentId.

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

Articles associés

• Présentation des fichiers et des dossiers
• Gérer les révisions de fichiers
• API Google Docs : utiliser des commentaires et des suggestions
• API Google Sheets : gérer les commentaires
• API Google Slides : gérer les commentaires