Los comentarios son comentarios que los usuarios proporcionan 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: anclados y no anclados. Un comentario fijado 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 sin anclar solo se asocia con el documento.
Las respuestas se adjuntan a los comentarios y representan la respuesta de un usuario a estos. La API de Drive permite que los usuarios agreguen comentarios y respuestas a los documentos que crea tu app. En conjunto, un comentario con respuestas se conoce como una discusión.
Es necesario configurar el parámetro fields para enumerar los campos que se mostrarán en la respuesta cuando se llame a todos los métodos que se enumeran en el recurso comments. Si omites el parámetro, el método mostrará un error. Para mostrar los campos exactos que necesitas, consulta Cómo mostrar campos específicos.
Agrega un comentario sin anclar
Para agregar un comentario sin anclar 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 muestra los campos que se indican en el campo fields.
Mostrar un ejemplo
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
Solo se puede resolver un comentario si se publica una respuesta a este.
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 del 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 respondió. 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
- Oculta los comentarios resueltos.
Mostrar un ejemplo
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, te recomendamos que lo ancles a una región del archivo. Un anclaje define la revisión y la región de 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:
(Opcional) Llama al método
revisions.list()para enumerar todos losrevisionIDde un documento. Sigue este paso solo si deseas fijar un comentario a cualquier revisión que no sea la más reciente. Si quieres usar la revisión más reciente, usaheadpararevisionID.Llama al método
create()con el parámetrofileID, un recursocommentsque contenga el comentario y una cadena de ancla JSON que contengarevisionID(r) y la región (a).
La forma en que definas una región depende del tipo de contenido del documento con el que trabajes. Para obtener más información, consulta Cómo definir una región.
Define una región
Como se mencionó anteriormente, la cadena de ancla JSON contiene un revisionID (r) y una región (a). La región (a) es un array JSON que contiene clasificadores de región que especifican el formato y la ubicación a la 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 vincular. 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 ancla JSON que ancla comentarios a líneas en dos áreas separadas de un documento:
- El primer área comienza en la línea 12 (
'n':12) y se extiende por tres líneas ('l':3). - El segundo á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.
Cómo obtener 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
enumerar todos los comentarios con el método list().
El método muestra una instancia de un recurso comments.
Para incluir los comentarios borrados en los resultados, establece el parámetro de búsqueda includedDeleted como true.
Mostrar un ejemplo
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 muestra una lista de comentarios.
Pasa los siguientes parámetros de consulta para personalizar la paginación de los comentarios o filtrar los siguientes:
includeDeleted: Se establece entruepara incluir los comentarios borrados. Los comentarios borrados no incluyen los camposhtmlContentnicontent.pageSize: Es la cantidad máxima de comentarios que se mostrarán por página.pageToken: Es un token de página, recibido desde una llamada a lista anterior. Proporciona este token para recuperar la página siguiente.startModifiedTime: El valor mínimo del campomodifiedTimepara los comentarios de los resultados.
Mostrar un ejemplo
Solicitud
En este ejemplo, proporcionamos el parámetro de ruta 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)
Cómo actualizar 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 método muestra los campos que se indican en el parámetro de consulta fields.
Mostrar un ejemplo
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 de 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 del comentario como deleted: true. Los comentarios borrados no incluyen los campos htmlContent ni content.
Mostrar un ejemplo
Solicitud
En este ejemplo, proporcionamos los parámetros de ruta fileId y commentId.
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID