Solicitudes por lotes

Este documento muestra cómo agrupar llamadas a la API para reducir la cantidad de conexiones que debe establecer el cliente. La agrupación en lotes puede mejorar el rendimiento de la red, disminuyendo las idas y vueltas de la red y aumentando 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 que el cliente pueda colocar varias Objetos Request, cada uno especifica un solo tipo de solicitud para realizar, en una única solicitud por lotes. Una solicitud por lotes puede mejorar el rendimiento combinando múltiples subsolicitudes en una única llamada al servidor, recuperando ni una sola respuesta.

Recomendamos a los usuarios que siempre agrupen varias solicitudes. Estos son algunos ejemplos 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.

Límites, autorización y consideraciones de 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 API. para tu 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 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 darle estilo.

Detalles del lote

Una solicitud por lotes consta de una llamada al método batchUpdate con varias solicitudes secundarias, por ejemplo, para agregar un documento y darle formato.

Cada solicitud se valida antes de aplicarse. Todas las subsolicitudes de la actualización en lote se aplican de forma atómica. Es decir, si alguna solicitud no es válida, la actualización no se realiza de forma correcta y ninguna de las (posiblemente dependientes) de que se apliquen los cambios.

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

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

Formato de una solicitud por lotes

Una solicitud es una solicitud JSON única que contiene múltiples, subsolicitudes anidadas con una propiedad obligatoria: requests. El Las solicitudes se construyen en un array de solicitudes individuales. Cada solicitud utiliza 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 el formato de la solicitud. La respuesta del servidor contiene una respuesta completa del objeto de respuesta único.

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 el índice del 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 “Hello World” texto en el inicio de un documento existente, con una índice location de 1 mediante el InsertTextRequest

  • Actualizar la palabra “Hola” con el UpdateTextStyleRequest startIndex y endIndex definen la range del texto con formato dentro segmento.

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

  • Con WriteControl puedes controlar cómo se ejecutan las solicitudes de escritura. Para ver más consulta Establece coherencia de estado con WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "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 TAB_ID y REQUIRED_REVISION_ID por el ID de la pestaña y el ID de revisión, respectivamente, del documento a la solicitud de escritura a la que se aplica el filtro.

Respuesta

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

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