Gérer les commentaires et les réponses

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, 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 :L'API Drive n'accepte que les commentaires au niveau des fichiers blob. Les commentaires ancrés sur les fichiers blob ou dans les fichiers des éditeurs Google Docs ne sont pas acceptés.

Les réponses sont jointes 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. 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 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. En outre, seul le créateur d'un commentaire ou d'une réponse peut les supprimer ou les modifier. Des erreurs se produisent lorsqu'un utilisateur n'ayant pas le rôle de créateur tente de supprimer ou de modifier un commentaire. Pour éviter ces erreurs, vérifiez le champ author.me de la ressource Commentaires 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, appelez la méthode replies.create avec le commentaire, le paramètre fileId et une ressource reply 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 zone du fichier. Une ancre définit la révision et la région du fichier d'un fichier auxquels le commentaire fait référence. La ressource comments définit le champ anchor en tant que chaîne JSON.

Remarque :L'API Drive n'accepte que les commentaires au niveau des fichiers blob. Les commentaires ancrés sur les fichiers blob ou dans les fichiers des éditeurs Google Docs ne sont pas acceptés.

Important: Les ancrages 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 où la position ne change pas, comme les fichiers image ou les documents en lecture seule.

Pour ajouter un commentaire ancré:

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

2. Appelez la méthode comments.create avec le paramètre fileID, une ressource comments contenant le commentaire et une chaîne d'ancre JSON contenant le revisionID (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 ci-dessous.

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

Définir une région

Comme indiqué précédemment, la chaîne d'ancre 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 d'ancrage d'un commentaire. Un classificateur peut être un rectangle bidimensionnel pour une image, une ligne de texte dans un document, une durée dans une vidéo, etc. Pour définir une région, sélectionnez le classificateur de région correspondant au type de contenu auquel vous essayez d'ancrer l'appareil. Par exemple, si votre contenu est du texte, vous allez probablement utiliser le classificateur de régions txt ou line.

Pour obtenir une liste des classificateurs de région dans l'API Drive, consultez la page 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.

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

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é traité.

Lorsque votre application définit la propriété resolved sur true, l'interface utilisateur doit indiquer que le commentaire a été traité. Par exemple, votre application peut:

• Interdire les nouvelles réponses et assombrir toutes les réponses précédentes ainsi que le commentaire d'origine.
• Masquer les commentaires résolus.

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 les commentaires supprimés dans les résultats, définissez le champ includedDeleted sur true.