Gerenciar comentários e respostas

Comentários são feedback dos usuários sobre um arquivo, como um leitor de um documento de processamento de texto sugerindo como reformular uma frase. Há dois tipos de comentários: fixos e não fixos. Um comentário fixo 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 fixo está associado apenas ao documento.

Respostas são anexadas a comentários e representam a resposta de um usuário ao comentário. A API Google 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.

Usar o parâmetro "fields"

Para todos os métodos (exceto delete) no comments recurso, é necessário definir o fields parâmetro do sistema para especificar os campos a serem retornados na resposta. Na maioria dos métodos de recursos 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 fields, o método retornará um erro. Para mais informações, consulte Retornar campos específicos.

Restrições de comentários

As seguintes restrições são aplicadas ao trabalhar com comentários fixos e não fixos com a API Drive:

Tipo de comentário Tipo de arquivo
Fixo
  • Os desenvolvedores podem definir o próprio formato para a especificação de fixação.
  • A fixação é salva e retornada ao recuperar o comentário, mas os apps do editor do Google Workspace tratam esses comentários como não fixos.
  • Ao recuperar comentários em arquivos do Google Workspace (como Documentos, Planilhas ou Apresentações Google) criados no editor, o anchor campo contém dados de fixação internos específicos do editor (como uma workbook-range string JSON em arquivos do Planilhas). A API Drive trata esses dados como opacos e não pode resolver regiões internas de documentos, coordenadas de células ou elementos de slides. Para trabalhar com comentários fixos diretamente nesses tipos de arquivo, use as APIs respectivas: API Google Docs, API Google Sheets, ou API Google Slides.
Não fixo
  • Compatível com documentos do Google Workspace, que os mostram na visualização "Todos os comentários".
  • Os comentários não fixos não são mostrados em PDFs renderizados no visualizador de arquivos do Drive, embora sejam salvos e possam ser recuperados pela API Drive.

Adicionar um comentário fixo

Ao adicionar um comentário, talvez você queira fixá-lo em uma região do arquivo. Uma fixação define uma região em um arquivo a que um comentário se refere. O recurso comments define o anchor campo como uma string JSON.

Para adicionar um comentário fixo:

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

  2. Chame o create método no comments recurso com o fileId parâmetro, um comments recurso que contém o comentário e uma string de fixação JSON definida pelo seu aplicativo.

O exemplo de código a seguir mostra como criar um comentário fixo:

Python

import json

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number in your application to anchor the comment to.
# Note: Google Workspace editor apps (such as Google Docs, Sheets, and
# Slides) treat comments created using the Drive API as unanchored
# comments. Custom anchors are intended for your own applications or
# custom file viewers.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment with a custom application-defined anchor.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define a custom anchor specification for your application.
        # The Drive API stores the anchor as an opaque string. Your custom
        # application or file viewer can parse this JSON string to position
        # the comment in your UI.
        anchor_data = {
            'line': ANCHOR_LINE,
            'revision': 'head'
        }

        # The comment body. The 'anchor' field must be a serialized
        # JSON string.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': json.dumps(anchor_data)
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

A API Drive retorna uma instância do objeto de recurso comments, que inclui a string anchor.

Adicionar um comentário não fixo

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

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

O exemplo de código a seguir mostra como criar um comentário não fixo:

Python


from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a file in Drive.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

Adicionar uma resposta a um comentário

Para adicionar uma resposta a um comentário, use o create método no replies recurso com os fileId e commentId parâmetros. 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 que contém 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 postando uma resposta a ele.

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

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

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

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

  • Não permitir mais respostas e esmaecer todas as respostas anteriores e o 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."
}

Receber um comentário

Para receber um comentário em um arquivo, use o get método no comments recurso com os fileId e commentId parâmetros. Se você não souber o ID do comentário, poderá listar 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 includeDeleted parâmetro de consulta 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 list método no comments recurso com o fileId parâmetro. 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. Forneça esse token para recuperar a página seguinte.

  • startModifiedTime: o valor mínimo do campo modifiedTime para os comentários de 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 update método no comments recurso com os fileId e commentId parâmetros. 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 postando uma resposta a ele. 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 delete método no comments recurso com os fileId e commentId parâmetros.

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.

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