Usar a API REST

Objetivos de aprendizagem

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

• Fazer login no aplicativo Postman e navegar até a pasta REST na Coleção de APIs do Salesforce.
• Usar o recurso GET SObject Descrição.
• Criar uma conta usando a API REST.
• Executar uma consulta usando a API REST.

Nota

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Recursos e métodos REST

Você vai usar o Postman para fazer algumas chamadas de API. Você pode fazer solicitações REST de qualquer remetente HTTP. E o Postman é apenas uma das muitas ferramentas que você pode usar para interagir com sua organização Salesforce por meio da API.  

O primeiro passo é criar um novo Trailhead Playground, conectá-lo ao aplicativo Postman, configurar o compartilhamento de recursos de origem cruzada e criar um fork para a Coleção de APIs do Salesforce. Você pode fazer isso concluindo o Início rápido: Conecte o Postman ao Salesforce. 

Você pode fazer chamadas de API REST para o seu Trailhead Playground usando os recursos na pasta REST da coleção do Salesforce do aplicativo Postman, assim como você faria de qualquer outra interface HTTP. Quando você seleciona um recurso da Coleção de APIs do Salesforce, o URI é criado na parte superior da janela principal. 

Descrever o objeto de conta

Vamos dar uma olhada em como isso funciona.

Você usará o recurso SObject Descrição. Este recurso, quando combinado com o método GET, retorna metadados sobre um objeto e seus campos. Vamos descrever o objeto de conta. 

1. Em Coleções, selecione seu fork da Coleção de APIs do Salesforce.
2. Clique na pasta REST.
3. Clique em SObject.
4. Clique em GET SObject Descrição.
5. No painel principal, abra a guia Params.
6. Em Variáveis de caminho, na linha SOBJECT_API_NAME, coluna VALUE, digite Conta.

Antes de dar uma olhada nos resultados da sua consulta, vamos parar um minuto para explicar o URI deste recurso.

• GET – O método HTTP usado para esta chamada de API.
• {{_endpoint}} – O local onde a solicitação ocorrerá. Neste caso, você adicionou a URL do seu Trailhead Playground ao campo _endpoint nas variáveis para se conectar ao Salesforce.
• /services/data – Especifica que você está fazendo uma solicitação à API REST.
• /v {{version}} – O número da versão API. As chaves duplas indicam que essa parte pode ser definida como uma variável.
• /sobjects – Especifica que você está acessando um recurso no agrupamento sObject.
• /:SOBJECT_API_Name – O sObject sendo acionado; neste caso, Conta.
• /describe – Uma ação; neste caso, uma solicitação de Descrição.

Bom trabalho! Os metadados da Conta aparecem na tela, e o Postman formatou bem a resposta. Para ver a resposta JSON bruta, clique em Dados brutos.

Os metadados da Conta são exibidos no JSON. Uma vez que a API REST aceita tanto JSON quanto XML, vamos alterar o cabeçalho de solicitação para especificar uma resposta XML. 

1. Na janela de solicitação, clique em Cabeçalhos.
2. Adicione um novo Cabeçalho com uma Key de Accept (Aceitar) e Value (Valor) de application/xml.

Seu cabeçalho de solicitação tem essa aparência.

{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

{
"ShippingCity" : "Melbourne"
}

SELECT Name From Account WHERE ShippingCity = 'Melbourne'

Amostras Node.js e Ruby

const jsforce = require("jsforce");const conn = new jsforce.Connection({
  // you can change loginUrl to connect to sandbox or prerelease env.
  // loginUrl : "https://test.salesforce.com"
});
// Log in with basic SOAP login (see documentation for other auth options)
conn.login(
  process.env.USERNAME,
  process.env.PASSWORD + process.env.SECURITY_TOKEN,
  (err, res) => {
    if (err) {
      return console.error("Failed to log in to Salesforce: ", err);
    }
    console.log("Successfully logged in!");
    // Run a SOQL query
    conn.query("SELECT Id, Name FROM Account LIMIT 5", (err, result) => {
      if (err) {
        return console.error("Failed to run SOQL query: ", err);
      }
      // Display query results
      const { records } = result;
      console.log(`Fetched ${records.length} records:`);
      records.forEach(record => {
        console.log(`- ${record.Name} (${record.Id})`);
      });
    });
  }
);

require 'restforce'
# create the connection with the Salesforce connected app
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']
# execute the query
accounts = client.query("select id, name from account limit 5")
# output the account names
accounts.each do |account|
  p account.Name
end

Recursos