Projeto 1 - Integração utilizando SOAP Inbound Adapter

A idéia deste novo conjunto de postagens é apresentar uma série de integrações utilizando o InterSystems IRIS. Vamos ver integrações REST, SOAP, utilizando adaptadores ODBC, Arquivos e outros.

Vamos montar nossa primeira integração completa, passando pelas camadas de BS, BP e BO, e devolvendo a resposta esperada. Vamos montar essa nossa primeira integração utilizando o SOAP como o adaptador de entrada, e como cliente vamos utilizar o SoapUI.

Vamos então começar:

1. SoapUI

Projeto 8 – REST Outbound Adapter

Olá. Vamos montar nossa próxima integração utilizando o adaptador SOAP Inbound Adapter chamando um BP que chamará um BO que utilizará o REST Outbound Adapter.

O BO que vamos construir irá chamar o nosso BS que montamos no artigo https://pt.community.intersystems.com/post/desenvolvendo-integra%C3%A7%C3%B5es-com-o-intersystems-iris-aplica%C3%A7%C3%A3o-rest mas, importante, note que poderíamos chamar qualquer serviço interno no nosso integrador ou outra instância IRIS, ou externo em qualquer outro sistema com esse adaptador.

Projeto 7 – SQL Outbound Adapter

Vamos montar nossa próxima integração utilizando o adaptador SQL Onbound Adapter. Vamos criar um BS que utilizará o SOAP Inbound Adapter, que vai chamar dois BPs que por sua vez chamarão um BO que utilizará o SQL Outbound Adapter. Nosso BS terá duas capacidades: incluir e consultar. Cada capacidade chamará um BP diferente, porém os dois BPs chamarão o mesmo BO, que também terá duas capacidades. Cada capacidade será chamada de acordo com a mensagem recebida.

Vamos começar verificando a tabela que será acessada. Vamos cria-la utilizando o modelo abaixo:

Projeto 6 – Chamada Assíncrona no BP

Vamos montar nossa próxima integração utilizando o adaptador SOAP Inbound Adapter chamando um BP que vai orquestrar chamadas a dois BOs em modo assíncrono.

Vamos começar criando as mensagens de Request e Response do nosso serviço:

Class ws.credito.msg.Request Extends Ens.Request
{
Property cpf As %String(PATTERN = "1N.N");
}

Projeto 5 – SOAP Outbound Adapter

Vamos montar nossa próxima integração utilizando o adaptador SOAP Outbound Adapter. Este adaptador permite acessar um serviço SOAP externo e consumir este serviço.

No nosso exemplo vamos publicar um serviço SOAP no barramento de integração simulando um serviço externo. Vamos então consumir o WSDL deste serviço criando o BO automaticamente, e depois montaremos os BP e BS da integração.

Neste artigo, vou abordar o teste e a depuração dos aplicativos da Web Caché (principalmente REST) com ferramentas externas. A segunda parte abrange ferramentas de Caché.

Você escreveu um código do servidor e quer testar em um cliente ou já tem um aplicativo da Web e ele não funciona. É aqui que entra a depuração. Neste artigo, vou mostrar desde as ferramentas mais fáceis de usar (navegador) até as mais completas (analisador de pacotes). Porém, primeiro, vamos falar um pouco sobre os erros mais comuns e como eles podem ser resolvidos.

Erros

401 Não Autorizado

Acho que é o erro encontrado com mais frequência ao implantar para a produção. O servidor de desenvolvimento local geralmente tem uma configuração de segurança mínima ou normal, mas convencional. No entanto, o servidor de produção pode ter um esquema mais restritivo. Portanto:

• Confira se você fez login
• Confira se o usuário tem acesso ao banco de dados/tabela/procedimento/linha/coluna que você quer acessar
• Confira se a solicitação OPTIONS pode ser realizada por um usuário não autorizado

404 Não Encontrado

Confira:

• Se o url está correto
• Caso seja um aplicativo novo e você esteja usando um servidor da Web externo, recarregar o servidor da Web pode ajudar

Erros do aplicativo

De certa forma, é o mais fácil de encontrar — o stack trace ajuda. A resolução é completamente específica ao aplicativo.

Ferramentas de depuração

Navegador da Web

A principal ferramenta de depuração sempre disponível é o navegador da Web, de preferência o Chrome, mas o Firefox também é suficiente. As solicitações GET podem ser testadas ao inserir o URL na barra de endereço, todas as outras solicitações exigem um aplicativo da Web ou a escrita de código js. A abordagem geral é:

• Pressione F12 para abrir as ferramentas de desenvolvedor.
• Acesse a guia Network (Rede).
• Marque a caixa de seleção "Preserve Log" (Preservar registro), se não estiver selecionada.
• Exiba apenas solicitações XHR.
• Realize a ação com problemas no aplicativo da Web.

Depois, você pode examinar as solicitações e reenviá-las. O Firefox também pode editar as solicitações antes de repeti-las.

Vantagens:

• Sempre disponível
• Fácil de usar (os usuários finais podem enviar capturas de tela das guias Network e Console)
• É um ambiente de usuário final

Desvantagens:

• Não mostra respostas parcialmente enviadas/corrompidas/etc.
• Lento para respostas grandes
• Lento para um número grande de respostas
• Tudo é feito manualmente

Cliente REST

O cliente REST é um aplicativo da Web independente ou um complemento do navegador da Web criado especificamente para testar aplicativos da Web. Eu uso Postman, mas há muitos outros. Veja como é a depuração no Postman:

O Postman trabalha com solicitações agrupadas em coleções. A solicitação pode ser enviada no ambiente. O ambiente é uma coleção de variáveis. Por exemplo, no meu ambiente CACHE@localhost, a variável do host está definida como localhost e o usuário como _SYSTEM. Quando a solicitação é enviada, as variáveis são substituídas pelos seus valores para o ambiente escolhido e a solicitação é enviada.

Confira um exemplo de coleção e ambiente para o projeto MDX2JSON.

Vantagens:

• Escreva uma única vez e use em todos os lugares
• Melhor controle sobre a solicitação
• Embelezamento das respostas

Desvantagens:

• <s>A depuração de solicitações em cadeia (a resposta à request1 pode forçar a request2 ou request 2B) ainda é manual</s> (Atualização de 22 de fevereiro: possível no Postman)
• Às vezes, falha com respostas parcialmente enviadas/corrompidas/etc.

Proxy de depuração HTTP

Um aplicativo independente que registra tráfego HTTP(S). As solicitações registradas podem ser modificadas e reenviadas. Eu uso Charles e Fiddler.

Vantagens:

• Processa respostas parcialmente enviadas/corrompidas/etc.
• Embelezamento das respostas
• Melhor suporte para tráfego HTTPS (do que no analisador de pacotes)
• Consegue capturar sessões

Desvantagens:

• Algo (aplicativo da Web/cliente REST/código JS) é necessário para enviar a solicitação

Analisador de pacotes

Um programa de computador consegue interceptar e registrar o tráfego transmitido por uma rede. Com os fluxos de dados fluindo em toda a rede, o sniffer captura cada pacote e, se necessário, decodifica os dados brutos do pacote. Essa é a opção mais completa, mas também exige um pouco de habilidade para a operação adequada. Eu uso o WireShark. Veja um breve guia sobre a instalação e o uso:

1. Se você quiser capturar pacotes locais, leia sobre o loopback e instale o software de pré-requisito (npcap para windows)
2. Instale o WireShark
3. Configure filtros de captura (por exemplo, um filtro para só capturar tráfego na porta 57772: port 57772
4. Inicie a captura
5. Configure filtros de exibição (por exemplo, um filtro para só exibir tráfego http para um ip específico: ip.addr == 1.2.3.4 && http

Confira um exemplo de captura de tráfego http (filtro de exibição) na porta 57772 (filtro de captura):

 Vantagens:

• Processa respostas parcialmente enviadas/corrompidas/etc.
• Consegue capturar uma grande quantidade de tráfego
• Consegue capturar qualquer coisa
• Consegue capturar sessões

Desvantagens:

• Algo (aplicativo da Web/cliente REST/código JS) é necessário para enviar a solicitação

O que usar

Bem, isso depende da finalidade. Primeiro, podemos ter como objetivo registrar (proxy de depuração, analisador de pacotes) ou gerar (navegador, cliente REST) solicitações.

Se você estiver desenvolvendo uma API Web REST, o cliente REST é a maneira mais rápida de testar o funcionamento.

No entanto, se as solicitações do cliente REST funcionarem, mas o aplicativo da Web cliente não, talvez seja necessário o proxy de depuração http e o analisador de pacotes.

Se você tiver clientes e precisar desenvolver uma API do lado do servidor para trabalhar com eles, precisará do proxy de depuração http ou do analisador de pacotes.

É melhor estar familiarizado com todos os 4 tipos de ferramentas e mudar rapidamente entre eles se o atual não der conta do trabalho.

Às vezes, a ferramenta ideal é óbvia.

Por exemplo, recentemente, desenvolvi uma API do lado do servidor para um protocolo de extensão http popular. Os requisitos eram:

• Os clientes já estavam escritos e o código não podia ser alterado
• Clientes diferentes têm comportamentos diferentes
• O comportamento no http e https varia
• O comportamento com diferentes tipos de autenticação varia
• Até cem solicitações por segundo para cada cliente
• Todos ignoram o RFC

Há só uma solução aqui: o analisador de pacotes.

Ou, se estou desenvolvendo uma API REST para consumo de JS, o cliente REST é uma ferramenta perfeita para testes.

Ao depurar o aplicativo da Web, comece com o navegador.

Na Parte 2, vamos discutir o que pode ser feito (muita coisa) para a depuração da Web no lado do Caché.

Quais são suas abordagens para depurar a comunicação no lado do cliente?

Um cliente perguntou recentemente se o IRIS era compatível com o OpenTelemetry, pois queria medir o tempo que os serviços SOAP implementados pelo IRIS levavam para serem concluídos. O cliente já tem diversas outras tecnologias compatíveis com o OpenTelemetry para o tracing de processos.  No momento, o InterSystems IRIS (IRIS) não oferece suporte nativo ao OpenTelemetry.  

É verdade que a plataforma de dados do IRIS tem várias maneiras de capturar, registrar e analisar o desempenho de uma instância em execução. Essas informações não saem do IRIS por outros componentes do OpenTelemetry, como Agentes ou Coletores, em uma arquitetura do OpenTelemetry implementada.  Várias tecnologias já são compatíveis com o OpenTelemetry, que parece estar se tornando um padrão para a Observabilidade.

Embora haja desenvolvimento contínuo para oferecer suporte nativo a esse recurso em versões futuras do IRIS, este artigo explica como, com a ajuda do Embedded Python e das bibliotecas correspondentes do Python,  os desenvolvedores de aplicativos IRIS podem começar a publicar eventos de Trace para seus back-ends do OpenTelemetry com pouco esforço.  Mais importantemente, meu cliente pode começar a adotar algo hoje mesmo. 

Observabilidade. 

A observabilidade geralmente é composta de três aspectos principais:

• Captura de métricas, que é a captura de medidas quantitativas sobre o desempenho e o comportamento de um sistema, parecido com o que o IRIS publica pela /api/monitor/metrics api
• Registros, que envolvem capturar e armazenar informações relevantes geradas por um aplicativo ou sistema, como o que aparece nas saídas de Logs do Sistema ou o arquivo messages.log gerado por instâncias do IRIS.
• Tracing: que envolve o rastreamento do fluxo de uma transação ou solicitação de serviço enquanto se move por vários componentes de uma solução. O tracing distribuído permite que você siga o caminho de uma solicitação em vários serviços, oferecendo uma representação visual de todo o fluxo da transação.

Este artigo e o aplicativo complementar encontrado aqui focam apenas no Tracing de Serviços SOAP.

Nessa implementação, que só usa o IRIS como a tecnologia para gerar telemetria, um trace e um Span raiz são iniciados com a inicialização do Serviço SOAP.

Abordagem de implementação:

Transforme a classe %SOAP.WebService do IRIS com a lógica de implementação do OpenTelemetry e as funções das bibliotecas Python em uma nova classe chamada SOAP.WebService. Inclua Macros que possam ser usados no código do usuário para contribuir mais com a observabilidade e o tracing. Devem ser necessárias mudanças mínimas na implementação do SOAP (troque o uso de %SOAP.WebService pelo SOAP.WebService como a superclasse de serviço web para implementar o SOAP.
O diagrama abaixo ilustra essa abordagem:

Recursos dessa implementação:

• Por padrão, todo Serviço SOAP será rastreado e relatará informações de traces.
• Quando um Serviço SOAP é usado pela primeira vez, a implementação inicializará um objeto Tracer do OpenTelemetry. Uma combinação do nome do servidor IRIS e instância é fornecida como a origem da telemetria, e a ação SOAP é usada como o nome do span raiz padrão que rastreia o serviço soap.
• Os traces de telemetria e o span padrão serão encerrados automaticamente quando a chamada do método SOAP for finalizada
• Depois da criação, os pares de chave/valor dos atributos podem ser adicionados ao span raiz padrão, como o ID da sessão do CSP ou o número do trabalho
• Os usuários podem usar o $$$OTELLog(...), para adicionar registros manuais a um span, usando uma string simples ou um array de pares chave-valor 
• Os usuários podem usar o $$$OTELPushChildSpan(...)/$$$OTELPopChildSpan(...) para criar spans não raiz em torno de seções do código que desejam identificar de maneira independente com sua lógica

Instalação e teste

• Faça o git pull/clone do repositório em qualquer diretório local

$ git clone https://github.com/pisani/opentelemetry-trace-soap.git

• Abra uma janela de terminal nesse diretório e digite o seguinte para criar as imagens IRIS com código de amostra:

$ docker-compose build

• Depois de criar a imagem iris, no mesmo diretório, digite o seguinte para iniciar os contêineres Jaeger e IRIS:

$ docker-compose up -d

Isso iniciará dois contêineres: o contêiner back-end de destino do OpenTelemetry Jaeger (também expondo uma interface do usuário) e uma instância do IRIS que servirá como o endpoint do servidor dos serviços web SOAP.  Três serviços web simples foram desenvolvidos na instância do IRIS para testar a solução.

• Usando seu navegador, acesse as informações SOAP e páginas de teste por esse URL. Faça login como um superusuário/SYS quando solicitado:

http://localhost:52773/csp/irisapp/SOAP.MyService.cls

(Observação: essas páginas não são ativadas por padrão, e a segurança na instância do IRIS em execução precisa ser relaxada para ativar esse recurso, facilitando o teste)

Selecione cada um dos métodos da web que você quer testar, para gerar a atividade SOAP.  Para ver essa implementação gerar um Erro nos traces observados, use zero (0) como o segundo número no método SOAP Divide(), forçando um erro <DIVDE>.

• Abra outra guia do navegador e acesse a IU do Jaeger pelo seguinte URL

http://localhost:16686

• A página de destino resultante mostra todos os serviços que contribuem para as leituras de telemetria e deve ser parecida com a captura de tela abaixo: 

Conclusão

Resumindo, este artigo mostra como o Embedded Python pode ser usado para adicionar mais recursos ao IRIS, no meu caso, implementar o tracing de Observabilidade para os serviços SOAP.  As opções disponíveis pelo Python e a capacidade do IRIS de aproveitar as bibliotecas Python são vastas.

Reconheço que é possível trabalhar para criar uma classe mais genérica de suporte ao OpenTelemetry que implemente o mesmo para os serviços REST, além de ampliar as assinaturas de Class Method para rastrear o timing de qualquer Class method por esse framework.

Publiquei um Serviço SOAP.
Recebo o cabeçalho abaixo com o parametro mustUnderstand="1", logo preciso criar a estrutura para interpretar o cabeçalho.

Ocorre que o valor contido na TAG <Action/> é puramente uma string. Não estou conseguindo fazer a classe de header aceitar esse valor, uma vez que por default ela espera que a TAG <Action/> contenha subelementos espelhados nas suas propriedades (como se fizesse o correlate e não conseguisse interpretar a string).
 

Alguém sabe como consigo receber esse cabeçalho?

Cabeçalho do XML:

Oi, pessoal,

Estamos nos conectando a um serviço da Web SOAP de terceiros.O wsdl se parece com o abaixo 

Observe que o portType foi definido como / cvpService.

Então, quando estivermos tentando usar o SOAP Wizard para gerar um cliente para o serviço, encontraremos o seguinte erro que impediu a geração 

Parece que '/ cvpService' não pode ser usado como um nome de classe válido (ou mesmo nome de método), portanto, a geração falhou.

Portanto, tenho 2 perguntas sobre a falha

Pessoal,

Procuro perfil de analista de integração / Ensemble (freelance). Interessados, por favor enviar mensagem de WhatsApp (61) 98405-2981.

Local de trabalho: 100% Remoto

Habilidades:  Cache DB, Object Script, InterSystems, Ensemble

Conhecimentos Necessários:

Olá,

Tenho uma pergunta sobre um problema ao chamar um serviço da Web SOAP.

Publicado o novo lançamento da versão 1.5 do InterSystems API Manager (IAM).

O contêiner do IAM, incluindo todos os artefatos necessários para realizar a atualização a partir de versões anteriores do IAM podem ser baixados do site de Distribuição de Software do WRC na área de Componentes.

O número de registro deste lançamento é  IAM 1.5.0.9-4.

O Gerenciador de APIs InterSystems 1.5 facilita o gerenciamento do tráfego de suas APIs, a integração de seu ambiente e usuários com suas APIs. Ele possui várias novas funcionalidades incluindo: 

*Analista Ensemble Júnior / Pleno

Próximo Metrô Clínicas

REQUISITOS:

* COS / Portal
* Conhecimento em barramento e protocolos RESTFull / SOAP 
* Integração com banco de dados Oracle / SQL Server

ATIVIDADES:
* Integração de sistemas hospitalares
* Administração do ambiente Ensemble
* Análise de Dados

Enviar CV com pretensão salarial
.

Contratação CLT ou PJ tempo indeterminado

Empresa ..................: JHealth Informatics
Email ........................: rh@jhealth.com.br

Ao chamar os serviços web, há várias configurações de Business Operation que atuam juntas no controle do que acontecerá quando uma resposta não for retornada no tempo desejado.(Observe que isso também é relevante, por exemplo, para uma chamada HTTP simples não SOAP)

As 3 configurações principais envolvidas são:

Especifica o tempo limite para obter uma resposta do servidor web remoto.

Número de segundos de espera entre as tentativas de conexão com um destino fora do Ensemble.

Número total de segundos para continuar tentando se conectar com um destino fora do Ensemble. Após esse número de segundos ter decorrido, a operação de negócios descarta os dados da mensagem e retorna um código de erro. 

Colocando em palavras, isso funciona da seguinte maneira –

Vamos esperar por uma resposta do servidor web para o 'Tempo Limite de Resposta' em segundos. Se nenhuma resposta for recebida até esse momento, vamos chamar o servidor web novamente após os segundos do 'Intervalo de Repetição' terem decorrido. Continuaremos tentando uma resposta com estes segundos do 'Tempo Limite de Falha' com o tempo decorrido desde o início da primeira tentativa.

Para ilustrar, vamos olhar o seguinte exemplo –

Considere as seguintes configurações:

Em palavras –

Tempo Limite de Resposta - Esperar por 7 segundos pela resposta

Intervalo de Repetição - Tentando novamente a cada 10 segundos.

Tempo Limite de Falha - "Desistir" e tentar novamente após 30 segundos

Então, supondo que a resposta volte após exatamente 8 segundos, então o seguinte cenário ocorrerá –

A seguir, algumas "evidências" de uma chamada de amostra de acordo com o cenário acima.

Primeiro, o lado do servidor [do log SOAP] – você pode ver que recebeu 4 chamadas/requisições, com 10 segundos de intervalo, cada vez retornando uma resposta após 8 segundos a partir da requisição –

05/31/2016 14:18:45 *********************

Input to Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:18:53 *********************

Output from Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:18:55 *********************

Input to Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:03 *********************

Output from Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:05 *********************

Input to Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:13 *********************

Output from Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:15 *********************

Input to Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:23 *********************

Output from Web service with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

E agora do lado do Ensemble BO/cliente, você pode ver 4 tentativas, 10 segundos de intervalo, cada vez registrando um erro de tempo limite de resposta 7 segundos depois.

Lado do cliente

05/31/2016 14:18:45 *********************

Output from Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:18:52 *********************

Input to Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

ERROR #5922: Timed out waiting for response

string**** SOAP client return error. method=GetResponse, action=http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

     ERROR #5922: Timed out waiting for response

05/31/2016 14:18:55 *********************

Output from Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:02 *********************

Input to Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

ERROR #5922: Timed out waiting for response

string**** SOAP client return error. method=GetResponse, action=http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

     ERROR #5922: Timed out waiting for response

05/31/2016 14:19:05 *********************

Output from Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:12 *********************

Input to Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

ERROR #5922: Timed out waiting for response

string**** SOAP client return error. method=GetResponse, action=http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

     ERROR #5922: Timed out waiting for response

05/31/2016 14:19:15 *********************

Output from Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

...

05/31/2016 14:19:22 *********************

Input to Web client with SOAP action = http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

ERROR #5922: Timed out waiting for response

string**** SOAP client return error. method=GetResponse, action=http://tempuri.org/Test.WSTimeouts.WebService.GetResponse

     ERROR #5922: Timed out waiting for response

Aqui está o Ensemble Visual Trace:

E aqui as entradas do registro de eventos (log) –

Amostra de registro de eventos (log) com eventos de rastreamento ativado (Você pode precisar aumentar o zoom para ler melhor o texto na imagem) –

Aqui você pode observar alguns dos "funcionamentos internos" do cenário descrito acima –

No Log ID #684 a chamada inicial é feita – às 17:09:16.

Então, 7 segundos depois (09:23), obtemos o erro de tempo limite de resposta (#685). A operação então registra o erro (#687) e decide esperar mais 3 segundos até o intervalo de repetição; Intervalo de repetição de 10 segundos menos o tempo limite de resposta de 7 segundos (#688 - #690).

Decorridos os 3 segundos de espera (às 09:26; #691) é feita a ^2ª tentativa (#692), com o mesmo resultado e o mesmo comportamento subsequente, até a ^4ª tentativa (#704). Após a falha da ^4ª tentativa (09:53; #705), outra tentativa não é feita, pois o tempo limite de falha (30 segundos) foi excedido.