Les commentaires sont des remarques fournies par les utilisateurs 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, tel qu'une phrase dans un document de traitement de texte, au sein d'une version spécifique d'un document. À l'inverse, un commentaire non ancré est simplement associé au document.
Les réponses sont associées à des commentaires et représentent la réponse d'un utilisateur à un commentaire. L'API 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.
Pour toutes les méthodes (à l'exception de delete
) sur la ressource comments
, vous devez définir le paramètre système fields
pour spécifier les champs à renvoyer dans la réponse. Dans la plupart des méthodes 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, la méthode renvoie une erreur. Pour en savoir plus, consultez 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é en texte brut, mais le corps de la réponse fournit un champ htmlContent
contenant du contenu mis en forme pour l'affichage.
Répondre à 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 l'affichage.
La méthode renvoie les champs listés dans le champ fields
.
Requête
Dans cet exemple, nous fournissons les paramètres de chemin d'accès 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
Pour résoudre un commentaire, vous devez y répondre.
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 marque la ressource de commentaire 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, votre UI doit indiquer que le commentaire a été traité. Par exemple, votre application peut :
- Interdire d'autres réponses et atténuer toutes les réponses précédentes ainsi que le commentaire initial.
- Masquez les commentaires résolus.
Requête
Dans cet exemple, nous fournissons les paramètres de chemin d'accès 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. Une ancre définit la révision et la région d'un fichier auxquelles un commentaire fait référence. La ressource comments
définit le champ anchor
comme une chaîne JSON.
Pour ajouter un commentaire ancré :
(Facultatif) Appelez la méthode
revisions.list
pour lister tous lesrevisionID
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, utilisezhead
pourrevisionID
.Appelez la méthode
create
avec le paramètrefileID
, une ressourcecomments
contenant le commentaire et une chaîne d'ancrage JSON contenant lerevisionID
(r
) et la région (a
).
La manière dont vous définissez une région dépend du type de contenu de document avec lequel vous travaillez. Pour en savoir plus, consultez Définir une région.
Définir une région
Comme mentionné 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 qui spécifient 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 qui correspond au type de contenu auquel vous essayez d'ancrer l'annonce. 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 Classificateurs de région.
L'exemple suivant montre une chaîne d'ancrage JSON qui ancre des commentaires à 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.
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
.
Requête
Dans cet exemple, nous fournissons les paramètres de chemin d'accès 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
Lister 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éfinissez la valeur surtrue
pour inclure les commentaires supprimés. Les commentaires supprimés n'incluent pas les champshtmlContent
nicontent
.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 champmodifiedTime
pour les commentaires sur les résultats.
Requête
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 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.
Le champ booléen resolved
de la ressource comments
est en lecture seule. Un commentaire ne peut être résolu qu'en y répondant. Pour en savoir plus, consultez Résoudre un commentaire.
La méthode renvoie les champs listés dans le paramètre de requête fields
.
Requête
Dans cet exemple, nous fournissons les paramètres de chemin d'accès 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 marque la ressource de commentaire comme deleted: true
. Les commentaires supprimés n'incluent pas les champs htmlContent
ni content
.
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