Atenção!| Para usar esse recurso, você deverá ter conhecimento de: conexões REST, HTTP, Json, JSONPath, XML e XPATH. |
Veja um exemplo de como podemos usar o novo tipo de campo Pesquisar e Preencher para consultar obter o Endereço de um CEP e preencher estes dados no formulário eletrônico do seu processo:
Neste vídeo vamos trabalhar com o FEED RSS do Canal da SML Brasil no YouTube, que é um arquivo XML, para popularmos uma caixa de seleção e outros campos do formulário com dados obtidos desse arquivo:
O que é JSON
JSON (JavaScript Object Notation) é um padrão para formato de dados simples, derivado da sintaxe de objetos em Javascript. E apesar de estar diretamente relacionado à JavaScript, ele é um padrão com vários parsers em diferentes linguagens, podendo servir para diferentes propósitos. Se o seu sistema externo permite conexões JSON, use esse padrão.
Veja um exemplo de arquivo JSON abaixo:
O que é XML
É a sigla para Extensible Markup Language, que significa em português "Linguagem Extensível de Marcação Genérica". É uma recomendação para gerar linguagens de marcação para necessidades especiais. XML é capaz de descrever diversos tipos de dados, e seu objetivo principal é a facilidade de compartilhamento de informações através da Internet.
Abaixo temos um exemplo de documento XML:
O que é REST
O termo REST é utilizado para descrever qualquer interface web simples que utiliza XML (ou JSON, ou texto puro) e HTTP, sem as abstrações adicionais dos protocolos baseados em padrões de trocas de mensagem como o protocolo de serviços Web SOAP. É possível desenhar sistemas de serviços Web de acordo com o estilo arquitetural REST.
Uma conexão REST geralmente é representada por uma URL, similarmente as URL´s de navegação na internet. Por isso, ao realizar uma fonte de dados REST, o fornecedor do sistema que irá fornecer a API deverá informar, no mínimo, a URL do serviço.
Muitas vezes, você conseguirá abrir o arquivo REST acessando a URL informada diretamente em seu navegador de internet. Veja abaixo:
Conectividade
O primeiro ponto a verificar ao realizar uma conexão REST é se o servidor onde está instalado o Orquestra consegue "enxergar" a URL a ser integrada. Se você consegue abrir a URL em seu navegador em seu computador local, é um passo positivo, pois significa que a URL realmente existe. Mas não assegura que o servidor do Orquestra conseguirá acessar.
É muito normal as equipes de TI configurarem servidores para que eles não possam acessar a Internet ou outros recursos da Intranet da empresa. Isso poderá impedir que o Orquestra conecte-se ao serviço.
De modo geral, siga as recomendações abaixo:
- Tente acessar a URL em seu computador local, usando seu navegador. Se funcionar, é um ponto positivo;
- Se você tiver acesso ao servidor onde o Orquestra está instalado, abra o navegador de internet instalado no servidor e procure acessar a URL. Se funcionar, é um ponto positivo;
- Tente configurar a fonte de dados no Orquestra SEM configurar proxy, usuário ou senha. Se funcionar dessa maneira, melhor;
- Se você receber algum erro de conectividade e o acesso a Internet em sua rede é feito via proxy, tente configurar essa conexão na configuração da fonte de dados;
- Use o tipo de autenticação padrão de "Use Global Preferences", caso necessite de autenticação "Pre-emptive" selecione a opção na configuração da fonte de dados;
- Se, ainda assim, não for possível realizar a conexão, será preciso abrir um canal de conversa com a equipe de infraestrutura de TI de sua empresa para compreender porque o servidor do Orquestra não consegue conectar na URL.
Principais configurações
Configurações de autenticação
- Usuário para autenticação: cadastre aqui um usuário de serviço de sua rede, com permissão de navegação dentro da rede da empresa ou da internet, e que fará a conexão com o proxy. É importante que esse usuário seja criado pela TI de sua empresa especialmente para isso; se você cadastrar aqui o seu usuário pessoal e sua senha, é possível que você enfrente problemas no futuro, quando, por exemplo, sua senha expirar. A senha de usuários de serviços não expiram;
- Senha: cadastre aqui a senha do usuário de serviço criado;
- Endereço do proxy: cadastre arquivo o endereço HTTP do seu servidor proxy em sua rede, com a porta de conexão, se necessário;
- Tipo de Autenticação: escolha o tipo de autenticação utilizado pelo serviço;
- Use Global Preferences:Preferencias globais de autenticação do webserserve;
- Authenticate Pre-emptively: Em geral, significa que o servidor espera que as credenciais de autorização sejam enviadas sem fornecer a resposta não autorizada. Reduzindo a carga na rede e no próprio.
Endereço, método e parâmetros
- Endereço de definição do serviço: cadastre aqui a URL do serviço REST que você irá conectar. Essa URL poderá possuir informações dinâmicas, como tokens. Por exemplo, considere a seguinte URL JSON que retorna uma consulta a CEP:
https://viacep.com.br/ws/90480180/json/. Como podemos ver, na própria URL é enviado o CEP a ser consultado, no caso, 90480-180. Se você possui um campo no formulário do Orquestra cujo identificador é "cep", e a partir desse campo deseja realizar a consulta de endereço, deve configurar a conexão REST com o endereço https://viacep.com.br/ws/{Formulario.cep}/json/ .
2. Cabeçalho: no cabeçalho da conexão são, geralmente, enviadas informações adicionais necessárias para a conexão REST ocorrer. É comum, por exemplo, que no cabeçalho sejam enviadas informações de autenticação (como usuário e senha, por exemplo), específicas para conexão no serviço. O serviço Airtable.com, por exemplo, que permite a usuário de negócios montarem bancos de dados na Internet, habilita uma API Json para cada banco de dados criado. Conforme sua documentação, no cabeçalho deve ser enviado o token de autenticação do Airtable, no formado Authorization: Bearer YOUR_API_KEY. A informação do que deve ser enviado no cabeçalho deve ser informada pelo fornecedor da API.
3. Método: selecione aqui qual será o método de postagem de dados para a API. Em grande parte das vezes, principalmente ao simplesmente listar ou resgatar dados de uma API Json, esse campo poderá ficar em branco (marque a opção N/A). A informação sobre qual método usar deve estar disponível na documentação do serviço REST que você está conectando. Os métodos disponíveis são:
a. POST
b. GET
c. PUT
d. DELETE
e. PATCH
f. N/A (Nenhum)
4. Parâmetros - Corpo: esse campo é opcional e deve ser usado somente quando você precisa enviar dados estruturados para a API. Nesse cenário, além de você estar capturando / resgatando dados em formato JSON ou XML da API, você estará enviando um documento JSON ou XML para a API. É o cenário quando você, por exemplo, precisar adicionar ou atualizar dados no sistema externo. O uso de tokens aqui é comum.