Los comentarios son opiniones que los usuarios proporcionan sobre un archivo, como cuando un lector de un documento de procesamiento de texto 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 discusión.
Usa el parámetro fields
Para todos los métodos (excepto delete) en el recurso comments, debes establecer el parámetro del sistema fields para especificar los campos que se devolverán en la respuesta. En la mayoría de los métodos de recursos de Drive, esta acción solo es necesaria para devolver 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 devolver campos específicos.
Restricciones de comentarios
Cuando trabajas con comentarios anclados y no anclados con la API de Drive, se aplican las siguientes restricciones:
| Tipo de comentario | File type |
|---|---|
| Anclado |
|
| Sin anclaje |
|
Agrega un comentario anclado a la revisión más reciente de un documento
Cuando agregues un comentario, es posible que desees anclarlo a una región del archivo. Un ancla define una región en un archivo a la que se refiere un comentario. El recurso comments define el campo anchor como una cadena JSON.
Para agregar un comentario anclado, sigue estos pasos:
(Opcional) Llama al método
listen el recursorevisionspara enumerar cadarevisionIDde un documento. Sigue este paso solo si deseas anclar un comentario a una revisión que no sea la más reciente. Si quieres usar la revisión más reciente, usaheadpararevisionID.Llama al método
createen el recursocommentscon el parámetrofileID, un recursocommentsque contiene el comentario y una cadena de anclaje JSON que contiene elrevisionID(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 devuelve una instancia del objeto de recurso comments, que incluye la cadena anchor.
Cómo agregar un comentario no anclado
Para agregar un comentario no anclado, llama al método create con el parámetro fileId y un recurso comments que contenga el comentario.
El comentario se inserta como texto sin formato, pero el cuerpo de la respuesta proporciona un campo htmlContent que contiene contenido con formato para su visualización.
En el siguiente ejemplo de código, se muestra cómo crear un comentario sin anclaje:
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()
Cómo agregar una respuesta a un comentario
Para agregar una respuesta a un comentario, usa el método create en el recurso replies con los parámetros fileId y commentId. 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 su visualización.
El método devuelve los campos que se indican en el campo fields.
Solicitud
En este ejemplo, proporcionamos los parámetros de ruta 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."
}Cómo resolver un comentario
Un comentario solo se puede resolver publicando una respuesta.
Para resolver un comentario, usa el método create en el recurso replies con los parámetros fileId y commentId.
El cuerpo de la solicitud usa el campo action 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 resuelva un comentario, la IU debe indicar que se abordó el comentario. Por ejemplo, tu app podría hacer lo siguiente:
- No permitir 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 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 método get en el recurso comments con los parámetros fileId y commentId. Si no conoces el ID del comentario, puedes listar todos los comentarios con el método list.
El método devuelve una instancia de un recurso comments.
Para incluir los comentarios borrados en los resultados, establece el parámetro de búsqueda includedDeleted en true.
Solicitud
En este ejemplo, proporcionamos los parámetros de ruta fileId y commentId, y varios campos.
GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved
Cómo enumerar comentarios
Para enumerar los comentarios de un archivo, usa el método list en el recurso comments con el parámetro fileId. El método devuelve una lista de comentarios.
Pasa los siguientes parámetros de consulta para personalizar la paginación de los comentarios o filtrarlos:
includeDeleted: Se establece entruepara incluir los comentarios borrados. Los comentarios borrados no incluyen los camposhtmlContentocontent.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 lista anterior. Proporciona este token para recuperar la página siguiente.startModifiedTime: Es el valor mínimo del campomodifiedTimepara los comentarios del 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 en un archivo, usa el método update en el recurso comments con los parámetros fileId y commentId. El cuerpo de la solicitud usa el campo content para actualizar el comentario.
El campo booleano resolved del recurso comments es de solo lectura. Un comentario solo se puede resolver publicando una respuesta. Para obtener más información, consulta Cómo resolver un comentario.
El método devuelve los campos que se indican en el parámetro de consulta fields.
Solicitud
En este ejemplo, proporcionamos los parámetros de ruta 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."
}Cómo borrar un comentario
Para borrar un comentario en un archivo, usa el método delete 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