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

Introdução

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

O armazenamento de chaves é o tipo de armazenamento apropriado para o estado da sessão. Os dados em um armazenamento de chaves são retidos até serem explicitamente excluídos, o que significa que os registros persistem indefinidamente entre as sessões. O 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.

Padrão de design

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

A operação de Consulta procura o registro da sessão por uma chave única (tipicamente 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 Consultar Itens define o filtro da consulta, e um script após isso lê totalItems da resposta da consulta: se o valor for 0, a operação de Inserir é executada para criar um novo registro; se o valor for maior que 0, a operação de Atualizar é executada para sobrescrever o registro existente com novos dados da sessão.

Parte 1: Criar o armazenamento de chaves

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

1. No portal Harmony, navegue até Menu do portal Harmony > Console de Gerenciamento > Cloud Datastore.

2. Na aba Armazenamentos, clique em Adicionar Armazenamento, e então selecione Criar Armazenamento de Chaves.

3. Nome do armazenamento: Insira um nome para o armazenamento (por exemplo, ConversationHistory).

4. Ambiente: Selecione o ambiente que usará este armazenamento. Este campo não pode ser alterado após a gravação.

5. Descrição: Opcionalmente, insira uma descrição.

6. Em Campos, clique em Adicionar Campo para cada campo personalizado necessário para armazenar dados da sessão. Para o histórico de conversas, adicione um campo chamado ConversationHistory com o tipo Texto Grande. Os campos embutidos Chave, Chave Alternativa e Valor estão sempre presentes e não precisam ser adicionados.

   Nota

   Um máximo de 20 campos personalizados é permitido por armazenamento, e cada item é limitado a 25.000 bytes.

7. Clique em Salvar.

8. Navegue até Menu do portal Harmony > Console de Gerenciamento > Tokens de Acesso e crie um novo token de acesso com escopo para o mesmo ambiente. Copie o valor do token.

   Dica

   Armazene o token de acesso como uma variável de projeto com seu valor oculto, e então faça referência a ele na configuração da conexão. Isso facilita a rotação do token sem editar a conexão diretamente.

Parte 2: Configurar a conexão do Cloud Datastore

1. No Studio, abra seu projeto e clique na aba Endpoints e conectores do projeto no palete de componentes de design.

2. Clique no conector Cloud Datastore para abrir a configuração da conexão.

3. Nome da Conexão: Insira um nome para a conexão (por exemplo, Cloud Datastore).

4. Token de acesso: Insira o token de acesso gerado na Parte 1, ou faça referência a ele usando uma variável de projeto.

5. Clique em Testar para verificar a conexão, e então clique em Salvar Alterações.

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 Itens de Consulta

1. No painel de componentes de design, expanda o endpoint do Cloud Datastore que você criou. Arraste o tipo de atividade Query Items para o canvas de design.

2. Clique duas vezes na atividade para abrir sua configuração.

3. Nome: Insira um nome para a atividade (por exemplo, Query Session).

4. Selecionar armazenamento: Selecione Selecionar armazenamento existente, em seguida, clique no armazenamento criado na Parte 1 na tabela.

5. Clique em Próximo para revisar os esquemas de dados, em seguida, clique em Concluído.

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 embutido em um armazenamento de chave e é sensível a maiúsculas e minúsculas.
• Mapeie fields.item.value para o identificador da sessão (por exemplo, o ID do usuário ou o ID do canal do payload da solicitação de entrada).
• Mapeie limit para 1. Apenas um registro por chave de sessão é esperado.

Por exemplo, se a solicitação de entrada fornecer o 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 um passo de Script à operação. O script lê totalItems da resposta da consulta e direciona a execução para a operação de Inserir ou Atualizar:

<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ê dá a essas operações na Parte 4 e Parte 5. A sintaxe <TAG> resolve a operação pelo nome em tempo de execução.

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

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

Configurar a atividade Inserir Itens

1. Arraste o tipo de atividade Inserir Itens para uma nova tela de operação.

2. Clique duas vezes na atividade para abrir sua configuração.

3. Nome: Insira um nome para a atividade (por exemplo, Inserir Sessão).

4. Selecionar armazenamento: Selecione o mesmo armazenamento usado na Parte 3.

5. Clique em Próximo para revisar os esquemas de dados e, em seguida, clique em Concluído.

Mapear os dados da sessão

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

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

Deixe AlternativeKey e Value sem mapeamento, a menos que seu caso de uso exija.

Parte 5: Atualizar um registro de sessão existente

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

Configurar a atividade Atualizar Itens

1. Arraste o tipo de atividade Atualizar Itens para uma nova tela de operação.

2. Clique duas vezes na atividade para abrir sua configuração.

3. Nome: Insira um nome para a atividade (por exemplo, Atualizar Sessão).

4. Selecionar armazenamento: Selecione o mesmo armazenamento usado na Parte 3.

5. Clique em Próximo para revisar os esquemas de dados e, em seguida, clique em Concluído.

Mapear os dados da sessão atualizados

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

• Key: Mapeie para o identificador da 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 atualizados da sessão. Todos os campos mapeados são sobrescritos.

Verificar a integração

1. Implantar e executar a operação de Consulta manualmente, passando um identificador de sessão que ainda não existe no armazenamento.

2. No registro de operações, confirme que totalItems é 0 e que a operação de Inserção foi acionada.

3. Em Console de Gerenciamento > Cloud Datastore, abra os detalhes do armazenamento e confirme que um novo registro com a chave e os valores de campo esperados aparece.

4. Implemente e execute a operação de Consulta novamente com o mesmo identificador de sessão.

5. No registro de operações, confirme que totalItems é 1 e que a operação de Atualização foi acionada.

6. Em Console de Gerenciamento > Cloud Datastore, confirme que os campos personalizados do registro refletem os valores atualizados.

7. Se a atividade Consulta falhar com um erro de autenticação, verifique o token de acesso na conexão do Cloud Datastore e confirme que o token está associado ao mesmo ambiente que o armazenamento.

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