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 a 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.
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 Drive, esta acción solo es necesaria para devolver campos no predeterminados, pero es obligatoria para el recurso comments. Si omites el parámetro, el método devuelve un error. Para obtener más información, consulta Cómo devolver campos específicos.
Cómo agregar un comentario no anclado
Para agregar un comentario no anclado a un documento, 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.
Cómo agregar una respuesta a un comentario
Para agregar una respuesta a un comentario, usa el método replies.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 replies.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 de comentario 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."
}Cómo agregar 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 la revisión y la región del archivo a las 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
revisions.listpara enumerar todos losrevisionIDde 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
createcon el parámetrofileID, un recursocommentsque contiene el comentario y una cadena de anclaje JSON que contiene elrevisionID(r) y la región (a).
La forma en que defines una región depende del tipo de contenido del documento con el que trabajas. Para obtener más información, consulta Cómo definir una región.
Cómo definir una región
Como se mencionó anteriormente, la cadena de anclaje JSON contiene un revisionID (r) y una región (a). La región (a) es un array JSON que contiene clasificadores de regiones que especifican el formato y la ubicación a los que se ancla un comentario. Un clasificador puede ser un rectángulo bidimensional para una imagen, una línea de texto en un documento o una duración en un video. Para definir una región, selecciona el clasificador de regiones que coincida con el tipo de contenido al que intentas anclarte. Por ejemplo, si tu contenido es texto, es probable que uses el clasificador de regiones txt o line.
Para obtener una lista de los clasificadores de regiones en la API de Drive, consulta Clasificadores de regiones.
En el siguiente ejemplo, se muestra una cadena de anclaje JSON que ancla comentarios a líneas en dos áreas separadas de un documento:
- La primera área comienza en la línea 12 (
'n':12) y se extiende por tres líneas ('l':3). - La segunda área solo abarca la línea 18 (
'n':18, 'l':1`).
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Reemplaza REVISION_ID por head o el ID de una revisión específica.
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, recibido 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