Melhores práticas de integração para desenvolvedores na Digibee Integration Platform

Neste caso de uso, você vai explorar as melhores práticas de integração, essenciais para desenvolvedores de todos os níveis. Este documento aborda diretrizes para garantir que suas integrações sejam eficazes, escaláveis e seguras, com foco na Digibee Integration Platform

A ênfase será dada a três pilares essenciais:

1. Melhorar a depuração com práticas de solução de problemas mais eficazes.

2. Garantir a consistência dos dados por meio da validação de payloads.

3. Validar respostas de chamadas externas.

Melhorando o debugging com práticas mais eficazes de troubleshooting

O debugging é essencial para manter os fluxos de integração. Uma maneira de alcançar isso é melhorando a visibilidade dos seus payloads durante a execução. O conector Log desempenha um papel fundamental nesse processo, tornando o troubleshooting mais fácil.

Para maximizar a eficácia dos logs, é importante posicioná-los estrategicamente dentro de suas integrações. Por exemplo:

• No início de um pipeline acionado por evento para monitorar o payload de entrada.

• Nas saídas de um Choice para acompanhar o "caminho" que a integração segue.

• Como o primeiro conector nos subfluxos onProcess e onException para rastrear o subprocesso pelo qual a execução está passando.

• Antes de fazer chamadas externas, para rastrear as informações sendo enviadas na requisição.

A ilustração mostra o conector Log em cada caminho após um Choice.	A ilustração mostra o conector Log antes de uma requisição POST.

Melhores práticas para usar o conector Log

1. Atribua um nome descritivo (step name) ao conector.

2. Se o conector Log vier após um Choice, o nomeie de acordo com o "caminho" específico ao qual ele está conectado.

3. Escolha o nível de log apropriado (Info, Error ou Warning), pois ele aparecerá nos logs da área de Monitor.

4. Use o conector Log com cautela dentro de conectores de loop (por exemplo, For Each, Stream) para evitar um volume excessivo de logs, que pode sobrecarregar a memória do pipeline.

5. Registre apenas dados relevantes para minimizar a exposição de informações sensíveis. Por exemplo: {{ message.id }} em vez de {{ message.$ }}.

6. Proteja informações sensíveis aplicando configurações de campo sensível para ofuscar esses campos no Monitor usando caracteres “***”. Isso pode ser configurado nas configurações do pipeline no Canvas ou por meio de uma política de campos sensíveis para todo o realm.

A ilustração mostra a configuração do conector Log com os diferentes níveis de log disponíveis.	A ilustração acima mostra a configuração do pipeline com o campo de entrada Sensitive Field, especificando os campos que serão ofuscados na tela de Monitor.

Garantindo a consistência dos dados por meio da validação de payloads

Para alcançar conformidade de dados, você deve implementar a validação como parte do processo de integração. O conector Validator V2 é usado para aplicar a validação da estrutura de dados com base em um esquema JSON pré-definido. Esse conector deve ser posicionado estrategicamente no pipeline, geralmente após o recebimento dos dados e antes de qualquer chamada externa que exija uma estrutura de payload específica.

Passos para Implementação

1. Coloque o conector Validator V2 no pipeline no ponto em que você precisa verificar a estrutura de um dado específico.

2. Selecione a versão do Schema apropriada para o seu caso de uso ou ative a opção Detect Draft Version para detectar automaticamente a versão a partir do esquema fornecido.

3. No campo JSON Payload, insira o conteúdo JSON que precisa ser validado (esse campo aceita funções com Double Braces).

4. No campo JSON Schema, insira o esquema JSON que será usado para validar o conteúdo JSON.

   1. Se o conector validar com sucesso o conteúdo JSON, ele retornará o JSON configurado no parâmetro JSON Payload.

   2. Em caso de erro, o conector retornará um atributo "success": false e um objeto validation” contendo os detalhes do erro.

Para ajudar na criação dos seus schemas, use a ferramenta JSON Schema Tool.

A ilustração acima mostra uma resposta de erro do conector Validator V2, acionada quando o payload não atende aos critérios de verificação dos atributos exigidos.

A ilustração acima mostra uma resposta de erro do conector Validator V2, acionada quando o payload não atende aos critérios de verificação dos atributos exigidos.

Validando interações com serviços externos

Validar chamadas externas é crucial para garantir que as respostas sejam tratadas de forma adequada. Por exemplo, uma chamada REST com diferentes códigos de status, como 200 ou 500, pode exigir tratamentos distintos. Da mesma forma, uma chave de erro na resposta pode indicar a necessidade de um tratamento de erro específico. Garantir o roteamento correto do payload com base no tipo de resposta ajuda a evitar problemas no fluxo de integração.

Quando validar

Para conectores REST, SOAP e similares, entender o que verificar é apenas o primeiro passo — você também precisa saber como realizar essas verificações. Duas abordagens comuns são:

1. Usando o conector Assert: Este conector verifica se os dados recebidos atendem a condições específicas de validação. Se a verificação falhar, o pipeline aciona um erro, e a execução é interrompida.

2. Usando o conector Choice: Em vez de interromper imediatamente o pipeline ao encontrar um erro, permite que você ramifique o fluxo e realize o tratamento de erro adequado antes de decidir se a execução deve ser interrompida ou continuada.

• Verificações comuns incluem:

  • Verificar um atributo error no payload de resposta após realizar a requisição.

  • Verificar o código de status HTTP.

A ilustração mostra o conector Log para cada caminho após um Choice.	A ilustração mostra o conector Assert após uma chamada externa.

3. Conectores de banco de dados (DB V2, Object Store e similares): Para operações de banco de dados, valide a resposta verificando os seguintes atributos:

• rowCount e updateCount: Certifique-se de que eles são diferentes de zero, dependendo da operação realizada.

Considerações importantes

• Ao usar o conector Assert, o fluxo será interrompido se os dados não atenderem à condição de validação, e o pipeline marcará a execução com o status de ERRO no log.

• Para situações em que você precisa parar o pipeline com uma mensagem de erro personalizada, use o conector Throw Error. Ele permite definir uma mensagem de erro específica e retornar um código de status HTTP correspondente na resposta.

Considerações Finais

Ao seguir estas melhores práticas, você estará no caminho certo para criar integrações eficientes, seguras e escaláveis. Implementar essas práticas em seus fluxos de trabalho aprimora a confiabilidade de seus pipelines, minimiza erros e, em última análise, melhora a escalabilidade de suas soluções.

Você pode explorar mais possibilidades em nosso Portal de Documentação, Digibee Academy ou visitar nosso Blog para descobrir mais recursos e insights.

Se você tiver um feedback sobre este caso de uso ou sugestões para futuros artigos, adoraríamos ouvir você em nosso formulário de feedback.