Administra comentarios y respuestas

Los comentarios son opiniones proporcionadas por los usuarios sobre un archivo, como un lector de un documento de procesamiento de texto que sugiere cómo reformular una oración. Existen dos tipos de comentarios: comentarios anclados y comentarios no anclados. Un comentario anclado está asociado con una ubicación específica, como una oración en un documento de procesamiento de texto, dentro de una versión específica de un documento. Por el contrario, un comentario no anclado solo está asociado con el documento.

Las respuestas se adjuntan a los comentarios y representan la respuesta de un usuario al comentario. La API de Google Drive permite que los usuarios agreguen comentarios y respuestas a los documentos creados por tu app. En conjunto, un comentario con respuestas se conoce como una discusión.

Usa el parámetro fields

Para todos los métodos (excepto delete) en el comments recurso, debes configurar el fields parámetro del sistema para especificar los campos que se mostrarán en la respuesta. En la mayoría de los métodos de recursos de Drive, esta acción solo es necesaria para mostrar campos no predeterminados, pero es obligatoria para el recurso comments. Si omites el parámetro fields, el método mostrará un error. Para obtener más información, consulta Cómo mostrar campos específicos.

Restricciones de comentarios

Se aplican las siguientes restricciones cuando se trabaja con comentarios anclados y no anclados con la API de Drive:

Tipo de comentario Tipo de archivo
Anclado
  • Los desarrolladores pueden definir su propio formato para la especificación de anclaje.
  • El anclaje se guarda y se muestra cuando se recupera el comentario, pero las apps del editor de Google Workspace tratan estos comentarios como comentarios no anclados.
  • Cuando se recuperan comentarios en archivos de Google Workspace (como Documentos, Hojas de cálculo o Presentaciones de Google) creados en el editor, el anchor campo contiene datos de anclaje internos específicos del editor (como una cadena JSON workbook-range en archivos de Hojas de cálculo). La API de Drive trata estos datos como opacos y no puede resolver regiones internas de documentos, coordenadas de celdas ni elementos de diapositivas. Para trabajar con comentarios anclados directamente en estos tipos de archivos, usa sus respectivas APIs: la API de Google Docs, la API de Google Sheets o la API de Google Slides.
No anclado
  • Se admite en documentos de Google Workspace, que los muestran en la vista "Todos los comentarios".
  • Los comentarios no anclados no se muestran en los archivos PDF renderizados en el visor de archivos de Drive, aunque se guardan y se pueden recuperar a través de la API de Drive.

Agrega un comentario anclado

Cuando agregas un comentario, es posible que quieras anclarlo a una región del archivo. Un anclaje define una región en un archivo al que hace referencia un comentario. El recurso comments define el campo anchor como una cadena JSON.

Para agregar un comentario anclado, sigue estos pasos:

  1. (Opcional) Llama al list método en el recurso revisions para enumerar cada revisionID de un documento. Solo sigue este paso si quieres anclar un comentario a cualquier revisión que no sea la más reciente. Si quieres usar la revisión más reciente, usa head para el revisionID.

  2. Llama al create método en el comments recurso con el fileId parámetro, un comments recurso que contenga el comentario y una cadena de anclaje JSON definida por tu aplicación.

En la siguiente muestra de código, se muestra cómo crear un comentario anclado:

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

La API de Drive muestra una instancia del objeto de recurso comments que incluye la cadena anchor.

Agrega un comentario no anclado

Para agregar un comentario no anclado, llama al create método con el fileId parámetro y un comments recurso que contenga el comentario.

El comentario se inserta como texto sin formato, pero el cuerpo de la respuesta proporciona un htmlContent campo que contiene contenido con formato para mostrar.

En la siguiente muestra de código, se muestra cómo crear un comentario no anclado:

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

Agrega una respuesta a un comentario

Para agregar una respuesta a un comentario, usa el create método en el replies recurso con los fileId y commentId parámetros. El cuerpo de la solicitud usa el campo content para agregar la respuesta.

La respuesta se inserta como texto sin formato, pero el cuerpo de la respuesta proporciona un campo htmlContent que contiene contenido con formato para mostrar.

El método muestra los campos que se enumeran en el campo fields.

Solicitud

En este ejemplo, proporcionamos los parámetros de ruta de acceso fileId y commentId, y varios campos.

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

Cuerpo de la solicitud

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

Resuelve un comentario

Un comentario solo se puede resolver publicando una respuesta a un comentario.

Para resolver un comentario, usa el create método en el replies recurso con los fileId y commentId parámetros.

El cuerpo de la solicitud usa el action campo para resolver el comentario. También puedes configurar el campo content para agregar una respuesta que cierre el comentario.

Cuando se resuelve un comentario, Drive marca el recurso comments como resolved: true. A diferencia de los comentarios borrados, los comentarios resueltos pueden incluir los campos htmlContent o content.

Cuando tu app resuelve un comentario, su IU debe indicar que se abordó el comentario. Por ejemplo, tu app podría hacer lo siguiente:

  • Inhabilitar más respuestas y atenuar todas las respuestas anteriores, además del comentario original
  • Ocultar los comentarios resueltos

Solicitud

En este ejemplo, proporcionamos los parámetros de ruta de acceso fileId y commentId, y varios campos.

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

Cuerpo de la solicitud

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

Obtén un comentario

Para obtener un comentario sobre un archivo, usa el get método en el comments recurso con los fileId y commentId parámetros. Si no conoces el ID del comentario, puedes enumerar todos los comentarios con el método list.

El método muestra una instancia de un recurso comments.

Para incluir comentarios borrados en los resultados, configura el includeDeleted parámetro de consulta como true.

Solicitud

En este ejemplo, proporcionamos los parámetros de ruta de acceso fileId y commentId, y varios campos.

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

Enumera comentarios

Para enumerar comentarios en un archivo, usa el list método en el comments recurso con el fileId parámetro. El método muestra una lista de comentarios.

Pasa los siguientes parámetros de consulta para personalizar la paginación de los comentarios o filtrarlos:

  • includeDeleted: Configúralo como true para incluir comentarios borrados. Los comentarios borrados no incluyen los campos htmlContent ni content.

  • pageSize: Es la cantidad máxima de comentarios que se mostrarán por página.

  • pageToken: Es un token de página que se recibió de una llamada a la lista anterior. Proporciona este token para recuperar la página siguiente.

  • startModifiedTime: Es el valor mínimo del campo modifiedTime para los comentarios de resultado.

Solicitud

En este ejemplo, proporcionamos el parámetro de ruta de acceso fileId, el parámetro de consulta includeDeleted y varios campos.

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

Actualiza un comentario

Para actualizar un comentario sobre un archivo, usa el update método en el comments recurso con los fileId y commentId parámetros. El cuerpo de la solicitud usa el campo content para actualizar el comentario.

El campo booleano resolved en el recurso comments es de solo lectura. Un comentario solo se puede resolver publicando una respuesta a un comentario. Para obtener más información, consulta Resuelve un comentario.

El método muestra los campos que se enumeran en el parámetro de consulta fields.

Solicitud

En este ejemplo, proporcionamos los parámetros de ruta de acceso fileId y commentId, y varios campos.

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

Cuerpo de la solicitud

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

Borra un comentario

Para borrar un comentario sobre un archivo, usa el delete método en el recurso comments con los parámetros fileId y commentId.

Cuando se borra un comentario, Drive marca el recurso de comentario como deleted: true. Los comentarios borrados no incluyen los campos htmlContent ni content.

Solicitud

En este ejemplo, proporcionamos los parámetros de ruta de acceso fileId y commentId.

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