Pular para o conteúdo

Lê um objeto do Salesforce — padrão ou personalizado — para uma tabela de projeto através da Bulk API 2.0 do Salesforce. Escolha a ligação Salesforce, o objeto e os campos; o passo constrói a consulta, pagina todo o conjunto de resultados e carrega cada coluna com o tipo que o Salesforce declara para ela. Não há nenhuma consulta para escrever.

O Salesforce é acedido diretamente na nuvem através da sua API REST, pelo que este passo não precisa de um agente PlaidLink.

Campo Obrigatório Notas
Ligação Salesforce Sim A ligação Salesforce através da qual ler. As ligações são geridas em Ferramentas > Ligações.
Ambiente Não Qual dos ambientes da ligação ler — aponte um ambiente de sandbox para a organização sandbox e um de produção para a produção. Ambiente do projeto (a predefinição) utiliza o ambiente da ligação do projeto. Ambiente fixo utiliza sempre o que escolher. Consulte Fixar um passo a um ambiente.
Objeto Sim O nome da API do objeto — Account, Opportunity, Invoice__c. O seletor lista os objetos que o utilizador Run As da ligação pode consultar e também aceita um nome escrito, para que um passo guardado continue a funcionar enquanto a descoberta não estiver disponível.
Tabela de destino Sim A tabela de projeto onde as linhas são carregadas.
Incluir registos eliminados e arquivados Não Lê também os registos do Recycle Bin e as atividades arquivadas, tal como faz um queryAll do Salesforce.
Campos Sim Marque os campos a extrair. É necessário pelo menos um: a Bulk API 2.0 rejeita uma seleção do objeto inteiro, pelo que a lista de colunas é sempre enumerada.
Filtro Não Restringe a extração no Salesforce. Veja Filtrar no Salesforce.
Etiqueta da janela Não Dá nome à janela de extração. Veja As janelas de extração são executadas uma só vez.

Id é sempre incluído, quer o marque ou não — é a chave sobre a qual cada nova execução faz a fusão. Um campo de moeda também traz o seu CurrencyIsoCode quando o objeto tem um.

Pré-visualização no separador Origem mostra até 100 linhas do que o passo leria, sem o executar. As variáveis no filtro são preenchidas da forma como uma execução as preenche, mas formatos de variáveis como {x:>9} não são suportados. A pré-visualização não está disponível num projeto bloqueado. Se o filtro usar algo que a pré-visualização não consegue verificar como só de leitura, indica-lhe que execute o passo.

Cada execução lê o objeto por inteiro, sujeito ao seu filtro, e funde cada página na tabela de destino por Id. Uma linha já existente na tabela é substituída no local, pelo que uma execução interrompida que é retomada não volta a carregar nada duas vezes.

As colunas carregadas usam os tipos que o Salesforce declara nos seus próprios metadados de campo, nunca um tipo deduzido a partir da primeira página de dados. A coluna Resulta em no seletor de campos é esse tipo declarado, pelo que a forma que aprova no formulário é a forma que a tabela recebe.

Tipo de campo do Salesforce Resulta em
id, reference, string, textarea, phone, url, email, picklist, multipicklist, combobox texto
boolean booleano
date data
datetime data e hora
time hora
int inteiro, ou um inteiro de 64 bits quando o campo declara 10 ou mais dígitos
double, currency, percent numérico — um decimal largo, 38 dígitos com 10 casas decimais

Três convenções decorrem dessa tabela e vale a pena conhecê-las antes de construir sobre a saída:

  • A moeda é carregada como número, não como tipo de moeda. As organizações reais declaram campos de moeda com escalas de 0, 2, 3 e 4, pelo que todos os tipos numéricos são carregados num decimal suficientemente largo para todos. Não há símbolo de moeda na coluna nem restrição de casas decimais por campo. Quando o objeto tem CurrencyIsoCode, essa coluna acompanha o campo de moeda para que o montante mantenha a sua moeda; uma organização de moeda única não tem esse campo no objeto, e nenhum é inventado.
  • Uma percentagem é o número inteiro que o Salesforce comunica. 20 significa 20 por cento, não 0.2. Nada é reescalado à entrada.
  • Um valor vazio é carregado como NULL. Os resultados em massa não conseguem distinguir um nulo verdadeiro de uma cadeia vazia explícita, pelo que ambos são carregados como NULL — em todas as colunas, incluindo as de texto. Uma coluna que tenha de manter a semântica de cadeia vazia precisa de um campo de fórmula do lado do Salesforce.

Alguns tipos de campo do Salesforce não podem ser carregados com rigor, pelo que o seletor de campos os marca como inutilizáveis e indica o motivo em vez de o deixar guardar um passo que falha em tempo de execução. Cada recusa nomeia o campo e o seu tipo no Salesforce.

Tipo de campo do Salesforce Porquê O que fazer em alternativa
address, location (campos compostos) Um campo composto não tem um valor diretamente legível numa consulta em massa. Marque os respetivos campos componentes — BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry e a latitude e longitude da geolocalização. O seletor nomeia os componentes do campo que tem à frente.
base64 O conteúdo de ficheiros e blobs nunca é devolvido em linha; precisa de uma transferência binária separada que este passo não faz. Leia os outros campos do registo e trate os anexos em separado.
encryptedstring O Salesforce devolve um valor mascarado em vez de um erro quando o utilizador Run As não tem View Encrypted Data, e nada distingue dados mascarados de dados reais. Carregar em silêncio linhas de asteriscos é pior do que recusar. Decida deliberadamente se os dados devem sair do Salesforce; não existe forma suportada de os extrair através deste passo.
anyType O tipo real pode variar de linha para linha, e uma coluna de tabela tem exatamente um tipo. Extraia um campo com tipo, ou um campo de fórmula que apresente o valor como texto.
Qualquer tipo que o passo não reconheça Recusado em vez de carregado como texto, o que alteraria discretamente o significado do valor. Comunique-o ao suporte para que o tipo obtenha um mapeamento.

As janelas de extração são executadas uma só vez

Seção intitulada “As janelas de extração são executadas uma só vez”

A Etiqueta da janela dá nome à janela de dados que uma execução está a carregar — um período ou uma etiqueta de lote como 2026-09. Aceita variáveis do fluxo de trabalho: uma etiqueta {period} resolve para o valor dessa variável sempre que o passo é executado.

Uma janela de extração é executada uma só vez. Voltar a executar uma janela que já foi concluída não volta ao Salesforce: o passo comunica claramente que não voltou a ler e diz que a contagem de linhas que mostra pertence à execução anterior. Isto é uma operação nula ruidosa, não silenciosa, e é o comportamento que impede uma nova execução de paginar uma segunda cópia de um conjunto de resultados que já carregou.

Há três formas de usar o passo:

  • Deixe a etiqueta em branco e trate o passo como um carregamento único. A primeira execução lê; uma segunda execução desse mesmo passo repete e comunica que não voltou a ler. Use isto para construir e validar a extração e para uma tabela que carrega uma só vez.
  • Escreva uma etiqueta e altere-a quando carregar a janela seguinte — 2026-09 e depois 2026-10. Editar a etiqueta inicia uma nova janela, pelo que um carregamento mensal que alguém avança à mão funciona exatamente como se lê.
  • Construa a etiqueta a partir de uma variável do fluxo de trabalho para uma extração recorrente sem supervisão — por exemplo {period}, definida por um passo anterior do fluxo de trabalho com o período que está a ser carregado. Cada execução agendada dá nome à sua própria janela, e uma nova execução dentro do mesmo período retoma ou repete essa janela em vez de iniciar outra.

Um chamador da API REST ou MCP passa extract_tag diretamente e fornece ele próprio um valor distinto por janela.

Uma execução que foi interrompida retoma a mesma janela, por isso mantenha a etiqueta constante enquanto essa janela puder ainda precisar de terminar. Alterar a etiqueta inicia uma nova janela e uma nova consulta no Salesforce. Altere a etiqueta sempre que alterar o filtro ou os campos: editar a configuração sob uma etiqueta que já foi executada é recusado como conflito.

Restrinja a extração no Salesforce em vez de trazer o objeto inteiro e filtrar depois. Cada termo do filtro é um campo, um operador e um valor; os termos combinam-se com AND. Um valor pode usar uma variável do fluxo de trabalho, como {region}.

Operador Notas
=, !=, <, <=, >, >= Comparado com o valor tal como foi escrito.
LIKE Use % como carácter universal, por exemplo Acme%.
IN, NOT IN Indique uma lista de valores separados por vírgulas.

Tanto o campo como o operador são verificados em relação aos campos que selecionou antes de a consulta ser construída, e não há nenhuma cláusula WHERE de texto livre para escrever — pelo que um filtro não pode ir além da extração. Filtre por um campo que também tenha marcado; um filtro que nomeie um campo que a extração não seleciona é recusado.

O passo não oferece limite de linhas nem ordenação. A Bulk API 2.0 desativa a sua própria divisão interna em blocos quando uma consulta tem qualquer um deles, o que torna uma extração grande mais lenta e mais propensa a exceder o tempo limite. Critérios de filtro seletivos são o remédio do próprio Salesforce para uma consulta demasiado grande ou demasiado lenta.

Esta forma — ler o objeto por inteiro, de forma agendada — convém a objetos de volume e variação moderados: Accounts, Opportunities, Leads, Campaigns e objetos personalizados de dimensão semelhante.

É a ferramenta errada para objetos de grande volume e grande variação como Task, EmailMessage ou um objeto personalizado grande com milhões de linhas a mudar diariamente. Uma extração completa noturna desses objetos gasta tempo real e capacidade da API que uma sincronização incremental não gastaria. Quando o objeto é grande mas só parte dele interessa, um filtro que delimite a extração — um intervalo de datas, um tipo de registo, um proprietário — transforma-a de novo numa extração de volume moderado.

O que vê O que aconteceu O que fazer
Um erro de que a tarefa ainda está em execução após 15 minutos O passo espera em primeiro plano que o Salesforce conclua a consulta, e essa espera é limitada. Nada faz avançar a tarefa em segundo plano. O passo falha, para que os passos seguintes não sejam executados sobre uma tabela que esta extração não escreveu. Retome o fluxo de trabalho ou volte a executar o passo. Retoma a espera na mesma tarefa do Salesforce e nunca submete uma segunda. Se continuar a exceder o limite, restrinja a extração com critérios de filtro.
Um aviso de que a janela já foi concluída e não foi relida A janela foi executada anteriormente. A contagem de linhas mostrada é a da execução anterior. Execute a extração com uma Etiqueta da janela distinta, ou avance a variável a partir da qual a etiqueta é construída — veja As janelas de extração são executadas uma só vez.
Um erro que nomeia uma tarefa falhada ou abortada Uma tarefa de consulta em massa falhada não produz resultados parciais e não pode ser retomada. A janela está agora esgotada. Volte a executar com uma Etiqueta da janela distinta. Voltar a executar a mesma janela repete a falha e não submete nada, e editar a configuração do passo sob a mesma etiqueta é recusado como conflito.
Uma recusa que nomeia o limite de pedidos do Salesforce O limite de pedidos de API de 24 horas da organização está esgotado. O Salesforce não documenta nenhum retry-after para ele. Aguarde que a janela seja libertada e depois volte a executar — a extração continua a poder ser retomada, nada se perdeu.
Uma recusa que nomeia um campo e o seu tipo no Salesforce Esse tipo de campo não pode ser carregado, ou o utilizador Run As não pode ler o campo. Veja Campos que o passo recusa e a segurança ao nível do campo do utilizador Run As.

O Salesforce mantém recuperáveis durante 7 dias os resultados de uma tarefa de consulta concluída, o que torna uma extração interrompida retomável — e o que limita durante quanto tempo uma retoma pode esperar antes de os resultados desaparecerem. As tarefas são visíveis no Salesforce em Setup > Environments > Jobs > Bulk Data Load Jobs.