Gerenciar comentários e respostas

Os comentários são feedbacks fornecidos pelo usuário sobre um arquivo, como um leitor de um documento de processamento de texto que sugere como reformular uma frase. Há dois tipos de comentários: com âncora e sem âncora. Um comentário fixado é 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 sem âncora é apenas associado ao documento.

Observação: em arquivos blob, a API Google Drive só oferece suporte a comentários sem âncora. Não é possível usar comentários fixados em arquivos blob ou nos arquivos do editor do Documentos Google.

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

A configuração do parâmetro fields é necessária para listar os campos que serão retornados na resposta ao chamar todos os métodos listados no recurso comments. Se você omitir o parâmetro, o método vai retornar um erro. Para retornar os campos exatos necessários, consulte Retornar campos específicos.

Adicionar um comentário sem âncora

Para adicionar um comentário sem âncora 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.

Importante: recomendamos verificar se um usuário tem as permissões corretas para adicionar comentários. Além disso, apenas o criador de um comentário ou resposta pode excluir ou editar um comentário ou uma resposta. Os erros ocorrem quando um usuário que não tem a função de criador de conteúdo tenta excluir ou editar um comentário. Para evitar esses erros, verifique o campo author.me do recurso comments para garantir que o usuário que faz a solicitação seja o autor do comentário e, em seguida, verifique as permissões relacionadas ao comentário.

Adicionar uma resposta 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.

Mostrar um exemplo

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

Para resolver um comentário, é necessário responder a ele.

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. Também é possível definir o campo content para adicionar uma resposta que fecha o comentário.

Quando um comentário é resolvido, o Drive marca o recurso de comentário 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 resolver um comentário, a interface precisa indicar que ele foi encaminhado. Por exemplo, o app pode:

• Não permite mais respostas e desativa todas as respostas anteriores, além do comentário original.
• Ocultar comentários resolvidos.

Mostrar um exemplo

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 anexá-lo a uma região no 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.

Observação: em arquivos blob, a API Drive só oferece suporte a comentários não ancorados. Não é possível usar comentários fixos em arquivos blob ou arquivos do editor do Documentos Google.

Importante: os âncoras são imutáveis, e a posição delas em relação ao conteúdo de um documento não pode ser garantida entre as revisões. Recomendamos o uso de âncoras em documentos em que a posição não muda, como arquivos de imagem ou documentos de leitura somente.

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 você quiser ancorar um comentário em qualquer revisão, exceto a mais recente. Se você 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 contenha o comentário e uma string de âncora JSON que contenha o revisionID (r) e a região (a).

A forma de definir 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.

Observação: recomendamos que você verifique se um usuário tem as permissões corretas para adicionar comentários. Além disso, apenas o criador de um comentário ou resposta pode excluir ou editar um comentário ou uma resposta. Os erros ocorrem quando uma pessoa que não tem a função de criador de conteúdo tenta excluir ou editar um comentário. Para evitar esses erros, verifique o campo author.me do recurso comments.

Definir uma região

Como mencionado anteriormente, a string de â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 especificando 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 em um vídeo. Para definir uma região, selecione o classificador de região correspondente ao tipo de conteúdo que você quer ancorar. Por exemplo, se o conteúdo for texto, provavelmente você usará o classificador de região txt ou line.

Para conferir 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 ancora comentários em 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 cobre 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.

Importante: se o app permitir que os usuários atualizem e compartilhem várias revisões de um documento, os comentários de revisões mais antigas talvez não se apliquem mais ao local fixado. Portanto, é necessário indicar claramente na interface a qual revisão cada comentário pertence.

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, use o método list() para listar todos os comentários.

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.

Mostrar um exemplo

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 este token para recuperar a página seguinte.

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

Mostrar um exemplo

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 método retorna os campos listados no parâmetro de consulta fields.

Mostrar um exemplo

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 de comentário como deleted: true. Os comentários excluídos não incluem os campos htmlContent ou content.

Mostrar um exemplo

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