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: 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.

Respostas são anexadas a 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.

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 ancorados e não ancorados com a API Drive:

Tipo de comentário	Tipo de arquivo
Ancorado	Os desenvolvedores podem definir o próprio formato para a especificação da âncora. A âncora é salva e retornada ao recuperar o comentário. No entanto, os apps do editor do Google Workspace tratam esses comentários como não ancorados.
Não ancorado	Compatível com documentos do Google Workspace, que os mostrarão na visualização "Todos os comentários". Os comentários não ancorados 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 ancorado à revisão mais recente de um documento

Ao adicionar um comentário, talvez você queira ancorá-lo a uma região no arquivo. Uma âncora 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.

**Importante** :as â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 somente leitura.

Para adicionar um comentário ancorado:

1. (Opcional). Chame o list método no recurso revisions para listar cada revisionID de um documento. Siga esta etapa apenas se quiser ancorar um comentário a qualquer 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 create método no comments recurso com o fileID parâmetro, um comments recurso que contenha o comentário e uma string de âncora JSON que contenha o revisionID (r) e a região (a).

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

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.

**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 uma resposta pode excluir ou editar um comentário ou uma resposta. Ocorrem erros quando uma pessoa em uma função não criadora tenta excluir ou editar um comentário. Para evitar esses erros, verifique o campo author.me de o recurso de comentários.

Adicionar um comentário não ancorado

Para adicionar um comentário não ancorado, chame o create método com o fileId parâmetro e um comments recurso que contenha 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 ancorado:

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

**Importante** :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 uma resposta pode excluir ou editar um comentário ou uma resposta. Ocorrem erros quando um usuário em uma função não criadora tenta excluir ou editar um comentário. Para evitar esses erros, verifique o campo author.me de o recurso comments para garantir que o usuário que está fazendo a solicitação seja o autor do comentário e, em seguida, verifique as permissões dele em relação ao comentário.

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 includedDeleted 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

Temas relacionados

• Visão geral de arquivos e pastas
• Gerenciar revisões de arquivos