Criando, Editando e Excluindo Environments

Na tela Environments, é possível criar novos ambientes para implantar suas APIs.

O seu Manager já vem com um ambiente padrão cadastrado. Se você quiser criar um ambiente novo, deverá primeiramente cadastrar um domínio para o seu ambiente na tela Inbound Address.

Você pode usar um mesmo host para múltiplos ambientes, complementando o endereço de cada ambiente adicionando uma Inbound URL, conforme as instruções desta página. Assim, todos os seus ambientes terão uma URL única.

A configuração de uma URL válida é crucial para o correto funcionamento do ambiente. Caso seja configurada uma URL que direcione a chamada para outro domínio, o recurso da API que se deseja consumir não será encontrado.

Cadastrando um novo ambiente

Para cadastrar um novo ambiente, clique no botão + no canto inferior direito da página Environments.

Há dois campos diferentes para o cadastro: a área para preenchimento dos campos obrigatórios, e a área para registro das variáveis de ambiente (environment variables).

Campos obrigatórios

Nesta área, devem ser preenchidos todos os campos obrigatórios, compostos por dados básicos e permissão de visualização e implantação.

Dados básicos

Name: nome que identifica o ambiente.
Description: descrição que ajuda na identificação do ambiente.

Host + Inbound URL: formam a URL que representará o ambiente e receberá as requisições realizadas às APIs que forem hospedadas nele.

No campo Host, que é obrigatório, selecionar um domínio cadastrado na página Inbound Address.

Quando você selecionar o host, poderá complementar o endereço no campo Inbound URL, que é opcional. A URL aparecerá no campo para que você a complete (veja a imagem abaixo).
host url

Não é obrigatório complementar o host com uma inbound URL. Entretanto, atente-se para o fato de que cada ambiente deve ter uma URL única. Como é possível utilizar um mesmo inbound address (host) para múltiplos ambientes, será obrigatório complementar a URL de cada um dos ambientes compartilhando um host com uma inbound URL única.

O tipo de segurança que aparece na listagem de ambientes existentes — que pode ser nenhuma (none), TLS ou mTLS — não é configurado na tela Environments, mas sim em Inbound Address. É la que você estabelece, portanto, se a URL conterá http:// ou https://.

Gateway Pool: campo para indicar qual pool de gateways contratado irá atender o ambiente.

É sempre possível conversar com o seu Business Partner para contratar mais pools de gateways.

Uma vez cadastrado o gateway pool de um ambiente, não é possível editar este gateway pool.

Permissões

O campo Environment Deployment Permission está relacionado à permissão de implantação de APIs dentro do ambiente. O campo Environment Trace Visibility permite restringir o acesso à visibilidade do ambiente no Trace (que contém a listagem de chamadas para as APIs que forem associadas ao ambiente em questão).

A restrição de visualização pelo campo Environment Trace Visibility será aplicada tanto ao General Trace total (referente a todas as APIs), quanto ao API Trace acessado pelo card de uma API específica.

Leia mais sobre as permissões de visualização do API Manager aqui.

Para ambos os campos, estas são as opções de permissão:

Organization: liberará acesso para todos os usuários logados no sistema.
Teams: habilitará acesso para o time selecionado. Para saber mais sobre a criação de times, clique aqui.
Only me: permitirá acesso apenas para o usuário que criou o ambiente.

Caso você escolha a opção Teams ou Only me, o botão Add Users será habilitado. Por meio dele, você poderá adicionar usuários individuais para que também tenham acesso (veja a imagem abaixo).

users

Environment Variables

Variáveis de ambiente (environment variables) são variáveis com valores únicos para um ambiente específico. Elas são utilizadas como uma configuração extra de cada ambiente, permitindo personalizar requisições de forma a alternar facilmente entre contextos diferentes. Não é obrigatório criá-las, mas o seu uso torna mais prático o processo de design e gerenciamento de APIs.

O API Manager permite criar variáveis de ambiente que podem ser utilizadas em diversos pontos da nossa plataforma, como no Target ou Timeout da API Destination, ao habilitar um Connector ou em inúmeros Interceptors (ver a tabela abaixo).

Lista de interceptors que permitem o uso de variáveis de ambiente:

Time allowed
Spike arrest
Rate limit
Payload size
Cache write
Billing hits

XML Threat protection
JSON Threat protection
Time Token
IP Filtering
Encrypt
Data Obfuscation
CSRF Token

Service mashup
Service callout
Internall API Call

Query param
Header
Destination

Um exemplo prático de uso: imagine que várias APIs implantadas em um ambiente contenham um target destination igual e que, em algum momento, ele mude. Seria necessário alterar o target destination em todas as APIs individualmente. Entretanto, se ele tiver sido definido como uma variável de ambiente, bastará modificar o valor da variável no ambiente específico e isso atualizará os destinations das APIs.

Para cadastrar variáveis de ambiente, é necessário adicionar um mapa de variáveis (Variables Map), ou importar um mapa existente em outro ambiente.

Para adicionar um mapa, clique no botão ADD MAP. Uma tela como a da imagem abaixo será apresentada. Você deverá definir um nome para o mapa e poderá incluir uma descrição, se quiser.

Agora você pode criar as variáveis de ambiente como um par chave-valor em que ambos são strings.

O campo Type permite mudar a tipagem da variável para uma das opções abaixo:

DEFAULT: É a tipagem padrão para todas as variáveis, e não muda nada em seu comportamento.
SECURED: Esta tipagem tem seu valor criptografado. A decriptação é feita apenas pelo fluxo de um Connector, adicionando mais segurança ao armazenar as credenciais do mesmo, já que o valor não é resgatável de nenhuma outra forma.

Se desejar, você pode adicionar um certificado, correspondente à comunicação entre o gateway e o backend, a ser aplicado quando a variável de ambiente for utilizada. Para isso, clique no ícone icon certificate . Uma janela modal aparecerá para que você escolha o certificado, que deve ter sido cadastrado na página Certificates.

Para importar um mapa de outro ambiente, basta clicar no botão IMPORT MAP. Selecione o nome do ambiente que contém o mapa e o sistema carregará os mapas existentes. Após selecionar o mapa desejado, clique em IMPORT MAP.

As variáveis de ambiente do mapa serão carregadas. Você poderá visualizá-las clicando no ícone para extender abas ao lado do nome do mapa. Você poderá editar ou excluir as variáveis, clicando nos respectivos ícones ( icon edit ou icon delete ).

Para adicionar novas variáveis a um mapa, clique no ícone icon more info à direita do nome do mapa, e, na aba que se abrirá, no icone +. Nessa mesma aba, você poderá editar o nome e descrição do mapa (clicando no ícone icon edit ) ou excluir o mapa (pelo ícone icon delete ).

Exemplo de uso

Como mencionamos anteriormente, uma variável de ambiente é um par chave-valor, ambos strings. No exemplo abaixo, foram criadas duas variáveis: uma denominada destination, com um endereço válido, e uma denominada rateLimit, com o valor 2.

A variável de ambiente $destination pode ser utilizada, por exemplo, como o endpoint de uma API. Dessa forma, quando uma requisição for realizada para a API, o gateway irá direcionar a chamada para o endereço configurado.

Para isso, basta referenciar a variável de ambiente no Target Destination da API, conforme a imagem a seguir.

O Target Destination de uma API é acessado na seção Flows de edição ou criação de uma API, clicando-se no botão icon backend

no diagrama que representa os fluxos de requisição e resposta.

Atualmente o gateway realiza por padrão o reaproveitamento de conexões, para mais informações sobre como gerenciá-lo, consulte a FAQ aqui.

Todas as variáveis de ambiente, ao serem referenciadas nas APIs ou nos interceptores, devem ser precedidas do símbolo $.

Na imagem abaixo, temos um exemplo de utilização da variável de ambiente $rateLimit no interceptor homônimo. Nesse cenário, quando for feita uma requisição para a API, o Gateway substituirá a quantidade de chamadas pelo valor configurado na variável (no caso, o valor 2).

Editando um ambiente

O botão de edição de ambientes é encontrado na listagem de ambientes existentes, na coluna ACTIONS.

Para editar os dados de um ambiente, clique no ícone icon edit e você será direcionado à tela de edição.

Excluindo um ambiente

Para excluir um ambiente, basta clicar no ícone icon delete na coluna ACTIONS da listagem de ambientes existentes e confirmar a ação clicando no botão CONFIRM.

Se o ambiente que você deseja excluir possuir implantações de APIs (ou seja, deploys ativos), não será possível excluir o ambiente. Para excluí-lo, você deverá primeiramente desativar os deploys.

Undeploy revisions de um ambiente

Na parte inferior da tela de edição de Environments, estão listados todos os deployments associados a um ambiente.

Clique em icon delete deploy , na coluna ACTIONS para realizar o undeploy de uma revision.

Ao clicar, o seguinte modal será exibido:

Clique no botão CONFIRM para confirmar a ação.

Ao desassociar uma revision, ela não aparecerá mais na lista de deployments.

Caso possua o Adaptive Governance habilitado e tenha realizado o undeploy utilizando o método acima, será possível habilitá-lo novamente por meio da Implantação de APIs na tela de Environments.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]