Prácticas recomendadas para obtener los mejores resultados

Hay varios principios que debes seguir cuando usas la API de Documentos de Google. Se incluyen los siguientes productos:

  • Editar 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.

Editar hacia atrás para mejorar la eficiencia

Dentro de una sola llamada al método documents.batchUpdate, ordena las solicitudes en orden descendente de la ubicación del índice. Esto elimina la necesidad de calcular los cambios del índice debido a inserciones y eliminaciones.

Planifica la colaboración

Es posible 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:

Cómo puede cambiar un documento entre llamadas de método

Esto puede generar errores si tus índices son incorrectos. Como varios usuarios editan un documento con la IU, Documentos de Google se encarga de esto con transparencia. Sin embargo, como cliente de API, tu app debe administrar esto. Incluso si no prevés la colaboración en el documento, es importante que programes con la defensiva y te asegures de que el estado del documento se mantenga coherente. Para conocer una forma de 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 de la competencia con el campo WriteControl en el método documents.batchUpdate. WriteControl brinda autoridad sobre cómo se ejecutan las solicitudes de escritura.

Así es como se usa:

  1. Obtén el documento con el método documents.get y guarda el revisionId del recurso documents que se muestra.
  2. Redacta tus solicitudes de actualización.
  3. Incluye un objeto WriteControl opcional con una de estas dos opciones:
    1. El campo requiredRevisionId se establece en el revisionId del documento al que se aplica la solicitud de escritura. Si el documento se modificó desde la solicitud de lectura a la API, la solicitud de escritura no se procesa y muestra un error.
    2. El campo targetRevisionId se establece en el revisionId del documento al que se aplica la solicitud de escritura. Si el documento se modificó desde la solicitud de lectura a la API, los cambios en la solicitud de escritura se aplican a 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 se encarga de fusionar el contenido.

Para ver un ejemplo de cómo construir una solicitud por lotes con WriteControl, consulta este ejemplo de solicitud por lotes.