Saltar al contenido

Almacenar y recuperar estado de 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 estado de sesión (como historial de conversación, indicadores por usuario o contexto entre sesiones) usando un almacenamiento de clave de Cloud Datastore.

El almacenamiento de clave es el tipo de almacenamiento apropiado para el estado de sesión. Los datos en un almacenamiento de clave se retienen hasta que se eliminan explícitamente, lo que significa que los registros persisten indefinidamente entre sesiones. El almacenamiento de estado, por el contrario, está diseñado para 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.

Advertencia

Cloud Datastore devuelve datos en texto plano. No almacenes contraseñas, credenciales u otra información sensible en los almacenamientos de Cloud Datastore.

Patrón de diseño

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

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Transformation] --> B[Query Items] --> C[Script] C -->|"No record found"| D[Transformation] --> E[Insert Items] C -->|"Record found"| F[Transformation] --> G[Update Items]

La operación Query busca el registro de 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 Query Items establece el filtro de consulta, y un script después de ella lee totalItems de la respuesta de consulta: si el valor es 0, se ejecuta la operación Insert para crear un nuevo registro; si el valor es mayor que 0, se ejecuta la operación Update para sobrescribir el registro existente con nuevos datos de sesión.

Parte 1: Crear el almacenamiento de clave

Antes de configurar el conector en Studio, crea un almacenamiento de clave y un token de acceso en la Consola de administración.

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

  2. En la pestaña Almacenamientos, haz clic en Agregar almacenamiento y luego selecciona Crear almacenamiento de clave.

  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. En Campos, haz clic en Agregar campo para cada campo personalizado necesario para almacenar datos de sesión. Para el historial de conversación, agrega un campo denominado ConversationHistory con el tipo Texto grande. Los campos integrados Key, Alternative Key y Value siempre están presentes y no necesitan ser agregados.

    Nota

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

  7. Haz clic en Guardar.

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

    Consejo

    Almacena el token de acceso como una variable de proyecto con su valor oculto, y luego hazle referencia en la configuración de 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 de conexión del proyecto y conectores en la paleta de componentes de diseño.

  2. Haz clic en el conector Cloud Datastore para abrir la configuración de 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 la Parte 1, o hazle referencia usando una variable de proyecto.

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

Parte 3: Consultar un registro de sesión existente

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

Configurar la actividad Query Items

  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. Name: Ingresa un nombre para la actividad (por ejemplo, Query Session).

  4. Select storage: Selecciona Select existent storage, luego haz clic en el almacenamiento creado en Part 1 en la tabla.

  5. Haz clic en Next para revisar los esquemas de datos, luego haz clic en Finished.

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 de clave integrado en un almacenamiento de clave y distingue mayúsculas de minúsculas.
  • Mapea fields.item.value al identificador de sesión (por ejemplo, el ID de usuario o ID de canal de la carga útil 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 Script a la operación. El script lee totalItems de la respuesta de consulta y dirige la ejecución a la operación Insert o Update:

<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 des a esas operaciones en Part 4 y Part 5. La sintaxis <TAG> resuelve la operación por nombre en tiempo de ejecución.

Sugerencia

Para pasar la clave de sesión y cualquier dato de carga útil a las operaciones Insert y Update, guárdalos en variables globales antes de llamar a RunOperation. Las variables globales persisten durante toda la cadena de operaciones.

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

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

Configurar la actividad Insert Items

  1. Arrastra el tipo de actividad Insert Items a un nuevo lienzo de operación.

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

  3. Name: Ingresa un nombre para la actividad (por ejemplo, Insert Session).

  4. Select storage: Selecciona el mismo almacenamiento utilizado en Part 3.

  5. Haz clic en Next para revisar los esquemas de datos, luego haz clic en Finished.

Mapear los datos de sesión

En la transformación que precede a la actividad Insert Items, 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 futuras consultas.
  • ConversationHistory (o cualquier campo personalizado que defina tu almacenamiento): Mapea a los datos de sesión iniciales a almacenar.

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

Part 5: Actualizar un registro de sesión existente

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

Configurar la actividad Update Items

  1. Arrastra el tipo de actividad Update Items a un nuevo lienzo de operación.

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

  3. Name: Ingresa un nombre para la actividad (por ejemplo, Update Session).

  4. Select storage: Selecciona el mismo almacenamiento utilizado en Part 3.

  5. Haz clic en Next para revisar los esquemas de datos, luego haz clic en Finished.

Mapear los datos de sesión actualizados

En la transformación que precede a la actividad Update Items, 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 de sesión actualizados. Todos los campos mapeados se sobrescriben.

Nota

La actividad Update Items coincide con el registro a actualizar utilizando el campo Key. Si no existe ningún registro con esa clave, la actualización se completa sin generar errores y sin crear un nuevo registro. Siempre confirma el resultado de la consulta antes de llamar a la operación de actualización.

Verificar la integración

  1. Implementa y ejecuta la operación de consulta manualmente, pasando un identificador de sesión que aún no exista en el almacenamiento.

  2. En el registro de operaciones, confirma que totalItems es 0 y que se activó la operación de inserción.

  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. Implementa y ejecuta nuevamente la operación de consulta con el mismo identificador de sesión.

  5. En el registro de operaciones, confirma que totalItems es 1 y que se activó la operación de actualización.

  6. En Management Console > Cloud Datastore, confirma que los campos personalizados del registro reflejen 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 al mismo ambiente que el almacenamiento.

Consejo

Para limpiar datos de sesión al final de una conversación, agrega una cuarta operación utilizando una actividad Delete Items que se dirija al registro por Key. Esto evita que el almacenamiento acumule registros obsoletos.

Cloud Datastore también se puede utilizar para deduplicación entre ejecuciones a alto volumen, como alternativa a las funciones de caché. Consulta Detectar y deduplicar registros utilizando funciones hash.