Gérer les commentaires et les réponses

Les commentaires sont des commentaires envoyés par les utilisateurs sur un fichier, par exemple document de traitement de texte suggérant comment reformuler une phrase. Il y a deux types de commentaires: commentaires ancrés et commentaires non ancrés. Une vue ancrée le commentaire est associé à un lieu spécifique, comme une phrase dans une document de traitement de texte, dans une version spécifique d'un document. À l'inverse, un commentaire non ancré est simplement associé au document.

Remarque :Pour les fichiers blob, l'API Google Drive n'accepte que les commentaires non ancrés. Les commentaires ancrés sur les fichiers blob ou 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 Drive permet à vos utilisateurs d'ajouter des commentaires et des réponses les documents créés par votre application. Collectivement, un commentaire contenant des réponses est appelé une 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 une Champ htmlContent avec du contenu mis en forme pour être affiché.

Important :Nous vous recommandons de vérifier qu'un utilisateur dispose des autorisations appropriées pour ajouter commentaires. De plus, seul l'auteur d'un commentaire ou d'une réponse peut supprimer ou modifier une un commentaire ou une réponse. Des erreurs se produisent lorsqu'un utilisateur sans rôle de créateur tente de supprimer ou 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 demande est l'auteur du commentaire, puis vérifiez autorisations relatives au commentaire.

Ajouter une réponse à un commentaire

Pour répondre à 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 une Champ htmlContent avec du contenu mis en forme pour être affiché.

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 dans un fichier auquel un commentaire renvoie. La ressource comments définit anchor sous forme de chaîne JSON.

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

Important :Les ancres sont immuables et leur position par rapport au contenu des un document ne peut pas être garanti entre les révisions. Nous vous recommandons d'utiliser des ancres dans les documents dont la position ne change pas, comme les fichiers image ou les fichiers en lecture seule documents.

Pour ajouter un commentaire ancré:

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

2. Appelez la méthode comments.create. avec le paramètre fileID, un élément comments ressource contenant le commentaire, ainsi qu'une chaîne d'ancrage JSON contenant le paramètre 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 sur lequel vous travaillez . Pour en savoir plus, consultez Définir une région.

Remarque :Nous vous recommandons de vérifier qu'un utilisateur dispose des autorisations appropriées pour ajouter commentaires. De plus, seul l'auteur d'un commentaire ou d'une réponse peut supprimer ou modifier une un commentaire ou une réponse. Des erreurs se produisent lorsqu'une personne qui n'est pas un créateur tente de supprimer ou 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 élément revisionID (r) et (a). La région (a) est un tableau JSON contenant des classificateurs de région spécifiant le format et l'emplacement d'ancrage d'un commentaire. Un classificateur peut être un rectangle en deux dimensions pour une image, une ligne de texte dans un document, ou la durée d'une vidéo. Pour définir une région, sélectionnez la région classificateur correspondant au type de contenu auquel vous essayez de vous ancrer. Pour Par exemple, si votre contenu est du texte, vous utiliserez probablement la méthode txt ou le classificateur par région line.

Pour obtenir la liste des classificateurs par région dans l'API Drive, consultez Région classificateurs.

L'exemple suivant montre une chaîne d'ancrage JSON qui ancre les commentaires aux 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 du client.

Important :Si votre application permet aux utilisateurs de mettre à jour et de partager plusieurs révisions d'un les commentaires associés à d'anciennes révisions peuvent ne plus s'appliquer au texte ancré l'emplacement. Vous devez donc indiquer à quelle révision chaque commentaire appartient. clairement dans votre interface utilisateur.

Fermer un commentaire

Utilisez la méthode comment.update pour définir la propriété resolved dans comments ; vers true lorsqu'un commentaire a été traité.

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

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

Supprimer un commentaire

Utilisez la méthode comments.delete pour supprimer des commentaires. Lorsqu'un commentaire est supprimé, Drive le marque la ressource de commentaire en tant que "deleted": "true".

Lister les commentaires

Utilisez la méthode comments.list pour répertorier commentaires. Si vous souhaitez inclure les commentaires supprimés dans les résultats, définissez le paramètre le champ includedDeleted sur true.