Almacenar y recuperar el estado de la sesión usando Cloud Datastore en Jitterbit Studio

Introducción

Cloud Datastore es el sistema de almacenamiento en la nube integrado de Jitterbit. Permite que las operaciones de Studio persistan y recuperen datos entre ejecuciones sin requerir una base de datos externa. Esta guía cubre el patrón común para almacenar el estado de la sesión (como el historial de conversaciones, banderas por usuario o contexto entre sesiones) utilizando un almacenamiento de claves de Cloud Datastore.

El almacenamiento de claves es el tipo de almacenamiento apropiado para el estado de la sesión. Los datos en un almacenamiento de claves se retienen hasta que se eliminan explícitamente, lo que significa que los registros persisten indefinidamente entre sesiones. El almacenamiento de estados, en contraste, está destinado a rastrear los estados de operación y se elimina automáticamente después de 90 días, lo que lo hace inadecuado para registros de sesión duraderos.

Patrón de diseño

Tres operaciones implementan el patrón de estado de sesión:

La operación de Consulta busca el registro de la sesión por una clave única (típicamente un ID de usuario o ID de sesión) y verifica si ya existe un registro para esa clave. Una transformación antes de la actividad Consultar Elementos establece el filtro de consulta, y un script después de esta lee totalItems de la respuesta de la consulta: si el valor es 0, se ejecuta la operación de Insertar para crear un nuevo registro; si el valor es mayor que 0, se ejecuta la operación de Actualizar para sobrescribir el registro existente con nuevos datos de sesión.

Parte 1: Crear el almacenamiento de claves

Antes de configurar el conector en Studio, cree un almacenamiento de claves y un token de acceso en la Consola de Administración.

1. En el portal de Harmony, navegue a Menú del portal de Harmony > Consola de Administración > Cloud Datastore.

2. En la pestaña Almacenamientos, haga clic en Agregar Almacenamiento, luego seleccione Crear Almacenamiento de Claves.

3. Nombre del almacenamiento: Ingresa un nombre para el almacenamiento (por ejemplo, ConversationHistory).

4. Entorno: Selecciona el entorno que utilizará este almacenamiento. Este campo no se puede cambiar después de guardar.

5. Descripción: Opcionalmente, ingresa una descripción.

6. Bajo Campos, haz clic en Agregar campo para cada campo personalizado necesario para almacenar datos de sesión. Para el historial de conversaciones, agrega un campo llamado ConversationHistory con el tipo Texto grande. Los campos incorporados Key, Alternative Key y Value siempre están presentes y no necesitan ser añadidos.

   Nota

   Se permite un máximo de 20 campos personalizados por almacenamiento, y cada ítem está limitado a 25,000 bytes.

7. Haz clic en Guardar.

8. Navega a Menú del portal Harmony > Consola de administración > Tokens de acceso y crea un nuevo token de acceso con el mismo ámbito del entorno. Copia el valor del token.

   Consejo

   Almacena el token de acceso como una variable de proyecto con su valor oculto, luego haz referencia a él en la configuración de la conexión. Esto facilita la rotación del token sin editar la conexión directamente.

Parte 2: Configurar la conexión de Cloud Datastore

1. En Studio, abre tu proyecto y haz clic en la pestaña Puntos finales y conectores del proyecto en la paleta de componentes de diseño.

2. Haz clic en el conector Cloud Datastore para abrir la configuración de la conexión.

3. Nombre de la conexión: Ingresa un nombre para la conexión (por ejemplo, Cloud Datastore).

4. Token de acceso: Ingresa el token de acceso generado en Parte 1, o haz referencia a él usando una variable de proyecto.

5. Haz clic en Probar para verificar la conexión, luego haz clic en Guardar cambios.

Parte 3: Consultar un registro de sesión existente

La operación de consulta determina si ya existe un registro de sesión para el usuario actual.

Configurar la actividad de elementos de consulta

1. En la paleta de componentes de diseño, expande el endpoint de Cloud Datastore que creaste. Arrastra el tipo de actividad Query Items al lienzo de diseño.

2. Haz doble clic en la actividad para abrir su configuración.

3. Nombre: Ingresa un nombre para la actividad (por ejemplo, Query Session).

4. Seleccionar almacenamiento: Selecciona Seleccionar almacenamiento existente, luego haz clic en el almacenamiento creado en Parte 1 en la tabla.

5. Haz clic en Siguiente para revisar los esquemas de datos, luego haz clic en Finalizado.

Mapear el filtro de consulta en una transformación

Coloca una transformación antes de la actividad Query Items para definir qué registro buscar. En la transformación:

• Mapea fields.item.key a la cadena literal "Key". Este es el nombre del campo clave incorporado en un almacenamiento de clave y es sensible a mayúsculas y minúsculas.
• Mapea fields.item.value al identificador de sesión (por ejemplo, el ID de usuario o el ID de canal del payload de la solicitud entrante).
• Mapea limit a 1. Se espera solo un registro por clave de sesión.

Por ejemplo, si la solicitud entrante proporciona el ID de usuario en una variable userId:

<trans>
$userId
</trans>

Mapea este nodo de script a fields.item.value en la transformación.

Verificar el resultado de la consulta en un script

Después de la actividad Query Items, agrega un paso de Script a la operación. El script lee totalItems de la respuesta de la consulta y dirige la ejecución a la operación de Insertar o Actualizar:

<trans>
if(Source.json.pagination.totalItems == 0,
  RunOperation("<TAG>Operations/Insert Session</TAG>"),
  RunOperation("<TAG>Operations/Update Session</TAG>")
);
</trans>

Reemplaza Insert Session y Update Session con los nombres reales que les des a esas operaciones en Parte 4 y Parte 5. La sintaxis <TAG> resuelve la operación por nombre en tiempo de ejecución.

Parte 4: Insertar un registro para una nueva sesión

La operación de Inserción se ejecuta cuando no existe un registro para la clave de sesión.

Configurar la actividad Insertar Elementos

1. Arrastra el tipo de actividad Insertar Elementos a un nuevo lienzo de operación.

2. Haz doble clic en la actividad para abrir su configuración.

3. Nombre: Ingresa un nombre para la actividad (por ejemplo, Insertar Sesión).

4. Seleccionar almacenamiento: Selecciona el mismo almacenamiento utilizado en Parte 3.

5. Haz clic en Siguiente para revisar los esquemas de datos, luego haz clic en Finalizado.

Mapear los datos de la sesión

En la transformación que precede a la actividad Insertar Elementos, mapea los siguientes campos de solicitud:

• Key: Mapea al identificador de sesión (por ejemplo, userId). Este es el valor utilizado para buscar el registro en consultas futuras.
• ConversationHistory (o cualquier campo personalizado que defina tu almacenamiento): Mapea a los datos iniciales de la sesión que se van a almacenar.

Deja AlternativeKey y Value sin mapear a menos que tu caso de uso lo requiera.

Parte 5: Actualizar un registro de sesión existente

La operación de Actualización se ejecuta cuando ya existe un registro para la clave de sesión.

Configurar la actividad Actualizar Elementos

1. Arrastra el tipo de actividad Actualizar Elementos a un nuevo lienzo de operación.

2. Haz doble clic en la actividad para abrir su configuración.

3. Nombre: Ingresa un nombre para la actividad (por ejemplo, Actualizar Sesión).

4. Seleccionar almacenamiento: Selecciona el mismo almacenamiento utilizado en Parte 3.

5. Haz clic en Siguiente para revisar los esquemas de datos, luego haz clic en Finalizado.

Mapear los datos de sesión actualizados

En la transformación que precede a la actividad Actualizar Elementos, mapea los siguientes campos de solicitud:

• Key: Mapea al identificador de sesión. Este campo identifica qué registro actualizar: debe coincidir con el valor utilizado cuando se insertó el registro.
• ConversationHistory (o cualquier campo personalizado que defina tu almacenamiento): Mapea a los datos actualizados de la sesión. Todos los campos mapeados se sobrescriben.

Verify the integration

1. Deploy and run la operación de consulta manualmente, pasando un identificador de sesión que aún no existe en el almacenamiento.

2. En el operation log, confirma que totalItems es 0 y que se activó la operación de Insert.

3. En Management Console > Cloud Datastore, abre los detalles del almacenamiento y confirma que aparece un nuevo registro con la clave y los valores de campo esperados.

4. Despliega y ejecuta la operación de consulta nuevamente con el mismo identificador de sesión.

5. En el operation log, confirma que totalItems es 1 y que se activó la operación de Update.

6. En Management Console > Cloud Datastore, confirma que los campos personalizados del registro reflejan los valores actualizados.

7. Si la actividad Query falla con un error de autenticación, verifica el token de acceso en la conexión de Cloud Datastore y confirma que el token está asociado con el mismo entorno que el almacenamiento.

Cloud Datastore también se puede utilizar para deduplicación entre ejecuciones a gran volumen, como una alternativa a las funciones de caché. Consulta Detect and deduplicate records using hash functions.