Prácticas recomendadas para obtener los mejores resultados

Existen varios principios que debes seguir cuando usas la API de Documentos de Google. Estos incluyen los siguientes:

  • Edita hacia atrás para lograr eficiencia
  • Planifica la colaboración
  • Garantiza la coherencia del estado con el WriteControl campo
  • Ten en cuenta las pestañas

En las siguientes secciones, se explican estos principios.

Edita hacia atrás para lograr eficiencia

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

Planifica la colaboración

Espera que cambie el estado del documento. Entre una llamada al 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 a métodos.

Esto puede generar errores si tus índices son incorrectos. Cuando varios usuarios editan un documento con la IU, Documentos de Google se encarga de esto de forma transparente. Sin embargo, como cliente de API, tu app debe administrar esto. Incluso si no prevés la colaboración en el documento, es importante programar de forma defensiva y asegurarte de que el estado del documento siga siendo coherente. Para garantizar la coherencia, revisa la sección WriteControl.

Establece la coherencia del estado con WriteControl

Cuando lees y, luego, actualizas un documento, puedes controlar el comportamiento de cómo se controlan los cambios en conflicto con el WriteControl campo en el documents.batchUpdate método. WriteControl proporciona autoridad sobre cómo se ejecutan las solicitudes de escritura.

A continuación, se explica cómo usarlo:

  1. Obtén el documento con el documents.get método 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 las 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 de 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 de la API, los cambios de 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 es responsable de combinar el contenido.

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

Ten en cuenta las pestañas

Un solo documento puede contener varias pestañas, que requieren un manejo específico en tus solicitudes a la API.

Esto es lo que debes recordar:

  1. Configura el parámetro includeTabsContent como true en el documents.get método para recuperar el contenido de todas las pestañas de un documento. De forma predeterminada, no se muestra todo el contenido de las pestañas.
  2. Especifica los IDs de las pestañas a las que se aplicará cada Request a en el documents.batchUpdate método. Cada Request incluye una forma de especificar las pestañas a las que se aplicará la actualización. De forma predeterminada, si no se especifica una pestaña, la Request se aplicará, en la mayoría de los casos, a la primera pestaña del documento. Consulta la Requests documentación para obtener detalles.