Skip to main content
Join the Agentforce Hackathon on Nov. 18-19 to compete for a $20,000 Grand Prize. Sign up now. Terms apply.

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

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

Terra à vista! Vemos a ilha de REST adiante, capitão! Antes de atracar e começar a usar a API, vamos falar sobre recursos e métodos REST.

Um recurso REST é uma abstração de uma informação ou de uma ação, tal como um registro de dados individual, uma coleção de registros ou uma consulta. Cada recurso na API REST é identificado por um URI (Uniform Resource Identifier, Identificador de Recurso Uniforme) e é acessado usando métodos HTTP padrão (HEAD, GET, POST, PATCH, DELETE). A API REST é baseada no uso de recursos, seus URIs e os links entre eles.

Você usa um recurso para interagir com sua organização do Salesforce. É possível, por exemplo:
  • Obter informações resumidas sobre as versões de API disponíveis para você.
  • Obter informações detalhadas sobre um objeto Salesforce, como Conta, Usuário, ou sobre um objeto personalizado.
  • Fazer uma consulta ou pesquisa.
  • Atualizar ou excluir registros.

Uma solicitação REST consiste em quatro componentes: um URI de recurso, um método HTTP, cabeçalhos de solicitação e um corpo da solicitação. Cabeçalhos de solicitação especificam metadados para a solicitação. O corpo da solicitação especifica dados para a solicitação, quando necessário. Caso não haja dados para especificar, o corpo é omitido da solicitação.

Antes de prosseguir

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.

Janela de solicitação do Postman mostrando o URI do SObject Descrição.


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.
     7. Clique em Salvar.
     8. Clique em Enviar.

Janela de resposta do Postman mostrando os metadados do objeto Conta.

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.

Janela de solicitação do Postman mostrando o campo de valor de Cabeçalhos definido para application/xml.

     3. Clique em Enviar.

A resposta XML bruta é retornada. Oba!

Criar uma conta

Vamos agora criar uma conta usando o recurso SObject e o método POST. 

Para criar uma conta:

  1. Em REST, selecione SObject e, em seguida, selecione POST SObject Criação.
  2. Abra a guia Params.
  3. Em Variáveis de caminho, na linha SOBJECT_API_NAME, coluna VALUE, digite Conta.
  4. Abra a guia Corpo.
  5. Substitua o texto do corpo por este código:
{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

Janela de solicitação do Postman mostrando o URI do SObject POST e no campo Corpo, detalhes da conta que está sendo criada.

6. Clique em Salvar.
7. Clique em Enviar.

Janela de resposta do Postman mostrando o id da conta criada.

Se success: true, a conta foi criada com a ID retornada. 

Para animar, vamos criar uma segunda conta sem especificar um nome de conta. 

  1. Substitua o texto no corpo da solicitação pelo seguinte texto.
{
"ShippingCity" : "Melbourne"
}

Janela de solicitação do Postman mostrando novos detalhes de uma nova conta.

2. Clique em Enviar.

Oh, não! Você recebeu a resposta "Um ou mais campos obrigatórios não foram preenchidos: [Nome]"? 

Janela de resposta do Postman mostrando um erro informando que o campo Nome está faltando na solicitação.

Uma vez que Nome é um campo obrigatório para criar uma conta, o servidor não processou a solicitação e você recebeu um erro. Felizmente, todas as informações que você precisa para corrigir a solicitação estão na resposta de erro. Vamos especificar o nome da conta, Pedro Pirata e seu Papagaio, no corpo de solicitação. 

  1. Substitua o texto no corpo da solicitação pelo seguinte texto.
{
"Name": "Pirate Pete's Parrot Pellets",
"ShippingCity": "Melbourne"
}

     2. Clique em Salvar.
3. Clique em Enviar.

Sucesso!

Executar uma consulta

Vamos agora imaginar que você ou outro usuário criou centenas de contas. Você quer encontrar os nomes de todas as contas em que a cidade de envio é Melbourne. Você pode usar o recurso Consulta para executar uma consulta SOQL para concentrar-se nos registros exatos desejados, como em um mapa do tesouro personalizado.

  1. Em REST, selecione GET Consulta.
  2. Abra a guia Params.
  3. Em Consulta Params, na linha q, coluna VALUE, cole o texto a seguir.
SELECT Name From Account WHERE ShippingCity = 'Melbourne'

Janela de solicitação do Postman mostrando a guia Params onde o valor de KEY q está pedindo nomes de conta de onde a cidade de transporte é Melbourne.

4. Clique em Salvar.
5. Clique em Enviar.

A consulta devolve a conta que você acabou de criar, Pedro Pirata e seu Papagaio. Bom trabalho!

Dê uma olhada nos atributos. Ao lado do “url” está o URI do recurso da conta que foi retornada. Sua resposta tem mais ou menos essa aparência.

Janela de resposta do Postman mostrando uma conta retornada onde a cidade de transporte é Melbourne. Essa é a conta Pedro Pirata e seu Papagaio.

Quando você escreve uma integração, você pode pegar esse URI da resposta para acessar mais detalhes sobre essa conta.

Amostras Node.js e Ruby

Agora você já tem um gostinho do que é possível fazer com a API REST. É claro que quando você mudar do Postman para escrita de código, você estará interagindo com a API REST usando sua linguagem de programação preferida. Felizmente, desenvolvedores especialistas em Salesforce escreveram wrappers para várias linguagens que simplificam o processo de consumo da API REST. Aqui estão duas consultas de amostra escritas em Node.js e Ruby que usam wrappers JSforce e Restforce, respectivamente.

Amostra Node.js usando JSforce

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})`);
      });
    });
  }
);

Amostra Ruby usando Restforce

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
Compartilhe seu feedback do Trailhead usando a Ajuda do Salesforce.

Queremos saber sobre sua experiência com o Trailhead. Agora você pode acessar o novo formulário de feedback, a qualquer momento, no site Ajuda do Salesforce.

Saiba mais Continue compartilhando feedback