Usar a API em massa

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 REST Explorer no Workbench.
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.

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.

Importar dados para sua organização

Para explorar a API em massa, usaremos o Workbench para criar alguns registros de conta.

Criar um trabalho em massa

A API em massa é baseada em REST, então podemos usar o REST Explorer do Workbench para fazer solicitações da API em massa.

Faça login no Trailhead Playground e acesse o Workbench.
Em Ambiente, selecione Produção. Em Versão da API, selecione o número mais alto disponível. Certifique-se de marcar a opção Concordo com os termos de serviço.
Clique em Login com o Salesforce.
No menu superior, selecione utilitários | REST Explorer.

Agora estamos prontos para carregar nossos dados. A primeira etapa é criar um trabalho. Um trabalho especifica o tipo de operação e objeto de dados com o qual estamos trabalhando. Ele funciona como uma partição à qual adicionamos dados para processamento.

Usaremos o recurso /jobs/ingest para criar um trabalho. Esse recurso também pode ser usado para obter uma lista de trabalhos atuais.

Para criar um trabalho, enviamos uma solicitação POST para /jobs/ingest com as propriedades do trabalho no corpo da solicitação. 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 é POST, conforme já mencionamos.

Para o URI, substitua o texto na caixa de texto de URI pelo seguinte: /services/data/v XX.0/jobs/ingest, onde XX.0 corresponde à versão da API que você está usando. Vamos observar algumas coisas sobre este URI.

Estamos 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 estamos acessando o recurso para criar trabalhos da API em massa.

Para o corpo da solicitação, copie e cole o texto a seguir.

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

Essas propriedades indicam que queremos usar a operação de inserir nos dados que enviamos para o trabalho. Estamos enviando dados de conta em formato CSV. A API em massa aceita cargas em CSV.

Seu REST Explorer tem mais ou menos essa aparência.

Criar uma solicitação de trabalho no REST Explorer

Clique em Executar 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 ainda não adicionamos dados. No entanto, queremos anotar algumas propriedades. Veja a ID do trabalho (id) e copie-a para um arquivo de texto. Vamos usá-la para adicionar dados ao trabalho e consultar o status do trabalho. Examine também a propriedade state. Quando você cria um trabalho, ele é imediatamente definido para o estado Open. Isso significa que ele está pronto para começar a receber dados. Por fim, veja a propriedade contentUrl. Essa propriedade mostra a URL que usamos para carregar os dados do trabalho.

Adicionar dados ao trabalho

Agora, podemos 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 Workbench. Substitua o texto na caixa de texto de URI pelo seguinte: /services/data/v XX.0/jobs/ingest/ jobID/batches. Substitua jobID pela ID do trabalho que você copiou. Selecione PUT como o método HTTP.

Para este exemplo, adicionamos 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. Copie o texto CSV a seguir no corpo da solicitação.

"Name"
"Sample Bulk API Account 1"
"Sample Bulk API Account 2"
"Sample Bulk API Account 3"
"Sample Bulk API Account 4"

Estamos usando dados CSV porque foi o que especificamos quando criamos o trabalho.

Clique em Cabeçalhos e altere Content-Type para text/csv. Sua solicitação tem mais ou menos essa aparência.

Adicionar dados do trabalho usando o REST Explorer

Clique em Executar.

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 enviamos nossos dados, precisamos avisar ao Salesforce que é hora de processá-los. Faça isso alterando o estado do trabalho de Open para UploadComplete.

Substitua o texto na caixa de texto de URI pelo seguinte: /services/data/v XX.0/jobs/ingest/ jobID . Novamente, substitua XX pela versão da API que você estiver usando e substitua jobID pela ID do trabalho. Selecione PATCH como o método HTTP. Clique em Cabeçalhos e defina Content-Type como application/json. No corpo da solicitação, substitua o texto pelo seguinte texto JSON.

{
   "state" : "UploadComplete"
}

Clique em Executar. 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

Já enviamos nossos dados. Saímos do Salesforce sabendo que o carregamento dos dados foi concluído. Agora, cabe ao servidor processar a solicitação. Podemos monitorar o progresso do servidor verificando o status do trabalho por meio da API ou da interface de usuário do Salesforce. Em Salesforce, em Configuração, insira Trabalhos de carregamento de dados em massa na caixa Busca rápida e 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.

Na API, usamos o recurso /jobs/ingest/jobID para monitorar um trabalho. Substitua o texto na caixa de texto de URI pelo seguinte: /services/data/v XX.0/jobs/ingest/ jobID, com as substituições habituais. Para o método HTTP, selecione GET.

Clique em Executar. Você verá algo assim.

Se seu state 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 uma xícara de café 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 ou sinta-se à vontade para buscar mais uma xícara de café.

Obter resultados de trabalhos

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

Vamos ver primeiro os registros processados com êxito. No REST Explorer do Workbench, substitua o texto na caixa de texto do URI pelo seguinte: /services/data/v XX.0/jobs/ingest/ jobID/successfulResults, com as substituições habituais. Para o método HTTP, selecione GET.

Clique em Executar. Você verá algo assim.

O Salesforce retorna um CSV contendo uma lista de todos os registros no trabalho que foram processados com êxito. Neste módulo, criamos vários registros de conta. Os dados em CSV contêm a ID do registro criado e um valor true na coluna sf__Created.

À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, podemos pedir ao Salesforce uma lista de registros com erro durante o processamento, além de outras informações sobre o que deu errado.

De volta ao REST Explorer do Workbench, substitua o texto na caixa de texto do URI pelo seguinte: /services/data/v XX.0/jobs/ingest/ jobID/failedResults, com as substituições habituais. Para o método HTTP, selecione GET.

Clique em Executar. Os resultados têm mais ou menos essa aparência.

O Salesforce fornece um CSV contendo uma lista de registros com erro durante o processamento, além de uma 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

Bulk API 2.0 Developer Guide

Bulk API Developer Guide (uma versão anterior da API em massa não abordada nesta unidade)

Workbench

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.

Tópicos