Solicitudes por lotes

En este documento, se muestra cómo agrupar llamadas a la API para reducir la cantidad de conexiones que debe hacer el cliente. La agrupación en lotes puede mejorar la eficiencia de una aplicación, ya que reduce la ida y vuelta de la red y aumenta la capacidad de procesamiento.

Descripción general

Cada conexión que realiza tu cliente da como resultado una cierta cantidad de sobrecarga. La API de Documentos de Google admite el procesamiento por lotes para permitir que tu cliente coloque varios objetos de solicitud, cada uno de los cuales especifica un solo tipo de solicitud para realizar, en una única solicitud por lotes. Una solicitud por lotes puede mejorar el rendimiento a través de la combinación de varias subsolicitudes en una sola llamada al servidor y la recuperación de una sola respuesta.

Recomendamos a los usuarios que siempre agrupen varias solicitudes. Estos son algunos ejemplos de situaciones en las que puedes usar el procesamiento por lotes:

  • Acabas de empezar a usar la API y tienes muchos datos para subir.
  • Debes actualizar los metadatos o las propiedades, como el formato, en varios objetos.
  • Debes borrar muchos objetos.

Consideraciones sobre los límites, la autorización y la dependencia

Esta es una lista de otros elementos que debes tener en cuenta cuando se emplea la actualización por lotes:

  • Cada solicitud por lotes, incluidas todas las subsolicitudes, se cuenta como una solicitud a la API respecto del límite de uso.
  • Una solicitud por lotes se autentica una vez. Esta autenticación única se aplica a todos los objetos de actualización por lotes de la solicitud.
  • El servidor procesa las subsolicitudes en el mismo orden en que aparecen en la solicitud por lotes. Las últimas subsolicitudes pueden depender de las acciones realizadas durante las subsolicitudes anteriores. Por ejemplo, en la misma solicitud por lotes, los usuarios pueden insertar texto en un documento existente y, luego, darle estilo.

Detalles del lote

Una solicitud por lotes consiste en una llamada al método batchUpdate con varias subsolicitudes para, por ejemplo, agregar un documento y, luego, darle formato.

Cada solicitud se valida antes de aplicarse. Todas las subsolicitudes de la actualización por lotes se aplican de forma atómica. Es decir, si alguna solicitud no es válida, no se realizará correctamente la actualización completa y no se aplicará ninguno de los cambios (potencialmente dependientes).

Algunas solicitudes proporcionan respuestas con información sobre las solicitudes aplicadas. Por ejemplo, todas las solicitudes de actualización por lotes para agregar objetos muestran respuestas a fin de que puedas acceder a los metadatos del objeto recién agregado, como el ID o el título.

Con este enfoque, puedes crear un documento de Google completo mediante una solicitud de actualización por lotes de la API con varias solicitudes secundarias.

Formato de una solicitud por lotes

Una solicitud es una solicitud JSON que contiene varias subsolicitudes anidadas con una propiedad obligatoria: requests. Las solicitudes se construyen en un array de solicitudes individuales. Cada solicitud usa JSON para representar el objeto de solicitud y contener sus propiedades.

Formato de una respuesta por lotes

El formato de respuesta para una solicitud por lotes es similar al formato de solicitud. La respuesta del servidor contiene una respuesta completa del único objeto de respuesta.

La propiedad principal del objeto JSON se llama replies. Las respuestas se muestran en un array, y cada respuesta a una de las solicitudes ocupa el mismo orden de índice que la solicitud correspondiente. Algunas solicitudes no tienen respuestas y la respuesta en ese índice de array está vacía.

Ejemplo

En la siguiente muestra de código, se puede apreciar cómo usar la agrupación en lotes con la API de Documentos.

Solicitud

En este ejemplo de solicitud por lotes, se muestra cómo hacer lo siguiente:

  • Inserta el texto “Hello World” en el inicio de un documento existente, con un índice location de 1, mediante InsertTextRequest.

  • Actualiza la palabra "Hola" con UpdateTextStyleRequest. Los valores startIndex y endIndex definen el range del texto con formato dentro del segmento.

  • Con textStyle, establece el estilo de fuente en negrita y el color en azul solo para la palabra "Hello".

  • Con el campo WriteControl, puedes controlar cómo se ejecutan las solicitudes de escritura. Para obtener más información, consulta Cómo establecer coherencia de estado con WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

Reemplaza REQUIRED_REVISION_ID por el ID de revisión del documento al que se aplica la solicitud de escritura.

Respuesta

En este ejemplo de respuesta por lotes, se muestra información sobre cómo se aplicó cada subsolicitud dentro de la solicitud por lotes. Ni InsertTextRequest ni UpdateTextStyleRequest contienen una respuesta, por lo que los valores de índice del array en [0] y [1] constan de llaves vacías. La solicitud por lotes muestra el objeto WriteControl, que indica cómo se ejecutaron las solicitudes.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}