Usar as APIs REST do Salesforce com a Heroku

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

  • Entender os casos de uso das APIs REST do Salesforce.
  • Entender os diferentes tipos de autenticação.
  • Entender como usar as APIs REST do Salesforce com aplicativos no Heroku.

APIs REST do Salesforce e Heroku

As APIs REST do Salesforce permitem uma integração fácil com o Salesforce por meio de solicitações HTTP + JSON simples. Existem APIs REST para acessar quase tudo no Salesforce, portanto, seu aplicativo personalizado pode fazer basicamente tudo com os dados, processos e metadados no Salesforce. As APIs REST usam OAuth para autenticação, que é o padrão para lidar com autenticações REST.

Imagem mostrando uma conexão entre os objetos no Salesforce ao Heroku por meio de uma interface REST

Embora as APIs REST possam ser usadas diretamente, existem várias bibliotecas wrapper em torno das APIs, facilitando o uso delas em Node.js, Python, Ruby, Java, etc. As bibliotecas wrapper lidam com tarefas de baixo nível, como autenticação e tratamento de solicitações e respostas. Assim, em vez de construir manualmente solicitações HTTP do tipo (com Node.js como exemplo):

var query = 'SELECT name Account'; var url = 'https://na1.salesforce.com/services/data/v20.0/query/?q=' + encodeURIComponent(query); request.get(url, { 'auth': { 'bearer': 'bearerToken' } }); 

Você pode usar a biblioteca nforce de código aberto para Node.js e simplesmente fazer o seguinte:

org.query({ query: 'SELECT name FROM Account' }); 

No fim das contas, a biblioteca nforce faz a mesma coisa nos bastidores, mas a biblioteca facilita o uso da API.

Você pode criar integrações aplicativo a aplicativo e interfaces de usuário personalizadas com base nas APIs REST do Salesforce. A maior diferença está em como a autenticação é tratada. Com uma integração aplicativo a aplicativo, o aplicativo só conhece um único usuário de integração e todas as chamadas às APIs REST são feitas como esse usuário. Com uma interface de usuário personalizada, o usuário não autentica diretamente no aplicativo personalizado. Em vez disso, o usuário percorre o processo de OAuth para autorizar o aplicativo personalizado a fazer chamadas à API em seu nome. Cada solicitação à API REST é feita em nome do usuário denominado que está usando a interface de usuário personalizada.

Um caso de uso da integração aplicativo a aplicativo é transformar, agrupar e replicar ou fazer proxy dos dados para outro sistema. Por exemplo, um aplicativo de gerenciamento de pedidos voltado para o cliente em execução na Heroku precisa ter acesso às informações dos clientes no Salesforce. Esta configuração pode usar um único usuário de integração para buscar todas as informações necessárias no Salesforce.

No entanto, se o aplicativo de gerenciamento de pedidos for para o back-office, em que os usuários fazem login por meio do Salesforce, ele será uma interface de usuário personalizada que usa OAuth para permitir que o aplicativo de gerenciamento de pedidos faça pedidos à API em nome do usuário denominado. Neste caso, é importante saber que usuário denominado está fazendo cada chamada REST para fins de segurança e auditoria.

Com a Heroku, é fácil implantar esses tipos de aplicativo e tirar proveito de OAuth e APIs REST do Salesforce.

Você pode ler a documentação de REST API do Salesforce para saber mais sobre APIs de baixo nível, se desejar. Para um início rápido completo que inclui a implantação na Heroku e um aplicativo básico que usa APIs REST, confira Quick Force Node (JavaScript) ou Quick Force Java.

Autenticação de API REST com OAuth

A autenticação é um aspecto crucial do uso de APIs REST, já que cada solicitação às APIs precisa incluir um token ou uma chave de autenticação. Seja usando uma integração aplicativo a aplicativo ou uma interface de usuário personalizada, seu aplicativo precisa de um aplicativo conectado no Salesforce para permitir que o Salesforce identifique qual aplicativo está fazendo as solicitações e para liberar o gerenciamento do acesso às APIs pelos administradores da organização.

Usuário único

Com uma integração aplicativo a aplicativo, o aplicativo precisa conhecer as credenciais de um único usuário de integração. Desse jeito, a API REST pode ser chamada para se fazer login com as credenciais, o que retornará um token de autenticação.

Usuários denominados

Durante a criação de uma interface de usuário personalizada, o aplicativo nunca recebe credenciais reais. Em vez disso, o processo OAuth fornece um código ao aplicativo para obter um token de autorização. Como o usuário autoriza o acesso do aplicativo ao Salesforce manualmente, o fluxo segue estas etapas:

  1. O usuário tenta visitar a página que exige autenticação.
  2. O aplicativo na Heroku redireciona o usuário para a página OAuth do Salesforce.
  3. Se o aplicativo não foi autorizado de antemão, o usuário é solicitado a pedir autorização.

Captura de tela da caixa de diálogo Permitir acesso, que aparecerá perguntando se o Workbench está autorizado

  1. Depois de autorizado, o Salesforce redireciona o usuário para o aplicativo com um código.
  2. O aplicativo usa o código para obter um token de acesso e um token de atualização.
  3. O aplicativo usa o token de acesso para fazer chamadas à API REST ao Salesforce.

Normalmente, os tokens de acesso e de atualização são criptografados e armazenados em algum tipo de estado de sessão ou banco de dados para que o usuário não tenha que continuar no fluxo de autorização a cada solicitação.

Lembre-se: estes tokens são confidenciais e devem ser tratados com o máximo de cuidado e segurança!

Recursos