Comece a acompanhar seu progresso
Página inicial do Trailhead
Página inicial do Trailhead

Usar a API REST

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Faça login no Workbench e navegue para o REST Explorer.
  • Use o recurso de descrição.
  • Criar uma conta usando a API REST.
  • Executar uma consulta usando a API REST.

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.

Descrever o objeto de conta

Chegou a hora de colocar a mão na massa. Vamos usar o Workbench para fazer algumas chamadas de API. O Workbench é um conjunto de ferramentas para interação com sua organização do Salesforce por meio da API. Uma vez que você pode fazer solicitações REST a partir de qualquer remetente de HTTP, há muitas outras ferramentas disponíveis para você usar (por exemplo, cURL ou Postman). No entanto, visto que o Workbench fornece uma estrutura amigável especificamente para APIs do Salesforce, é a maneira perfeita de começar antes de você estar pronto para escrever uma integração completa.
A primeira etapa é fazer login no Workbench.
  1. Faça login no Trailhead Playground e acesse o Workbench.
  2. Em Ambiente, selecione Produção.
  3. Para a versão da API, selecione o número mais alto disponível.
  4. Certifique-se de marcar a opção Concordo com os termos de serviço.
  5. Clique em Login com o Salesforce.

Você chegou à página inicial do Workbench. Para este módulo, usamos apenas uma das muitas ferramentas do Workbench, o REST Explorer.

No menu superior, selecione utilitários | REST Explorer.

REST Explorer do Workbench

Você pode fazer chamadas à API REST a partir do REST Explorer do mesmo modo que faria de qualquer outra interface HTTP. O texto na caixa de texto representa um URI de recurso. Por conveniência, o domínio de nível superior é omitido do URI exibido. Por exemplo, o URI completo do recurso que é pré-preenchido na caixa de texto de URI é https://foo.my.salesforce.com/services/data/v36.0.

Os botões de opção acima do URI representam os métodos HTTP padrão. Para fazer uma chamada de API, insira o URI do recurso, selecione o método apropriado e os cabeçalhos necessários e clique em Executar

Vamos experimentar o recurso SObject Describe. Este recurso, quando combinado com o método GET, retorna metadados sobre um objeto e seus campos.

Vamos tentar descrever o objeto de conta. Na caixa de texto de URI, substitua o texto existente por /services/data/vXX.0/sobjects/account/describe, em que XX mapeia para a versão da API que você está usando.

URI para descrever uma conta
Vamos dedicar um tempo para decompor o URI deste recurso.
  • /services/data – Especifica que estamos fazendo uma solicitação à API REST
  • /v36.0 – Número de versão da API
  • /sobjects – Especifica que estamos acessando um recurso no agrupamento sObject
  • /account – sObject sendo acionado; neste caso, conta
  • /describe – Ação; neste caso, uma solicitação de descrição

Verifique agora se o método GET está selecionado e clique em Executar.

Resposta após descrevermos o objeto de conta

Bom trabalho! Os metadados da conta aparecem na tela. E o Workbench formatou muito bem a resposta. Para ver a resposta JSON bruta, clique em Exibir resposta bruta.

Resposta JSON após descrevermos o objeto de conta

Os metadados da conta são exibidos em formato JSON abaixo de alguns cabeçalhos de resposta HTTP. Uma vez que a API REST aceita tanto JSON quanto XML, vamos alterar o cabeçalho de solicitação para especificar uma resposta XML. Perto dos métodos de HTTP, clique em Cabeçalhos. Para o valor de cabeçalho Accept, substitua application/json por application/xml. Seu cabeçalho de solicitação tem essa aparência.

Cabeçalho de solicitação especificando XML

Clique em Executar. A resposta XML bruta é retornada. Oba!

Criar uma conta

Vamos agora criar uma conta usando o recurso SObject e o método POST. Na caixa de texto de URI, substitua o texto existente por /services/data/vXX.0/sobjects/account, em que XX mapeia para a versão da API que você está usando. Selecione POST. Aparece uma área de texto Corpo da solicitação, que é onde especificamos os valores de campo para nossa nova conta. Primeiro, vamos alterar o cabeçalho Accept de volta para JSON.

Clique em Cabeçalhos. Altere Accept: application/xml de volta para Accept: application/json. Sua solicitação tem essa aparência.

Cabeçalhos de solicitação REST
Digite o seguinte texto no corpo da solicitação.
{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

Clique em Executar. Você verá uma resposta como a seguinte.

Resposta de criação de conta bem-sucedida na API REST

Se success: true, a conta foi criada com a ID retornada. Expanda a pasta de erros para verificar erros.

Para animar, vamos criar uma segunda conta sem especificar um nome de conta. Substitua o texto no corpo da solicitação pelo seguinte texto.
{
  "ShippingCity" : "San Francisco"
}

Clique em Executar.

Oh, não! Você recebeu uma resposta REQUIRED_FIELD_MISSING? Expanda a pasta REQUIRED_FIELD_MISSING e, então, expanda a pasta fields. Sua resposta expandida tem essa aparência.

Recebemos um erro quando não fornecemos um nome de conta
Uma vez que Name é um campo obrigatório para criar uma conta, o servidor não processou a solicitação e recebemos um erro. Felizmente, todas as informações que precisamos para corrigir a solicitação estão na resposta de erro. Vamos especificar o nome NewAccount2 e alterar a cidade de envio no corpo da solicitação. Substitua o texto no corpo da solicitação pelo seguinte texto.
{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

Clique em Executar. 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 é São Francisco. Você pode usar o recurso Consulta para executar uma consulta SOQL e concentrar-se nos registros exatos desejados, assim como em um mapa do tesouro personalizado.

Substitua o texto na caixa de texto de URI pelo seguinte texto: /services/data/vXX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco', em que XX mapeia para a versão de API que você está usando.

Substituímos os espaços pelo caractere + na sequência de caracteres de consulta para codificar corretamente o URI. Você pode ler sobre a codificação de URL HTML no link na seção Recursos. Verifique se o método GET está selecionado e clique em Executar.

Expanda a pasta records. Você vê uma pasta com o nome da primeira conta que criamos, NewAccount1? Ótimo. Clique nela. Agora clique na pasta attributes. Ao lado do URL está o URI do recurso da conta que foi retornada. Sua resposta tem mais ou menos essa aparência.

A resposta da consulta retorna um registro de conta

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 Workbench 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 Nforce e Restforce, respectivamente.

Amostra Node.js usando Nforce

var nforce = require('nforce');

// create the connection with the Salesforce connected app
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});

// authenticate and return OAuth token
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // execute the query
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // output the account names
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

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

Recursos

REST API Developer Guide

Getting Started with Salesforce REST in Java

HTML URL Encoding Reference

Workbench
Nota

Nota

Lembre-se: este módulo é destinado ao Salesforce Classic. Quando você iniciar sua organização prática, mude para o Salesforce Classic para concluir este desafio.