Armazenar e recuperar estado de sessão usando Cloud Datastore no Jitterbit Studio

Introdução

Cloud Datastore é o sistema de armazenamento em nuvem integrado do Jitterbit. Ele permite que operações do Studio persistam e recuperem dados entre execuções sem exigir um banco de dados externo. Este guia aborda o padrão comum para armazenar estado de sessão (como histórico de conversas, sinalizadores por usuário ou contexto entre sessões) usando um armazenamento por chave do Cloud Datastore.

O armazenamento por chave é o tipo de armazenamento apropriado para estado de sessão. Os dados em um armazenamento por chave são retidos até serem explicitamente excluídos, o que significa que os registros persistem indefinidamente entre sessões. Armazenamento de status, por outro lado, é destinado ao rastreamento de status de operações e é automaticamente excluído após 90 dias, tornando-o inadequado para registros de sessão duráveis.

Aviso

Cloud Datastore retorna dados em texto simples. Não armazene senhas, credenciais ou outras informações sensíveis em armazenamentos do Cloud Datastore.

Padrão de design

Três operações implementam o padrão de estado de sessão:

%%{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]

A operação de Consulta procura o registro de sessão por uma chave única (normalmente um ID de usuário ou ID de sessão) e verifica se já existe um registro para essa chave. Uma transformação antes da atividade Query Items define o filtro de consulta, e um script depois dela lê totalItems da resposta de consulta: se o valor for 0, a operação de Inserção é executada para criar um novo registro; se o valor for maior que 0, a operação de Atualização é executada para sobrescrever o registro existente com novos dados de sessão.

Parte 1: Criar o armazenamento por chave

Antes de configurar o conector no Studio, crie um armazenamento por chave e um token de acesso no Console de Gerenciamento.

No portal do Harmony, navegue até Menu do portal Harmony > Console de Gerenciamento > Cloud Datastore.
Na guia Storages, clique em Add Storage e selecione Create Key Storage.
Storage name: Digite um nome para o armazenamento (por exemplo, ConversationHistory).
Environment: Selecione o ambiente que usará este armazenamento. Este campo não pode ser alterado após salvar.
Description: Opcionalmente, digite uma descrição.
Em Fields, clique em Add Field para cada campo customizado necessário para armazenar dados de sessão. Para histórico de conversas, adicione um campo chamado ConversationHistory com o tipo Big Text. Os campos integrados Key, Alternative Key e Value sempre estão presentes e não precisam ser adicionados.

Nota

Um máximo de 20 campos customizados é permitido por armazenamento, e cada item é limitado a 25.000 bytes.
Clique em Save.
Navegue até Menu do portal Harmony > Console de Gerenciamento > Access Tokens e crie um novo token de acesso associado ao mesmo ambiente. Copie o valor do token.

Dica

Armazene o token de acesso como uma variável de projeto com seu valor oculto, depois referencie-o na configuração de conexão. Isso facilita a rotação do token sem editar a conexão diretamente.

Parte 2: Configurar a conexão do Cloud Datastore

No Studio, abra seu projeto e clique na guia Project endpoints and connectors na paleta de componentes de design.
Clique no conector Cloud Datastore para abrir a configuração de conexão.
Connection Name: Digite um nome para a conexão (por exemplo, Cloud Datastore).
Access token: Digite o token de acesso gerado na Parte 1 ou referencie-o usando uma variável de projeto.
Clique em Test para verificar a conexão e depois clique em Save Changes.

Parte 3: Consultar um registro de sessão existente

A operação de Consulta determina se um registro de sessão para o usuário atual já existe.

Configurar a atividade Query Items

Na paleta de componentes de design, expanda o endpoint Cloud Datastore que você criou. Arraste o tipo de atividade Query Items para a tela de design.
Clique duas vezes na atividade para abrir sua configuração.
Name: Digite um nome para a atividade (por exemplo, Query Session).
Select storage: Selecione Select existent storage e clique no armazenamento criado em Part 1 na tabela.
Clique em Next para revisar os esquemas de dados e depois clique em Finished.

Mapear o filtro de consulta em uma transformação

Coloque uma transformação antes da atividade Query Items para definir qual registro procurar. Na transformação:

Mapeie fields.item.key para a string literal "Key". Este é o nome do campo de chave integrado em um armazenamento de chaves e diferencia maiúsculas de minúsculas.
Mapeie fields.item.value para o identificador de sessão (por exemplo, a ID do usuário ou a ID do canal da carga de solicitação de entrada).
Mapeie limit para 1. Espera-se apenas um registro por chave de sessão.

Por exemplo, se a solicitação de entrada fornece a ID do usuário em uma variável userId:

<trans>
$userId
</trans>

Mapeie este nó de script para fields.item.value na transformação.

Verificar o resultado da consulta em um script

Após a atividade Query Items, adicione uma etapa Script à operação. O script lê totalItems da resposta de consulta e roteia a execução para a operação Insert ou Update:

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

Substitua Insert Session e Update Session pelos nomes reais que você atribuir a essas operações em Part 4 e Part 5. A sintaxe <TAG> resolve a operação pelo nome em tempo de execução.

Dica

Para passar a chave de sessão e quaisquer dados de carga para as operações Insert e Update, armazene-os em variáveis globais antes de chamar RunOperation. As variáveis globais persistem durante toda a cadeia de operações.

Part 4: Inserir um registro para uma nova sessão

A operação Insert é executada quando nenhum registro existe para a chave de sessão.

Configurar a atividade Insert Items

Arraste o tipo de atividade Insert Items para uma nova tela de operação.
Clique duas vezes na atividade para abrir sua configuração.
Name: Digite um nome para a atividade (por exemplo, Insert Session).
Select storage: Selecione o mesmo armazenamento usado em Part 3.
Clique em Next para revisar os esquemas de dados e depois clique em Finished.

Mapear os dados da sessão

Na transformação que precede a atividade Insert Items, mapeie os seguintes campos de solicitação:

Key: Mapeie para o identificador de sessão (por exemplo, userId). Este é o valor usado para procurar o registro em futuras consultas.
ConversationHistory (ou quaisquer campos personalizados que seu armazenamento defina): Mapeie para os dados de sessão iniciais a serem armazenados.

Deixe AlternativeKey e Value não mapeados, a menos que seu caso de uso os exija.

Part 5: Atualizar um registro de sessão existente

A operação Update é executada quando um registro para a chave de sessão já existe.

Configurar a atividade Update Items

Arraste o tipo de atividade Update Items para uma nova tela de operação.
Clique duas vezes na atividade para abrir sua configuração.
Name: Digite um nome para a atividade (por exemplo, Update Session).
Select storage: Selecione o mesmo armazenamento usado em Part 3.
Clique em Next para revisar os esquemas de dados e depois clique em Finished.

Mapear os dados de sessão atualizados

Na transformação que precede a atividade Update Items, mapeie os seguintes campos de solicitação:

Key: Mapeie para o identificador de sessão. Este campo identifica qual registro atualizar: deve corresponder ao valor usado quando o registro foi inserido.
ConversationHistory (ou quaisquer campos personalizados que seu armazenamento defina): Mapeie para os dados de sessão atualizados. Todos os campos mapeados são sobrescritos.

Nota

A atividade Update Items identifica o registro a atualizar usando o campo Key. Se nenhum registro com essa chave existir, a atualização é concluída com sucesso silenciosamente sem criar um novo registro. Sempre confirme o resultado da Query antes de chamar a operação de Update.

Verificar a integração

Implante e execute a operação Query manualmente, passando um identificador de sessão que ainda não exista no armazenamento.
No log de operação, confirme que totalItems é 0 e que a operação Insert foi acionada.
Em Management Console > Cloud Datastore, abra os detalhes do armazenamento e confirme que um novo registro com a chave esperada e os valores dos campos aparece.
Implante e execute a operação Query novamente com o mesmo identificador de sessão.
No log de operação, confirme que totalItems é 1 e que a operação Update foi acionada.
Em Management Console > Cloud Datastore, confirme que os campos personalizados do registro refletem os valores atualizados.
Se a atividade Query falhar com um erro de autenticação, verifique o token de acesso na conexão Cloud Datastore e confirme que o token está associado ao mesmo ambiente que o armazenamento.

Dica

Para limpar dados de sessão ao final de uma conversa, adicione uma quarta operação usando uma atividade Delete Items que aponte para o registro pela Key. Isso evita que o armazenamento acumule registros obsoletos.

O Cloud Datastore também pode ser usado para deduplicação entre execuções em alto volume, como alternativa às funções de cache. Consulte Detectar e desduplicar registros usando funções de hash.