Usar a API em massa 2.0

Objetivos de aprendizagem

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

• Descrever como uma solicitação assíncrona difere de uma solicitação síncrona.
  
• Criar um trabalho em massa usando o aplicativo da web Postman.
  
• Importar dados para sua organização do Salesforce adicionando dados a um trabalho.
  
• Monitorar o progresso de um trabalho.
  
• Obter os resultados de um trabalho.
  

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.

API em massa e solicitações assíncronas

A API em massa é baseada em princípios REST e é otimizada para trabalhar com grandes conjuntos de dados. Você pode usá-la para inserir, atualizar, inserir e atualizar, ou excluir muitos registros de forma assíncrona, isto é, você envia uma solicitação e volta depois para saber os resultados. O Salesforce processa a solicitação em segundo plano.

Por outro lado, a API SOAP e a API REST usam solicitações síncronas e são otimizadas para aplicações de cliente em tempo real que atualizam alguns registros por vez. Você pode usar essas duas APIs para processar muitos registros mas, quando os conjuntos de dados contêm centenas de milhares de registros, elas são menos práticas. A estrutura assíncrona da API em massa é desenvolvida para facilitar e deixar mais eficiente o processamento de dados de alguns milhares até milhões de registros.

A forma mais fácil de usar a API em massa é habilitá-la para processar registros no Data Loader usando arquivos CSV. Com o Data Loader, você não precisa compilar seu próprio aplicativo cliente. À vezes, contudo, solicitações únicas implicam escrever um aplicativo personalizado. A API em massa deixa você tomar o controle da situação e comandar o trajeto até uma solução que funciona para você.

Nesta unidade, use uma versão da API em massa chamada API em massa 2.0. Se quiser aplicar o que aprendeu nesta unidade à versão anterior da API em massa que ainda tem suporte, você precisará usar URIs de recurso diferentes e criar e gerenciar lotes e trabalhos. Para obter mais informações sobre a versão anterior da API em massa, consulte Guia do desenvolvedor de API em massa.

Configurar Playground e Postman

Para explorar a API em massa, você usará o Postman para criar alguns registros de conta.

1. Faça login no Trailhead Playground.
   
2. Faça login no aplicativo da web Postman.
   
3. Conecte seu Playground ao Postman obtendo um novo token.
   
4. Teste para ver se sua conexão está trabalhando com o recurso REST GET Limites.
   

Você aprendeu a fazer isso no Início rápido: Conecte o Postman ao Salesforce, então reveja esse projeto se você não tiver certeza sobre qualquer um dos passos.

Criar um trabalho em massa

O primeiro passo é criar um trabalho no seu fork de Coleção de APIs Salesforce. Um trabalho especifica o tipo de operação e o objeto de dados com os quais você está trabalhando. Ele funciona como uma partição à qual você adiciona dados para processamento.

1. Em Coleções, abra a pasta Bulk v2.
   
2. Clique em POST Create job (Criar trabalho POST).
   

Uma vez que a API em massa é baseada em REST, a solicitação assume o formato familiar de uma solicitação REST com quatro componentes: URI, método HTTP, cabeçalhos e corpo. O método HTTP é POST.

Observe o URI criado na janela principal após clicar no recurso na coleção: /services/data/v{{version}}/jobs/ingest. Vamos observar algumas coisas sobre este URI.

• Você está usando /services/data, que é o mesmo ponto de extremidade usado para a API REST. A API em massa usa a mesma estrutura usada pela API REST, o que significa que a API em massa dá suporte a vários recursos iguais, como a autenticação OAuth.
  
• /jobs/ingest indica que você está acessando o recurso para criar trabalhos da API em massa.
  

Vamos criar o corpo da solicitação.

Para criar um trabalho de API em massa 2.0, use o campo de solicitação lineEnding para especificar o término de linha usado para criar o texto CSV formatado. API em massa 2.0 dá suporte a dois formatos de término de linha: avanço de linha (LF) e retorno de carro seguido de avanço de linha (CRLF). O valor lineEnding padrão, se não for especificado, é LF . Sistemas operacionais diferentes usam caracteres diferentes para marcar o fim de uma linha:

• Unix / Linux / OS X usa LF (avanço de linha, '\n', 0x0A)
  
• Windows / DOS usa CRLF (retorno de carro seguido de avanço de linha, '\r\n', 0x0D0A)
  

Observe que os editores de texto usados para criar um arquivo CSV podem estar configurados para um formato específico de término de linha que substitui o formato padrão do sistema operacional.

1. Copie e cole o corpo CSV de exemplo do seu navegador para um editor de texto para remover a formatação. Indique o término de linha adequado usando o campo de solicitação lineEnding com base no SO e no editor de texto usados. No exemplo, estamos usando um computador com Windows em que "CRLF" é o valor do parâmetro lineEnding.
   

{
"operation" : "insert",
"object" : "Account",
"contentType" : "CSV",
"lineEnding" : "CRLF"
}

     2. Clique em Save (Salvar).

3. Clique em Enviar e verifique a resposta.

A resposta inclui todo o tipo de propriedades sobre o trabalho, mas a maioria ainda não tem utilidade para nós porque você ainda não adicionou dados. No entanto, vamos dar uma olhada em algumas coisas. 

1. Veja a linha "id". Ela mostra o ID do trabalho retornado para este trabalho.
   

1. Agora, na seção Solicitar, clique na guia Testes.
   
2. Este script adiciona automaticamente o ID de trabalho à variável __jobID. Isso injeta o jobID em solicitações futuras para que você não precise copiar e colar.
   

2. Em seguida, veja a propriedade "state” (estado).
   

1. Quando você cria um trabalho, ele é imediatamente definido para o estado Open. Isso significa que ele está pronto para começar a receber dados.
   

3. Por fim, veja a propriedade "contentUrl".
   

1. Essa propriedade mostra a URL que você usa para carregar os dados do trabalho.
   

Adicionar dados ao trabalho

Agora, você pode inserir dados de contas ao nosso trabalho. Os dados de um trabalho são enviados ao servidor como um conjunto de registros em uma solicitação PUT. O servidor processa o conjunto de registros determinando a melhor maneira de carregar os dados no Salesforce. Tudo o que você precisa fazer é carregar os dados.

Crie uma nova solicitação no Postman. No seu fork da Coleção de APIs Salesforce, na pasta Bulk v2, clique em PUT Carregar dados do trabalho. Observe que o método HTTP é PUT.

Para este exemplo, você adiciona um conjunto de registros com apenas quatro contas. Geralmente, usamos a API em massa para adicionar milhares ou milhões de registros, mas o princípio é o mesmo. Você pode carregar um arquivo CSV selecionando o botão de opção binário e carregando seu arquivo .csv, ou você pode colar em uma lista. Neste exemplo, vamos colar em uma lista.

1. Clique na guia Corpo e selecione Dados brutos na lista suspensa.
   
2. Copie o texto a seguir em um editor de texto para limpar qualquer formatação extra e, em seguida, copie-o do arquivo de texto para o campo do corpo de solicitação.
   

"Name"
"Global Treasures & Mapping Company"
"Ahab’s Mighty Masts"
"Planks R Us"
"Cap’n Cook’s Kitchen Supplies"

3. Clique em Cabeçalhos. Observe que o Tipo de conteúdo diz text/csv. Isso porque você especificou o tipo de conteúdo em sua primeira solicitação.

     4. Clique em Save (Salvar).

5. Clique em Enviar.

A resposta contém apenas um código do status 201 Criado, o que indica que o Salesforce recebeu os dados do trabalho com êxito.

Fechar o trabalho

Agora que enviou seus dados, você precisa avisar ao Salesforce que é hora de processá-los. 

1. Em seu fork de APIs Salesforce, Bulk v2, pasta Consulta, clique em PATCH Fechar ou abortar um trabalho.
   
2. Clique na guia Body (Corpo) e observe que "state”: já está preenchido com "UploadComplete".
   

     3. Clique na guia Cabeçalhos e observe que o tipo de conteúdo está definido como application/json.

4. Clique em Enviar.

A resposta contém informações de status de trabalho. A propriedade state indica que o estado do trabalho é UploadComplete. Nessa hora, o Salesforce começa a processar o trabalho.

Verificar o status do trabalho

Você enviou seus dados e avisou o Salesforce que você terminou de carregar dados. Agora, cabe ao servidor processar a solicitação. Você pode monitorar o progresso do servidor verificando o status do trabalho por meio da interface do usuário do Salesforce ou da API. Vamos dar uma olhada em cada método.

Veja como verificar o status do trabalho no seu Trailhead Playground. 

1. Em Setup (Configuração), digite Bulk Data Load Jobs (Trabalhos de carregamento de dados em massa) na caixa Busca rápida
   
2. Selecione Trabalhos de carregamento de dados em massa.
   

Você pode verificar o status de um trabalho nesta página. Ou pode clicar em uma ID de trabalho para verificar os status e obter resultados detalhados sobre esse trabalho.

Veja como você verifica o status do trabalho no Postman na pasta Bulk v2.

1. Selecione GET Informações do trabalho. Observe que o método http usado para este tipo de solicitação é GET.
   
2. Clique em Enviar.
   

Você verá algo assim.

Se seu estado ainda for UploadComplete em vez de JobComplete, significa que o Salesforce ainda está processando o trabalho. Não se preocupe, ele será processado em alguns minutos. Por enquanto, vá buscar um copo de leite e tente a mesma solicitação novamente quando voltar. Se você tiver sorte e seu trabalho já tiver sido processado, procure obter os resultados do trabalho.

Obter resultados de trabalhos

Quando um trabalho alcança o estado JobComplete (ou o estado Failed), você pode obter informações sobre o resultado na forma de registros processados com êxito ou falha.

Vamos ver primeiro os registros processados com êxito na pasta Bulk V2.

1. Clique no recurso GET Obter resultados de registros de trabalhos processados com êxito. Observe que o método HTTP é GET.
   
2. Clique em Enviar. Você verá algo assim.
   

O Salesforce retorna uma lista de todos os registros no trabalho que foram processados com êxito. Neste módulo, você criou vários registros de conta. A linha 1 mostra os tipos de valor das respostas retornadas abaixo dela. Os dados da lista contêm os IDs dos registros criados, um valor true para as colunas sf__Created e os nomes das contas criadas. Ótimo trabalho! 

Às vezes, alguns registros não podem ser processados. É possível que o trabalho tenha tentado criar registros de conta que já existiam. Ou que os dados do trabalho não tivessem alguns campos obrigatórios preenchidos. Nesses casos, você pode pedir ao Salesforce uma lista de registros com erro durante o processamento, além de outras informações sobre o que deu errado. Vamos dar uma olhada nos registros com falha na pasta Bulk v2.

1. Selecione o recurso Obter resultados de registros de trabalhos processados com falha. Note que o método HTTP é, novamente, GET.
   
2. Clique em Enviar. Os resultados têm mais ou menos essa aparência.
   

O Postman fornece uma lista contendo uma lista de registros com erro durante o processamento, além de um ID de registro e da mensagem de erro. Como todos os registros foram inseridos com êxito aqui, a lista de registros está vazia. Bom trabalho!

Recursos

• Guia do desenvolvedor: Bulk API 2.0 Developer Guide
  
• Guia do desenvolvedor: Guia do desenvolvedor da API em massa (uma versão anterior da API em massa não abordada nesta unidade)