Usar a API em massa 2.0

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 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 que costumam 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"
}

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

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

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 Configuração, digite 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 de API em massa (uma versão anterior da API em massa não abordada nesta unidade)