Les commentaires sont des commentaires fournis par l'utilisateur sur un fichier, comme un lecteur d'un document de traitement de texte suggérant comment 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, 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. L'API Drive permet à vos utilisateurs d'ajouter des commentaires et des réponses aux documents créés par votre application. Ensemble, un commentaire avec des réponses est appelé discussion.
Ajouter un commentaire non ancré
Pour ajouter un commentaire non ancré à un document, appelez la méthode comments.create
avec le paramètre fileId
et une ressource comments
contenant le commentaire.
Le commentaire est inséré en tant que texte brut, mais le corps de la réponse fournit un champ htmlContent
contenant du contenu mis en forme pour l'affichage.
Ajouter une réponse à un commentaire
Pour ajouter une réponse à un commentaire, appelez la méthode replies.create
avec le commentaire, le paramètre fileId
et une ressource replies
contenant la réponse.
La réponse est insérée en texte brut, mais le corps de la réponse fournit un champ htmlContent
contenant du contenu mis en forme pour l'affichage.
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 auquel 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 répertorier tous lesrevisionID
d'un document. Ne suivez cette étape que si vous souhaitez ancrer un commentaire sur une révision autre que la dernière révision. Si vous souhaitez utiliser la dernière révision, indiquezhead
pourrevisionID
.Appelez la méthode
comments.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 que vous utilisez. Pour en savoir plus, consultez Définir une région.
Définir une région
Comme indiqué précédemment, la chaîne d'ancrage JSON contient une 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 correspondant au type de contenu auquel vous essayez d'ancrer votre ancrage. Par exemple, si votre contenu est du texte, vous utiliserez probablement le classificateur de régions txt
ou line
.
Pour obtenir la liste des classificateurs de régions 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 l'ID d'une révision spécifique.
Fermer un commentaire
Utilisez la méthode comment.update
pour définir la propriété resolved
de la ressource comments
sur true
lorsqu'un commentaire a été résolu.
Lorsque votre application définit la propriété resolved
sur true
, l'interface utilisateur doit indiquer que le commentaire a été résolu. Par exemple, votre application peut:
- Interdire les réponses supplémentaires et réduire la luminosité de toutes les réponses précédentes ainsi que du commentaire d'origine
- Masquer les commentaires fermés.
Supprimer un commentaire
Utilisez la méthode comments.delete
pour supprimer des commentaires. Lorsqu'un commentaire est supprimé, Drive marque la ressource de commentaire comme "deleted": "true"
.
Répertorier les commentaires
Utilisez la méthode comments.list
pour répertorier les commentaires. Si vous souhaitez inclure des commentaires supprimés dans les résultats, définissez le champ includedDeleted
sur true
.