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 sem âncora 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.

Usar o parâmetro "fields"

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 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 vai 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
Ancorado
  • Os desenvolvedores podem definir o próprio formato para a especificação de âncora.
  • A âncora é salva e retornada ao recuperar o comentário, mas os apps editores do Google Workspace tratam esses comentários como não ancorados.
Sem âncora
  • Compatível com documentos do Google Workspace, que os mostram na visualização "Todos os comentários".
  • Os comentários não fixados não aparecem nos PDFs renderizados no visualizador de arquivos do Drive, mas são salvos e podem ser recuperados pela API Drive.

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 uma região em 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 list no recurso revisions para listar todos os revisionID de um documento. Siga esta etapa apenas se quiser ancorar 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 método create no recurso comments 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).

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

Python


from google.oauth2.credentials import Credentials
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 to anchor the comment to.
# Note: Line numbers are based on the revision.
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 on a specific line in a Google Doc.

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

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # 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 sem âncora

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

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

Python


from google.oauth2.credentials import Credentials
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 specific line in a Google Doc.

    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()

Responder a um comentário

Para adicionar uma resposta a um comentário, use o método 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 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 comments 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:

  • Não permitir mais respostas e diminuir a intensidade 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."
}

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. Forneça 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 ao postar 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 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