Procesamiento de grandes cantidades de datos con API (parte 2 de 2) ☁️

Cuando trabaje en un entorno empresarial, es posible que deba procesar grandes cantidades de registros de Salesforce utilizando las API de la plataforma. Esta publicación es la segunda parte de una serie de dos publicaciones que se centran en el procesamiento de datos a escala con API. En la primera parte de la serie , nos enfocamos en las operaciones de lectura con la API REST y las API masivas. En esta segunda parte, nos centraremos en las operaciones de escritura. Compararemos dos API que son ideales para el trabajo: la API compuesta y las API masivas.

Escribir registros con la API compuesta

Si bien la API REST es excelente para leer varios registros, sus recursos son demasiado granulares para operaciones de escritura a escala (una solicitud por operación de escritura). La API compuesta supera esta limitación. Hereda de la API REST en el sentido de que es una API síncrona que tiene acceso a los recursos de la API REST, pero admite varias operaciones de escritura por solicitud, lo que reduce la sobrecarga de las solicitudes/respuestas HTTP.

Hay tres recursos principales en Composite API que le permiten escribir datos: lote compuesto, compuesto y gráfico compuesto. Antes de entrar en los detalles de estos recursos, aquí hay una descripción general de la estructura de solicitud y los límites de estos recursos:

Recurso por lotes compuesto

El recurso de lote compuesto es el recurso más simple (el menos detallado) de la API compuesta, pero tiene algunas limitaciones. Este recurso permite la ejecución de hasta 25 subsolicitudes de API REST de forma secuencial. La diferencia clave entre este recurso y los demás es que las subsolicitudes por lotes son independientes y no se puede pasar información entre ellas.

Otra consideración importante para el recurso por lotes es que las subsolicitudes son transaccionales, pero la solicitud por lotes principal no lo es. Por ejemplo, si falla la tercera subsolicitud de un lote, solo se revierte esta tercera subsolicitud (las dos solicitudes anteriores no se revierten). Además, la solicitud seguirá ejecutando las subsolicitudes restantes después de que se produzca un error, a menos que establezca el indicador haltOnError en true .

Nota: Utilice el recurso de lote compuesto con cuidado para no introducir problemas de integridad de datos en caso de errores.

Para ejecutar una solicitud por lotes compuesta, ejecute una solicitud POST en INSTANCE_URL/services/data/v56.0/composite/batch con un cuerpo como este:

Este ejemplo cambia el nombre de una cuenta a "Nuevo nombre" y recupera el nombre de cuenta actualizado, así como su código postal de facturación. El resultado de esta solicitud se ve así:

Puntos destacados de la respuesta:

• El indicador hasErrors indica si una o más de las subsolicitudes fallaron.
• La propiedad de results contiene la lista de respuestas para las subsolicitudes. Las respuestas a subsolicitudes incluyen dos propiedades: statusCode y results . El valor y la forma de los results dependen de la operación que se realizó.

Las subsolicitudes pueden incluir varias consultas de SObjects; sin embargo, existen limitaciones importantes en los resultados que se recuperan. Una vez que obtenga un total de 2000 registros en varias subsolicitudes, las consultas restantes de la solicitud solo obtendrán los primeros registros de sus conjuntos de resultados y proporcionarán direcciones URL de localización de consultas que le permitirán obtener resultados adicionales (consulte la Parte 1 de esta serie para obtener más información) .

Nota: Al recuperar datos con el recurso de lote compuesto, tenga en cuenta los límites de recuperación de registros.

Por ejemplo, suponiendo que su organización tiene más de 2000 registros para cada SObjects, si ejecuta la siguiente solicitud por lotes, solo recuperaría hasta 1998 cuentas, hasta dos contactos (esto le da un total de 2000 registros) y hasta una oportunidad.

recurso compuesto

El recurso compuesto lleva el concepto de recurso por lotes un paso más allá con dos mejoras importantes. En primer lugar, en lugar de ejecutar las 25 subsolicitudes de forma independiente, ahora puede compartir ID de referencia entre subsolicitudes. En segundo lugar, puede hacer cumplir una transacción en el nivel de solicitud con un indicador allOrNone . Habilitar el indicador le permite revertir la solicitud completa si alguna de las subsolicitudes falla.

Para ejecutar una solicitud compuesta, ejecute una solicitud POST en INSTANCE_URL/services/data/v56.0/composite con un cuerpo como este:

Este ejemplo contiene dos subsolicitudes. La primera subsolicitud crea una cuenta denominada "Cuenta de muestra" y la segunda solicitud adjunta un contacto a la cuenta mediante una referencia refAccount para pasar el ID de la cuenta principal como @{refAccount.id} . El resultado de esta solicitud se ve así:

Recurso gráfico compuesto

El recurso de gráfico compuesto se basa en las ventajas de los otros recursos compuestos y los amplía con la capacidad de admitir múltiples gráficos en lugar de una sola cascada de subsolicitudes. La solicitud de gráfico compuesto principal no es transaccional en su conjunto, pero cada gráfico es transaccional.
El recurso de gráfico compuesto lleva las operaciones a otra escala con hasta 500 subsolicitudes.

Para ejecutar una solicitud de gráfico compuesto, ejecute una solicitud POST en INSTANCE_URL/services/data/v56.0/composite/batch . Aquí hay un cuerpo de solicitud de ejemplo con dos gráficos ( graph1 y graph2 ) que contienen dos subsolicitudes cada uno:

Esta solicitud hace lo siguiente:

• graph1 crea un "ACME Inc." cuenta y devuelve el registro con todos sus campos (algunos pueden autocompletarse mediante fórmulas o disparadores).
• graph2 recupera una cuenta y le adjunta una oportunidad. Usamos una referencia al nombre de la cuenta principal en el nombre de la oportunidad: "Opportunity for @{refAccount.Name}" .

Esta solicitud produce este tipo de respuesta:

Si bien sus respuestas pueden ser un poco detalladas en comparación con otros recursos compuestos, el recurso gráfico es realmente la solución ideal para realizar operaciones de escritura en hasta 500 registros de manera sincrónica y transaccional.

Si necesita trabajar en más registros, como varios miles de registros hasta millones, debe considerar el procesamiento asíncrono con las API masivas.

Escribir registros con las API masivas

No repetiremos el contenido de la primera parte de esta serie de blogs, ya que la estructura de las solicitudes de la API masiva es muy similar para las operaciones de escritura y lectura. En su lugar, destacaremos algunas pautas importantes para trabajar con actualizaciones masivas de datos a escala.

Cuando se trabaja con grandes cantidades de datos con API masivas, el tiempo de procesamiento es la principal limitación, por lo que desea optimizar sus operaciones para evitar tiempos de espera.

Nota: Como práctica recomendada, simule grandes operaciones de escritura en un espacio aislado antes de aplicarlas a la producción para evaluar y optimizar el tiempo de procesamiento.

Usar compresión

Independientemente del tipo de API masiva que utilice ( original o 2.0 ), asegúrese de habilitar la compresión de respuesta para reducir su tamaño y mejorar el tráfico de red. Todo lo que necesita es agregar un encabezado Accept-Encoding: gzip a sus solicitudes al recuperar conjuntos de resultados.

Minimizar campos y dependencias de objetos

Una serie de factores tienen un alto impacto en el tiempo de procesamiento, incluyendo:

• La cantidad de objetos, campos y relaciones que está modificando
• La cantidad de automatizaciones, como reglas de flujo de trabajo, procesos, flujos y desencadenadores que se ejecutan en los objetos que está modificando.

Intente minimizar esas dependencias para reducir el tiempo de procesamiento. Deshabilitar temporalmente ciertos activadores o automatizaciones al ingerir grandes cantidades de datos es una buena estrategia para acelerar las operaciones de escritura. Dividir lotes grandes en lotes más pequeños también ayuda a reducir el tiempo de procesamiento.

Evite la superposición de trabajos y la contención de bloqueos

La ejecución de varios trabajos y operaciones de escritura en paralelo aumenta el riesgo de bloqueos y congestión. Los bloqueos ocurren cuando un registro se modifica simultáneamente en varias operaciones. Es más probable que las operaciones de escritura en ciertos objetos, como usuarios o roles, creen bloqueos que otros objetos.

Por lo general, Salesforce Platform resuelve automáticamente los bloqueos con un mecanismo de reintento, pero esto provoca algunos retrasos adicionales y puede provocar que las operaciones se agoten cuando se trabaja a gran escala.

En organizaciones grandes, querrá monitorear sus colas de trabajo y programaciones, de modo que pueda programar sus operaciones en consecuencia para evitar la superposición de trabajos.

palabras de cierre

Esto concluye nuestro recorrido por las API masivas y compuestas para operaciones de escritura. Cubrimos cómo las API compuestas le permiten encadenar una serie de operaciones de lectura/escritura compartiendo contexto entre subsolicitudes. También obtuvo una descripción general de los consejos y trucos para aprovechar al máximo los trabajos de ingesta de las API masivas. Puede experimentar fácilmente con esas API gracias a la colección Postman API de Salesforce Platform .

Lo dejaremos con la siguiente tabla que proporciona un buen resumen de las diferencias clave entre estas API para operaciones de escritura.

Recursos

Sobre el Autor

Philippe Ozil es un defensor principal de desarrolladores en Salesforce, donde se enfoca en la plataforma de Salesforce. Escribe contenido técnico y habla con frecuencia en conferencias. Es un desarrollador de pila completa y disfruta trabajar en proyectos DevOps, robótica y realidad virtual. Sígalo en Twitter @PhilippeOzil o consulte sus proyectos de GitHub @pozil .