Account Engagement (Pardot) API v5: Por qué debería actualizar ☁️

¡Account Engagement tiene una nueva API REST brillante! La versión 5 se creó desde cero para facilitar la integración a todos los clientes e ISV. Con una mejor adopción del estándar REST, escritura más estricta y entrada y salida estandarizadas, estoy aquí para decirles que ahora es el momento de actualizar.

Disponible para todas las cuentas, independientemente de AMPSEA

El acceso a las versiones 3 y 4 de la API de compromiso de la cuenta se controló mediante una característica,específicamente Permitir múltiples prospectos con la misma dirección de correo electrónico (AMPSEA) . Los clientes con AMPSEA habilitado se migraron a la versión 4, mientras que los clientes sin AMPSEA tuvieron que usar la versión 3. Al crear la versión 5, queríamos eliminar este problema y proporcionar una API única y unificada que todas las organizaciones pudieran usar. Por lo tanto, todas las organizaciones son elegibles para usar la versión 5 de la API , siempre que tengan acceso a la API, según lo define Pardot Edition . Sin embargo, existen diferencias en cómo responderán ciertos puntos finales en función de AMPSEA. Veamos algunos ejemplos.

Respuesta:

Como puede ver, consultar prospectos por correo electrónico cuando AMPSEA está habilitado puede arrojar más de un resultado .

Consulta de prospectos por correo electrónico, no AMPSEA

Respuesta:

Por el contrario, cuando AMPSEA no está habilitado, la consulta por correo electrónico arrojará un máximo de un resultado . En ambas configuraciones, la consulta por ID no generará más de un resultado .

Selección de campo frente a formatos de salida

La versión 5 de Account Engagement API requiere que las personas que llaman especifiquen los campos de respuesta deseados para cualquier solicitud. Los beneficios aquí son múltiples. Primero, minimización de datos: no saturamos la respuesta con campos que la persona que llama no necesita. En segundo lugar, el rendimiento: diferentes campos pueden tener diferentes características de rendimiento. Por ejemplo, en el objeto de correo electrónico , el campo htmlMessage puede contener megabytes de datos. Recuperar este campo y transmitirlo a la persona que llama desperdiciará tiempo y recursos si no es necesario. En un caso de uso de consulta, donde se pueden devolver hasta 1000 filas, este único campo podría consumir un gigabyte de datos. Para evitar el escenario en el que se agote el tiempo de espera de una consulta, este campo y otros que pueden conducir a datos ilimitados solo se ofrecen cuando se lee un único registro.

Las relaciones son otra característica nueva de la versión 5. Cuando se combinan con Field Selection, ofrecen una poderosa herramienta para que las personas que llaman elaboren respuestas a sus necesidades. Al igual que las relaciones SOQL , permiten a las personas que llaman consultar y estructurar datos de forma personalizada. Las versiones anteriores obligaban a las personas que llamaban a adoptar uno de los cuatro formatos de respuesta : full , simple , mobile o bulk . Si bien son convenientes, estos formatos brindan a las personas que llaman poco control sobre qué campos y relaciones se exponen en el conjunto de datos final y, a menudo, realizan compensaciones de rendimiento ocultas para optimizar una cosa sobre otra. Cuando se utilizan relaciones en combinación con la selección de campos, la persona que llama tiene el control exacto de los datos que desea recibir.

Veamos cómo aprovechar la selección de campos y las relaciones juntas.

Consulta de prospectos con relaciones

Respuesta:

Aquí puede ver cómo estructuramos nuestro parámetro de fields para incluir campos de la campaign y las relaciones assignedTo a. Como se indica en la documentación de Prospects , se puede llamar a cualquier campo cuyo tipo sea otro objeto (representado por un hipervínculo) al consultar o leer un registro . Aquí llamamos a los objetos Campaña y Usuario y especificamos los campos que queremos en la respuesta.

Las relaciones pueden ser encadenadas o incluso recursivas. Algunos objetos, como Carpeta , tienen una referencia a otra Carpeta (la principal). Permitimos hasta tres recorridos de relación por consulta.

Consulta de prospectos con relaciones anidadas

Respuesta:

Aquí puede ver un nivel de estructura relacional que nunca fue posible con versiones anteriores. Las posibilidades de mezclar y combinar datos utilizando el árbol de objetos en la versión 5 son amplias.

Paginación

Para grandes conjuntos de datos, la paginación juega un papel fundamental en la recuperación de datos masivos. Aunque también ofrecemos exportación para grandes conjuntos de datos asíncronos, a veces los usuarios necesitan acceder a datos masivos de forma síncrona. Las versiones anteriores requerían que los usuarios administraran su propia paginación haciendo un seguimiento de las ventanas de filtro o usando offset . Las grandes compensaciones a menudo conducirían a problemas de rendimiento.

Con la versión 5 de la API de Account Engagement, queríamos crear un nuevo enfoque que ofreciera una paginación rápida y confiable para muchos miles de registros sin tener que enfrentar los problemas que se presentaban anteriormente. Introduce la paginación. Al realizar una consulta sobre cualquier objeto, el servidor completará un campo nextPageToken cuando haya más datos disponibles. El token encapsula la información de filtros, límites y orderBy. Para mayor comodidad, se incluye nextPageUrl en el conjunto de resultados con el token ya agregado. El consumidor puede continuar extrayendo los datos en nextPageUrl hasta que este campo y el token se devuelva como null , momento en el cual no habrá más datos.

Con la paginación, los usuarios pueden recuperar hasta 100 000 registros. Cada página puede contener hasta 1000 registros, según el límite especificado en la consulta inicial. Si los volúmenes de datos superan este límite, recomendamos realizar la transición a la API de exportación.

JSON y REST nativo

Si usó las versiones 3 y 4 de la API de Account Engagement, probablemente recuerde que XML es el estándar de salida predeterminado y que los usuarios deben solicitar JSON si así lo desean. ¡No más! La versión 5 admite JSON de forma predeterminada .

Detrás de escena, aquí está ocurriendo una mejora real. Las versiones anteriores en realidad construyeron XML para todas las solicitudes, independientemente del formato solicitado por el usuario. Antes de enviar la respuesta, el XML se convertiría a JSON si fuera necesario. El proceso de conversión trató algunas entradas XML como cadenas y otras como tipos JSON. El proceso era frágil y daría lugar a casos extremos en los que la conversión imperfecta a veces podría causar JSON no válido. Remediar esto de una manera que no cambiara el comportamiento esperado resultó ser un desafío, ya que los envíos de bots para objetos como Visitantes pueden generar una amplia gama de datos que causarán problemas durante la conversión.

La mejor solución fue comenzar desde cero con JSON, así que eso fue exactamente lo que hicimos. El efecto neto de admitir tipos JSON listos para usar debería facilitar a las personas que llaman la integración de puntos finales de Pardot con Apex.

Esperamos que pueda hacer uso de nuestras nuevas herramientas para desarrolladores y que disfrute usando estas herramientas tanto como nosotros disfrutamos construyéndolas.

Sobre el Autor

Adil se unió al equipo de Account Engagement (entonces Pardot) en Salesforce en 2013 y ha sido miembro del equipo de ingeniería de API desde 2018. Ha contribuido al marco de trabajo de la versión 5, así como a las API de importación y exportación. Antes de unirse al equipo de API, Adil lideró los esfuerzos de internacionalización para los mercados japonés y europeo y ayudó a liderar el lanzamiento de Salesforce Engage.