Gerenciar comentários e respostas

Os comentários são feedback fornecido pelo usuário em um arquivo, como um leitor de um documento de processamento de texto sugerindo como reformular uma frase. Há dois tipos de comentários: ancorados e não ancorados. Um comentário ancorado está associado a um local específico, como uma frase em um documento de processamento de texto, em uma versão específica de um documento. Por outro lado, um comentário não ancorado está associado apenas ao documento.

As respostas são anexadas aos comentários e representam a resposta de um usuário a eles. A API Drive permite que os usuários adicionem comentários e respostas a documentos criados pelo seu app. Um comentário com respostas é conhecido como uma discussão.

Para todos os métodos (exceto delete) no recurso comments, é obrigatório definir o parâmetro de sistema fields para especificar os campos a serem retornados na resposta. Na maioria dos métodos do Drive, essa ação só é necessária para retornar campos não padrão, mas é obrigatória para o recurso comments. Se você omitir o parâmetro, o método vai retornar um erro. Para mais informações, consulte Retornar campos específicos.

Adicionar um comentário sem âncora

Para adicionar um comentário não ancorado a um documento, chame o método create com o parâmetro fileId e um recurso comments que contenha o comentário.

O comentário é inserido como texto simples, mas o corpo da resposta fornece um campo htmlContent com conteúdo formatado para exibição.

Responder a um comentário

Para adicionar uma resposta a um comentário, use o método replies.create no recurso replies com os parâmetros fileId e commentId. O corpo da solicitação usa o campo content para adicionar a resposta.

A resposta é inserida como texto simples, mas o corpo da resposta fornece um campo htmlContent com conteúdo formatado para exibição.

O método retorna os campos listados no campo fields.

Solicitação

Neste exemplo, fornecemos os parâmetros de caminho fileId e commentId e vários campos.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Corpo da solicitação

{
  "content": "This is a reply to a comment."
}

Resolver um comentário

Um comentário só pode ser resolvido com uma resposta.

Para resolver um comentário, use o método replies.create no recurso replies com os parâmetros fileId e commentId.

O corpo da solicitação usa o campo action para resolver o comentário. Você também pode definir o campo content para adicionar uma resposta que encerra o comentário.

Quando um comentário é resolvido, o Drive marca o recurso como resolved: true. Ao contrário dos comentários excluídos, os comentários resolvidos podem incluir os campos htmlContent ou content.

Quando o app resolve um comentário, a interface precisa indicar que ele foi resolvido. Por exemplo, seu app pode:

  • Impedir mais respostas e diminuir a visibilidade de todas as respostas anteriores e do comentário original.
  • Ocultar comentários resolvidos.

Solicitação

Neste exemplo, fornecemos os parâmetros de caminho fileId e commentId e vários campos.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Corpo da solicitação

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

Adicionar um comentário fixo à revisão mais recente de um documento

Ao adicionar um comentário, talvez você queira ancorá-lo a uma região do arquivo. Uma âncora define a revisão e a região de um arquivo a que um comentário se refere. O recurso comments define o campo anchor como uma string JSON.

Para adicionar um comentário fixado:

  1. (Opcional). Chame o método revisions.list para listar todos os revisionID de um documento. Siga esta etapa apenas se quiser ancorar um comentário em uma revisão que não seja a mais recente. Se quiser usar a revisão mais recente, use head para o revisionID.

  2. Chame o método create com o parâmetro fileID, um recurso comments que contém o comentário e uma string de âncora JSON com o revisionID (r) e a região (a).

A definição de uma região depende do tipo de conteúdo do documento com que você está trabalhando. Para mais informações, consulte Definir uma região.

Definir uma região

Como mencionado anteriormente, a string âncora JSON contém um revisionID (r) e uma região (a). A região (a) é uma matriz JSON que contém classificadores de região que especificam o formato e o local em que um comentário está ancorado. Um classificador pode ser um retângulo bidimensional para uma imagem, uma linha de texto em um documento ou uma duração de tempo em um vídeo. Para definir uma região, selecione o classificador de região que corresponde ao tipo de conteúdo que você quer ancorar. Por exemplo, se o conteúdo for texto, provavelmente você vai usar o classificador de região txt ou line.

Para uma lista de classificadores de região na API Drive, consulte Classificadores de região.

O exemplo a seguir mostra uma string de âncora JSON que vincula comentários a linhas em duas áreas separadas de um documento:

  • A primeira área começa na linha 12 ('n':12) e se estende por três linhas ('l':3).
  • A segunda área abrange apenas a linha 18 ('n':18, 'l':1`).
    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Substitua REVISION_ID por head ou pelo ID de uma revisão específica.

Receber um comentário

Para receber um comentário em um arquivo, use o método get no recurso comments com os parâmetros fileId e commentId. Se você não souber o ID do comentário, liste todos os comentários usando o método list.

O método retorna uma instância de um recurso comments.

Para incluir comentários excluídos nos resultados, defina o parâmetro de consulta includedDeleted como true.

Solicitação

Neste exemplo, fornecemos os parâmetros de caminho fileId e commentId e vários campos.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Listar comentários

Para listar comentários em um arquivo, use o método list no recurso comments com o parâmetro fileId. O método retorna uma lista de comentários.

Transmita os seguintes parâmetros de consulta para personalizar a paginação ou filtrar comentários:

  • includeDeleted: defina como true para incluir comentários excluídos. Os comentários excluídos não incluem os campos htmlContent ou content.

  • pageSize: o número máximo de comentários a serem retornados por página.

  • pageToken: um token de página recebido de uma chamada de lista anterior. Informe esse token para recuperar a página subsequente.

  • startModifiedTime: o valor mínimo do campo modifiedTime para os comentários do resultado.

Solicitação

Neste exemplo, fornecemos o parâmetro de caminho fileId, o parâmetro de consulta includeDeleted e vários campos.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Atualizar um comentário

Para atualizar um comentário em um arquivo, use o método update no recurso comments com os parâmetros fileId e commentId. O corpo da solicitação usa o campo content para atualizar o comentário.

O campo booleano resolved no recurso comments é somente leitura. Um comentário só pode ser resolvido com uma resposta. Para mais informações, consulte Resolver um comentário.

O método retorna os campos listados no parâmetro de consulta fields.

Solicitação

Neste exemplo, fornecemos os parâmetros de caminho fileId e commentId e vários campos.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

Corpo da solicitação

{
  "content": "This comment is now updated."
}

Excluir um comentário

Para excluir um comentário em um arquivo, use o método delete no recurso comments com os parâmetros fileId e commentId.

Quando um comentário é excluído, o Drive marca o recurso como deleted: true. Os comentários excluídos não incluem os campos htmlContent ou content.

Solicitação

Neste exemplo, fornecemos os parâmetros de caminho fileId e commentId.

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