Hay varios principios que debes seguir cuando usas la API de Documentos de Google. Estos incluyen:
- Edita hacia atrás para mejorar la eficiencia
- Planifica la colaboración
- Garantiza la coherencia del estado con el campo
WriteControl
En las siguientes secciones, se explican estos principios.
Edita hacia atrás para mejorar la eficiencia
En una sola llamada al método documents.batchUpdate
, ordena tus solicitudes en orden descendente de ubicación del índice. Esto elimina la necesidad de calcular los cambios de índice debido a las inserciones y eliminaciones.
Planifica la colaboración
Es probable que cambie el estado del documento. Entre una llamada de método y otra, otros colaboradores pueden actualizar el documento, como se muestra en el siguiente diagrama:
Esto puede generar errores si tus índices son incorrectos. Dado que varios usuarios editan un
documento con la IU, Documentos de Google se encarga de esto con transparencia. Sin embargo, como cliente de la API, tu app debe administrar esto. Incluso si no anticipas una colaboración en el documento, es importante programar de manera defensiva y asegurarte de que el estado del documento permanezca coherente. Para garantizar la coherencia, revisa la sección WriteControl
.
Establece coherencia de estado con WriteControl
Cuando lees y, luego, actualizas un documento, puedes controlar el comportamiento de cómo
se manejan los cambios competidores mediante el campo
WriteControl
del método documents.batchUpdate
. WriteControl
proporciona autoridad sobre cómo se ejecutan las solicitudes de escritura.
Puedes usarla de la siguiente manera:
- Obtén el documento con el método
documents.get
y guardarevisionId
del recursodocuments
que se muestra. - Redacta tus solicitudes de actualización.
- Incluye un objeto
WriteControl
opcional con una de estas dos opciones:- El campo
requiredRevisionId
se establece en elrevisionId
del documento al que se aplica la solicitud de escritura. Si el documento se modificó desde la solicitud de lectura de la API, la solicitud de escritura no se procesa y se muestra un error. - El campo
targetRevisionId
se establece en elrevisionId
del documento al que se aplica la solicitud de escritura. Si el documento se modificó desde la solicitud de lectura de la API, los cambios en la solicitud de escritura se aplican en los cambios del colaborador. El resultado de la solicitud de escritura incorpora los cambios de la solicitud de escritura y los cambios del colaborador en una nueva revisión del documento. El servidor de Documentos es responsable de combinar el contenido.
- El campo
Para ver un ejemplo de cómo construir una solicitud por lotes con WriteControl
, consulta este ejemplo de solicitud por lotes.