Configurando Connectors

Você encontra os connectors disponíveis na Plataforma dentro do menu API Connectors do Manager:

apiManager apiConnectors

Eles são categorizados por seu tipo (que representa o protocolo a que eles permitem acesso). Por exemplo: Oracle Connector, SQL Server Connector e AWS Lambda Connector.

Os conectores se dividem por grupo, com características em comum. Pensando nos exemplos acima, o Oracle e o SQL Server são do grupo Database, enquanto o AWS Lambda é do grupo Cloud Providers. Essas divisões facilitam encontrar o conector desejado no API Manager.

Os conectores que estiverem habilitados no menu API Connectors estão prontos para ser vinculados a uma API e servir como base para criação de novos recursos. Os connectors habilitados tem a cor de seu grupo, enquanto os desabilitados ficam em cinza.

Quando vincular um connector a uma API, você poderá definir as operações para esse recurso da mesma forma como configura outros recursos de uma API (leia mais sobre recursos aqui). Como mencionamos antes, cada conector pode ser vinculado a múltiplas APIs e uma API pode ter múltiplos recursos a partir de connectors diferentes.

Mas, antes de tudo, é preciso saber como habilitar os connectors.

Habilitando um conector

Para habilitar um conector existente na Plataforma, é necessário preencher as informações obrigatórias. Depois de habilitado, você poderá vincular seu conector a uma API e criar recursos a partir dele.

O primeiro passo para habilitar um conector é configurar o ambiente em que ele será executado, no menu Environments do Manager.

Criando environment variables de conexão

Cada conector tem propriedades específicas de conexão. Essas propriedades são variáveis intrínsecas a cada tipo de conector, que representam diferentes configurações necessárias para que a conexão aconteça.

Por exemplo, um conector do tipo Database deve conter valores informando o nome do banco de dados, usuário e senha para acesso, database schema a ser utilizado, endereço do banco, entre outros.

Os valores dessas propriedades devem ser especificados previamente como variáveis de ambiente, na seção Environment Variables de um ambiente, dentro do menu Environments do Manager.

Como cada tipo de conector tem variáveis de ambiente diferentes, listamos os campos que você precisa preencher para cada conector. Acessando a página de informações técnicas, você consegue selecionar o grupo de conectores e encontrar o tipo específico que você precisa.

No exemplo da imagem abaixo, estamos estabelecendo as variáveis de ambiente para um Oracle Connector.

apiManager environmentVariables

As variáveis devem ter nomes únicos — ou seja, não é é possível existir duas variáveis com o mesmo nome.

Para facilitar, você pode seguir um padrão para nomear as variáveis. Uma sugestão para conectores de bancos de dados, por exemplo, é usar o seguinte padrão: nome-do-banco_nome-da-variavel_ID

Cadastrando um connector

Agora o novo conector já pode ser registrado no menu API Connectors do Manager.

Para disponibilizar um novo conector a partir do qual criar recursos, clique no botão flutuante + (Create Connector) e selecione o tipo do novo conector.

apiManager selectConnectorType

No exemplo acima, há três tipos disponíveis: MySQL e Oracle (dentro do grupo Database) e AWS Lambda (dentro do grupo Cloud Providers).

Ao selecionar o tipo, duas informações obrigatórias devem ser informadas: Name e Description.

apiManager selectConnectorType fillInfo

Após o preenchimento, as informações Connector ID e Factor (necessárias para a aplicação ser iniciada) são geradas.

apiManager selectConnectorType filled

Para executar o conector, é necessário baixá-lo na máquina. Para isso, é um pré-requisito ter Java 17 (ou superior) ou Docker instalado. Na mesma tela, você vê as instruções para baixar o conector pela linha de comando. São duas opções: Command JAR (no caso de Java) e Command image (para Docker).

apiManager downloadJar
apiManager dockerPull

Com a aplicação rodando, é necessário preencher a informação faltante na tela do Manager (endpoint) para cadastrar o conector (clicando em Register Connector), conforme a imagem abaixo. Nesta página, o endpoint é o endereço da máquina onde o conector está rodando.

apimanager createConnector endpoint

Após o cadastro bem-sucedido, as demais informações de configuração serão exibidas:

apiManager createConnector final toFill

É necessário apontar qual environment será configurado, e é possível escolher um ou mais environments. No caso de múltiplos environments, todas as variáveis de todos os ambientes devem ter o mesmo nome. Por exemplo: se apontarmos o "environment 1" e o "environment 2", é preciso que a variável "user" esteja cadastrada em ambos.

apiManager createConnector final filled

Quando pelo menos um environment for apontado, as variáveis ficarão disponíveis nos campos para serem selecionadas. Após o preenchimento dos campos, a opção Test Connection para validar as informações será habilitada.

Caso existam mais environments para o mesmo conector, os status de conexão de cada um serão exibidos em sequência, com mensagem de erro de conexão se houver algum. Após essa etapa, o conector pode ser salvo e estará apto para ser configurado no recurso de uma API. Leia mais sobre isso aqui.

apiManager testConnection

Existe também a possibilidade de configurações extras de segurança para o conector, como os interceptores de Rate Limit, Payload Size e IP Filtering. O conector só utilizará essas configurações caso elas estejam corretamente preenchidas — ou seja, nenhuma delas é obrigatória.

Para configurar o interceptor de Rate Limit, é necessário informar a quantidade de requisições permitidas para um determinado intervalo em segundos, minutos, horas, dias ou meses. Em Payload Size, a informação é esperada em kB, possibilitando um payload de requisição que seja menor do que o configurado. Já o IP Filtering obedece tanto à configuração manual de IPs quanto ao padrão CIDR — as requisições serão respondidas apenas se o IP de origem estiver configurado.

Opções de propriedades de configuração

Validação de token JWT

Como um requisito de segurança na comunicação entre os connectors e o gateway, um token JWT de curto tempo de vida (2 segundos) é gerado e validado a cada requisição que é feita utilizando um connector. Para que esse processo ocorra sem problemas, é necessário que o horário da máquina que roda o connector seja exatamente igual ao horário do gateway — por meio de sincronização via NTP (network time protocol), por exemplo.

Como pode haver casos de dificuldade para sincronizar os horários, é possível adicionar propriedades de configuração no momento em que um connector é baixado e executado — como descrito acima — para que exista um tempo a mais na validação do token JWT dentro do connector:

  • -DTOKEN_LEEWAY_BEFORE: essa propriedade adiciona uma folga em segundos na verificação do momento a partir do qual o token pode ser utilizado.

  • -DTOKEN_LEEWAY_AFTER: essa propriedade adiciona uma folga em segundos na verificação do tempo de expiração do token.

Sugerimos que você só utilize as propriedades acima se realmente não conseguir manter sincronismo entre os horários da máquina e do gateway. Para seguir a implementação de segurança, o desejável é que exista sincronismo e que o token seja validado da forma padrão.

Os exemplos abaixo mostram os comandos para baixar e executar um Lambda Connector utilizando as propriedades acima (mas elas são aplicáveis a qualquer connector). O tempo em segundos (que está como 0, que é o padrão) pode ser ajustado para a realidade da máquina que rodará o connector.

Command JAR:

java -jar -Xmx200m -Xms200m \
-DconnectorId=staging-e3d26a58-503c-4e47-9126-564bbfef30f7 -Dfactor=97de049b-7a25-4a91-a15d-2a8e2d9f19cd \
-DENABLE_LOG=true -DLEVEL_LOG=INFO -DSERVER_PORT=7096 -DTOKEN_LEEWAY_BEFORE=0 -DTOKEN_LEEWAY_AFTER=0 aws-lambda-conn-4.1.0.0.jar

Command image:

wget https://sensedia-connectors.s3.amazonaws.com/cloud-providers/aws-lambda-conn-4.1.0.0.jar \
&& java -jar -Xmx200m -Xms200m \
-DconnectorId=staging-e3d26a58-503c-4e47-9126-564bbfef30f7 -Dfactor=97de049b-7a25-4a91-a15d-2a8e2d9f19cd \
-DENABLE_LOG=true -DLEVEL_LOG=INFO -DSERVER_PORT=7096 -DTOKEN_LEEWAY_BEFORE=0 -DTOKEN_LEEWAY_AFTER=0 aws-lambda-conn-4.1.0.0.jar
Thanks for your feedback!
EDIT
How useful was this article to you?