Usar a API em massa
Objetivos de aprendizagem
- 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
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
Criar um trabalho 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.
- 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.
{ "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.

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
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.
"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.

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
{ "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
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
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!