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 Presentaciones 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 metadatos o 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 múltiples solicitudes para, por ejemplo, agregar una presentación y, luego, darle formato.

Cada solicitud se valida antes de aplicarse. Todas las subsolicitudes del lote update 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 ú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 el índice del array está vacía.

Ejemplo

En la siguiente muestra de código, se puede ver cómo usar el procesamiento por lotes con las API de Presentaciones.

Solicitud

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

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

Respuesta

Este ejemplo de respuesta por lotes muestra información sobre cómo cada subsolicitud en se aplicó la solicitud por lotes. Observa el InsertTextRequest no contiene una respuesta, por lo que el valor de índice del array en [2] Consta de llaves vacías. La solicitud por lotes muestra el WriteControl que muestra cómo se ejecutaron las solicitudes de escritura.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}