Uma das requisições mais comuns em um projeto é a necessidade de integração com outros sistemas, sendo que atualmente o protocolo REST é o dominante. Seja para recuperar ou enviar informações, a forma como essa estrutura é pensada é essencial para a manutenção posterior. Ela precisa ser de fácil manutenção e dar sempre um feedback para o usuário do que está acontecendo (veja nosso artigo sobre como utilizar spinners, toasts e notices). Felizmente, a Salesforce provê uma forma de deixar essa manutenção mais fácil e parametrizável usando as credenciais nomeadas.
Atenção: se você quiser pular a história, clique aqui e vá direto para a explicação da credencial nomeada.
O que é Credencial Nomeada?
A credencial nomeada é uma estrutura que permite a parametrização de informações de conexão a outros sistemas. Com ela é possível parametrizar a URL de conexão e alguns modos de autenticação. Vamos ver um exemplo de integração sem utilizar esse recurso:
Atenção: nos exemplos desse post iremos utilizar a ferramenta Beeceptor, que nos permite criar endpoints fixos para fins de testes. Por se tratar de um plano gratuito, há um limite no número de chamadas que podem ser executadas. Caso você não consiga executar os exemplos, recomendamos que crie o seu próprio endpoint e substitua todas as URLs.
- URL: https://forcetricksapi.free.beeceptor.com/contatos
- Método: GET
O método APEX a seguir faz a chamada dessa API e imprime o resultado no console de depuração:
public class ContatosApi {
public static void chamarContatosApi() {
HttpRequest req = new HttpRequest();
req.setEndpoint('https://forcetricksapi.free.beeceptor.com/contatos');
req.setMethod('GET');
Http http = new Http();
HttpResponse response = http.send(req);
System.debug(response.getBody());
}
}Essa é uma API relativamente simples, e portanto sua chamada também. Nas linhas 4 e 5 temos, respectivamente, a definição da URL da requisição (chamada de endpoint) e o método que será utilizado (também conhecido como verbo HTTP) . Após essas definições, basta apenas fazer a requisição (linha 8) e tratar a resposta (linha 10).
Apesar de ser simples, simplesmente definir essas informações não é suficiente para fazer a integração funcionar. Faça o teste: tente executar o trecho acima no seu ambiente e verá que irá surgir um erro.
Segurança nas integrações
Uma das coisas mais fortes na plataforma é a questão de segurança, e nas integrações não poderia ser diferente. Sempre que o Salesforce precisa acessar recursos em servidores externos, é preciso que esse servidor esteja devidamente autorizado, caso contrário será exibido um erro.
Para o nosso caso, é simples de resolver: basta ir em configurações, na caixa de busca pesquisar por site remoto e ir em configurações do site remoto. Uma vez nessa página, basta adicionar o nosso endpoint, conforme abaixo:
Na definição do site remoto basta adicionar um nome e a URL raiz das suas integrações. Uma vez isso criado, aquela classe que definimos lá em cima vai funcionar perfeitamente!
E onde entra a credencial nomeada?
Esse é um exemplo muito simples e trivial, então o problema que a credencial nomeada soluciona não é tão visível.
Vamos extrapolar um pouco: pense que essa api (/contatos) é apenas uma de muitas APIs que foram desenvolvidas nesse projeto. Existem outras 60 integrações, cada uma com sua classe e todas funcionando perfeitamente. Porém, o time de sustentação entrou em contato dizendo que haverá uma mudança de infraestrutura que acarretará na mudança da url dos endpoints. Ao invés de ser “https://forcetricksapi.free.beeceptor.com/” passará a ser “https://forcetricksapi.premium.beeceptor.com/”.
O que fazer? Primeiro será preciso localizar nas suas classes todas as referências ao antigo endpoint e substituir pelo novo endpoint, e por fim modificar também a URL do site remoto.
Se você tem alguma vivência com projetos, já percebeu como isso é ruim. São altas as chances de uma API ser esquecida, ou ao trocar a URL de uma API uma alteração indesejada ser feita. Sem contar que isso custará tempo e, geralmente, não é uma boa ideia deixar coisas “hard-coded” em suas classes. Com vocês, credenciais nomeadas!
Credenciais nomeadas!
Conforme descrito acima, a credencial é uma estrutura que te permite centralizar configurações utilizadas em integrações. Através dela é possível parametrizar o endpoint e alguns tipos de autenticações. Vamos utilizar o mesmo exemplo anterior, mas agora com credenciais nomeadas.
Primeiro, é preciso criar a credencial nomeada. Vá em configurações e procure por credenciais, então clique em credenciais nomeadas e crie uma nova.
Em rótulo, coloque um nome que identifique sua API; o campo Nome será populado automaticamente mas você pode mudar se quiser; em URL, adicione o endpoint da sua integração. Nossa API não tem nenhum tipo de autenticação nem parâmetros de cabeçalho, então o restante pode ser deixado como está. Fica dessa forma:
Autenticação
Na parte de autenticação é possível escolher um certificado para ser usado sempre que essa credencial for usada, e o tipo de autenticação necessária. A autenticação pode ser de forma anônima, usando um único usuário para todos ou as informações do usuário corrente. Em protocolos existe uma série de protocolos, cada um com os seus parâmetros, que pode ser escolhido.
Opções de chamada
Caso você precise adicionar campos ao cabeçalho ou parâmetros em sua API durante a chamada, marque o campo correspondente. Isso permitirá que durante a construção da sua chamada HTTP essas informações possam ser adicionadas.
Usar credenciais nomeadas
Agora que já criamos a credencial, vamos voltar ao nosso código e trocar a referência fixa ao endpoint pela referência da credencial nomeada:
public class ContatosApi {
public static void chamarContatosApi() {
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:ForceTricks/contatos');
req.setMethod('GET');
Http http = new Http();
HttpResponse response = http.send(req);
System.debug(response.getBody());
}
}A mudança é muito sutil e está na linha 4: ao invés de utilizar a URL fixa, substituímos pela notação callout:<nome da credencial> e após o caminho da sua API.
Vantagens da credencial nomeada
A grande vantagem de utilizar a credencial nomeada é a centralização das informações necessárias para essa integração. Ao invés de ter a mesma informação espalhada em diversos lugares, de forma fixa, ela fica em um único lugar. No cenário anterior, da mudança de endpoints, basta apenas trocar o endpoint na credencial nomeada.
Além disso, não é necessário também adicionar essa URL aos sites remotos, já que a configuração da credencial já diz ao Salesforce que essa URL pode ser utilizada em outras requisições.
Um outro cenário pode ser quando há diferentes endpoints para diferentes ambientes, como desenvolvimento, homologação e produção. É simples fazer a subida desses artefatos para outro ambiente e mudar apenas a URL para que as requisições cheguem ao servidor correto.
Conclusão
As credenciais nomeadas são muito úteis para centralizar as informações dos seus endpoints e evitar que essas informações fiquem abertas e fixas nas suas classes Apex. Apesar de não ter todos os tipos de autenticações possíveis, o seu uso deve ser encorajado sempre que possível, ajudando o seu ambiente a ficar organizado e seguro.
O que achou desse artigo? Deixe sua opinião nos comentários ou mande uma mensagem pelo nosso formulário de contato caso queira entrar em contato.
