Administrar 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 se asocia 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 se asocia con el documento.

Las respuestas se adjuntan a los comentarios y representan la respuesta de un usuario al comentario. La API de 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 muestra un error. Para obtener más información, consulta Cómo mostrar campos específicos.

Limitaciones de comentarios

Se aplican las siguientes limitaciones 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. Sin embargo, las apps del editor de Google Workspace tratan estos comentarios como comentarios no anclados.
No anclado
  • Se admite en documentos de Google Workspace, que los mostrarán 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 a la revisión más reciente de un documento

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 que contenga el revisionID (r) y la región (a).

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

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

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 el siguiente ejemplo de código, se muestra cómo crear un comentario no anclado:

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

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 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 includedDeleted 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 los comentarios de 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: Se establece en 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 recibe de una llamada de lista anterior. Proporciónalo 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 comentarios 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