Gérer les commentaires et les réponses

Les commentaires sont des commentaires fournis par l'utilisateur sur un fichier. Par exemple, un lecteur d'un document de traitement de texte peut suggérer de reformuler 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, comme une phrase dans un document de traitement de texte, dans une version spécifique d'un document. À l'inverse, un commentaire non ancré n'est associé qu'au document.

Remarque :Pour les fichiers blob, l'API Google Drive n'accepte que les commentaires non ancrés. Les commentaires ancrés sur des fichiers blob ou des fichiers de l'éditeur Google Docs ne sont pas acceptés.

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

Le paramètre fields doit être défini pour lister les champs à renvoyer dans la réponse lorsque vous appelez chaque méthode listée dans la ressource comments. Si vous omettez le paramètre, la méthode renvoie une erreur. Pour renvoyer les champs exacts dont vous avez besoin, consultez la section Renvoyer des champs spécifiques.

Ajouter un commentaire non ancré

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

Le commentaire est inséré 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.

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 le supprimer ou le modifier. Des erreurs se produisent lorsqu'un utilisateur disposant d'un rôle autre que celui de créateur tente de supprimer ou de modifier un commentaire. Pour éviter ces erreurs, vérifiez le champ author.me de la ressource comments pour vous assurer que l'utilisateur à l'origine de 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 méthode replies.create() sur la ressource replies avec les paramètres fileId et commentId. 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 être affiché.

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

Afficher un exemple

Requête

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

Vous ne pouvez résoudre un commentaire qu'en y répondant.

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

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

Lorsqu'un commentaire est résolu, Drive le marque comme resolved: true. Contrairement aux commentaires supprimés, les commentaires résolus peuvent inclure les champs htmlContent ou content.

Lorsque votre application résout un commentaire, l'UI doit indiquer qu'il a été traité. Par exemple, votre application peut:

• Interdiction de toute nouvelle réponse et atténuation de toutes les réponses précédentes, ainsi que du commentaire d'origine.
• Masquer les commentaires fermés.

Afficher un exemple

Requête

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

Ajouter un commentaire ancré à la dernière révision d'un document

Lorsque vous ajoutez un commentaire, vous pouvez l'ancrer à une région du fichier. Un ancrage définit la révision et la région d'un fichier auxquels un commentaire fait référence. La ressource comments définit le champ anchor en tant que chaîne JSON.

Remarque :Pour les fichiers blob, l'API Drive n'accepte que les commentaires non ancrés. Les commentaires ancrés sur des fichiers blob ou des fichiers de l'éditeur Google Docs ne sont pas acceptés.

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.

Pour ajouter un commentaire ancré:

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

2. Appelez la méthode create() avec le paramètre fileID, une ressource comments contenant le commentaire et une chaîne d'ancrage JSON contenant les revisionID (r) et la région (a).

La manière dont vous définissez une région dépend du type de contenu du document avec lequel vous travaillez. Pour en savoir plus, consultez la section Définir une région.

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 le supprimer ou le modifier. Des erreurs se produisent lorsqu'une personne qui n'est pas créatrice tente de supprimer ou de modifier un commentaire. Pour éviter ces erreurs, vérifiez le champ author.me de la ressource comments.

Définir une région

Comme indiqué précédemment, la chaîne d'ancrage JSON contient un revisionID (r) et une région (a). La région (a) est un tableau JSON contenant des classificateurs de région spécifiant le format et l'emplacement auxquels un commentaire est ancré. Un classificateur peut être un rectangle bidimensionnel pour une image, une ligne de texte dans un document ou une durée dans une vidéo. Pour définir une région, sélectionnez le classificateur de région correspondant au type de contenu que vous essayez d'ancrer. Par exemple, si votre contenu est du texte, vous utiliserez probablement le classificateur de région txt ou line.

Pour obtenir la liste des classificateurs de région dans l'API Drive, consultez la section Classificateurs de région.

L'exemple suivant montre une chaîne d'ancrage JSON qui ancre des commentaires sur des lignes dans deux zones distinctes d'un document:

• La première zone commence à la ligne 12 ('n':12) et s'étend sur trois lignes ('l':3).
• La deuxième zone ne couvre que la ligne 18 ('n':18, 'l':1`).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Remplacez REVISION_ID par head ou par l'ID d'une révision spécifique.

Important :Si votre application permet aux utilisateurs de mettre à jour et de partager plusieurs versions d'un document, les commentaires sur les versions plus anciennes peuvent ne plus s'appliquer à l'emplacement ancré. Par conséquent, vous devez indiquer clairement dans votre UI à quelle révision chaque commentaire appartient.

Obtenir un commentaire

Pour obtenir un commentaire sur un fichier, utilisez la méthode get() sur la ressource comments avec les paramètres fileId et commentId. 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 paramètre de requête includedDeleted sur true.

Afficher un exemple

Requête

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 méthode list() sur la ressource comments avec le paramètre fileId. 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éfini 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 sur les résultats.

Afficher un exemple

Requête

Dans cet exemple, nous fournissons le paramètre de chemin 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 mettre à jour un commentaire sur un fichier, utilisez la méthode update() sur la ressource comments avec les paramètres fileId et commentId. Le corps de la requête utilise le champ content pour mettre à jour le commentaire.

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

Afficher un exemple

Requête

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 méthode delete() sur la ressource comments avec les paramètres fileId et commentId.

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

Afficher un exemple

Requête

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

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