Salesforce: Consultar objeto
Descrição
Seção intitulada “Descrição”Lê um objeto do Salesforce, padrão ou personalizado, para uma tabela de projeto pela Bulk API 2.0 do Salesforce. Escolha a conexão do Salesforce, o objeto e os campos; a etapa monta a consulta, pagina todo o conjunto de resultados e grava cada coluna com o tipo que o Salesforce declara para ela. Não há consulta para escrever.
O Salesforce é alcançado diretamente na nuvem pela API REST dele, então esta etapa não precisa de um agente PlaidLink.
Configuração
Seção intitulada “Configuração”| Campo | Obrigatório | Observações |
|---|---|---|
| Conexão do Salesforce | Sim | A conexão do Salesforce pela qual ler. As conexões são gerenciadas em Ferramentas > Conexões. |
| Ambiente | Não | Qual dos ambientes da conexão ler: aponte um ambiente de sandbox para a organização de sandbox e um de produção para a produção. Ambiente do projeto (o padrão) usa o ambiente da conexão do projeto. Ambiente fixo sempre usa o que você escolher. Consulte Fixar uma etapa em um ambiente. |
| Objeto | Sim | O nome de API do objeto: Account, Opportunity, Invoice__c. O seletor lista os objetos que o usuário Run As da conexão pode consultar e também aceita um nome digitado, de modo que uma etapa salva continua funcionando enquanto a descoberta não está disponível. |
| Tabela de destino | Sim | A tabela de projeto em que as linhas são gravadas. |
| Incluir registros excluídos e arquivados | Não | Também lê os registros na Lixeira e as atividades arquivadas, como faz um queryAll do Salesforce. |
| Campos | Sim | Marque os campos a extrair. Pelo menos um é obrigatório: a Bulk API 2.0 rejeita um select do objeto inteiro, então a lista de colunas é sempre enumerada. |
| Filtro | Não | Restringe a extração no Salesforce. Consulte Filtrar no Salesforce. |
| Tag da janela | Não | Dá nome à janela de extração. Consulte Janelas de extração são executadas uma vez. |
Id é sempre incluído, quer você o marque ou não; é a chave sobre a qual toda reexecução faz a mesclagem. Um campo de moeda também traz seu CurrencyIsoCode quando o objeto tem um.
Pré-visualização
Seção intitulada “Pré-visualização”Pré-visualização na guia Origem mostra até 100 linhas do que a etapa leria, sem executá-la. As variáveis no filtro são preenchidas do jeito que uma execução as preenche, mas formatos de variável como {x:>9} não têm suporte. A pré-visualização não está disponível em um projeto bloqueado. Se o filtro usar algo que a pré-visualização não consegue verificar como somente leitura, ela orienta você a executar a etapa.
Como as linhas são gravadas
Seção intitulada “Como as linhas são gravadas”Cada execução lê o objeto por inteiro, sujeito ao seu filtro, e mescla cada página na tabela de destino por Id. Uma linha que já está na tabela é substituída no lugar, de modo que uma execução interrompida que é retomada não grava nada duas vezes.
As colunas gravadas usam os tipos que o Salesforce declara nos metadados dos próprios campos, nunca um tipo deduzido da primeira página de dados. A coluna Gravado como no seletor de campos é esse tipo declarado, então o formato que você aprova no formulário é o formato que a tabela recebe.
O que é gravado como o quê
Seção intitulada “O que é gravado como o quê”| Tipo de campo do Salesforce | Gravado como |
|---|---|
id, reference, string, textarea, phone, url, email, picklist, multipicklist, combobox |
texto |
boolean |
booleano |
date |
data |
datetime |
carimbo de data/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 conhecê-las antes de construir sobre a saída:
- A moeda é gravada como um número, não como um tipo de moeda. As organizações reais declaram campos de moeda com escalas de 0, 2, 3 e 4, então todo tipo numérico é gravado em um decimal largo o bastante para todos eles. 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 valor mantenha sua moeda; uma organização de moeda única não tem esse campo no objeto, e nenhum é inventado. - Um percentual é o número inteiro que o Salesforce informa.
20significa 20 por cento, não0.2. Nada é reescalonado na entrada. - Um valor vazio é gravado como NULL. Os resultados em massa não conseguem distinguir um nulo verdadeiro de uma string vazia explícita, então ambos são gravados como
NULL, em todas as colunas, inclusive de texto. Uma coluna que precisa manter a semântica de string vazia exige um campo de fórmula no lado do Salesforce.
Campos que a etapa recusa
Seção intitulada “Campos que a etapa recusa”Alguns tipos de campo do Salesforce não podem ser gravados de forma fiel, então o seletor de campos os marca como inutilizáveis e informa o motivo, em vez de deixar você salvar uma etapa que falha em tempo de execução. Cada recusa nomeia o campo e seu tipo no Salesforce.
| Tipo de campo do Salesforce | Por quê | O que fazer em vez disso |
|---|---|---|
address, location (campos compostos) |
Um campo composto não tem valor diretamente legível em uma consulta em massa. | Marque seus campos componentes: BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry e a latitude e a longitude da geolocalização. O seletor nomeia os componentes do campo que está diante de você. |
base64 |
O conteúdo de arquivos e blobs nunca é retornado em linha; ele exige um download binário separado que esta etapa não faz. | Leia os outros campos do registro e trate os anexos separadamente. |
encryptedstring |
O Salesforce retorna um valor mascarado em vez de um erro quando o usuário Run As não tem View Encrypted Data, e nada distingue dados mascarados de dados reais. Gravar silenciosamente linhas de asteriscos é pior do que recusar. | Decida deliberadamente se os dados devem sair do Salesforce; não há um modo com suporte de extraí-los por esta etapa. |
anyType |
O tipo real pode variar de linha para linha, e uma coluna de tabela tem exatamente um tipo. | Extraia um campo tipado ou um campo de fórmula que renderize o valor como texto. |
| Qualquer tipo que a etapa não reconheça | Recusado em vez de gravado como texto, o que alteraria silenciosamente o significado do valor. | Informe o suporte para que o tipo receba um mapeamento. |
Janelas de extração são executadas uma vez
Seção intitulada “Janelas de extração são executadas uma vez”Tag da janela dá nome à janela de dados que uma execução está carregando, um período ou um rótulo de lote como 2026-09. Ela aceita variáveis do fluxo de trabalho: uma tag {period} resolve para o valor dessa variável a cada execução da etapa.
Uma janela de extração é executada uma vez. Reexecutar uma janela que já foi concluída não volta ao Salesforce: a etapa informa claramente que não leu de novo e diz que a contagem de linhas exibida pertence à execução anterior. Isso é uma não-operação ruidosa, não silenciosa, e é o comportamento que impede uma reexecução de paginar uma segunda cópia de um conjunto de resultados que já foi gravado.
Há três modos de usar a etapa:
- Deixe a tag em branco e trate a etapa como uma carga única. A primeira execução lê; uma segunda execução dessa mesma etapa reproduz e informa que não leu de novo. Use isso para construir e validar a extração e para uma tabela que você carrega uma única vez.
- Digite uma tag e altere-a quando carregar a próxima janela:
2026-09, depois2026-10. Editar a tag inicia uma nova janela, então uma carga mensal que alguém avança manualmente funciona exatamente como parece. - Monte a tag a partir de uma variável do fluxo de trabalho para uma extração recorrente sem supervisão, por exemplo
{period}, definida por uma etapa anterior do fluxo de trabalho com o período que está sendo carregado. Cada execução agendada dá nome à própria janela, e uma reexecução dentro do mesmo período retoma ou reproduz essa janela em vez de iniciar outra.
Um chamador da API REST ou do MCP passa extract_tag diretamente e fornece por conta própria um valor distinto por janela.
Uma execução que foi interrompida retoma a mesma janela, então mantenha a tag constante enquanto essa janela ainda puder precisar terminar. Alterar a tag inicia uma nova janela e uma nova consulta no Salesforce. Altere a tag sempre que alterar o filtro ou os campos: editar a configuração sob uma tag que já foi executada é recusado como conflito.
Filtrar no Salesforce
Seção intitulada “Filtrar no Salesforce”Restrinja a extração no Salesforce em vez de trazer o objeto inteiro e filtrar depois. Cada termo de filtro é um campo, um operador e um valor; os termos se combinam com AND. Um valor pode usar uma variável do fluxo de trabalho, como {region}.
| Operador | Observações |
|---|---|
=, !=, <, <=, >, >= |
Comparados com o valor como digitado. |
LIKE |
Use % como curinga, por exemplo Acme%. |
IN, NOT IN |
Informe uma lista de valores separados por vírgula. |
Tanto o campo quanto o operador são verificados em relação aos campos que você selecionou antes de a consulta ser montada, e não há cláusula WHERE de texto livre para escrever, portanto um filtro não consegue ir além da extração. Filtre por um campo que você também marcou; um filtro que nomeia um campo que a extração não seleciona é recusado.
A etapa não oferece limite de linhas nem ordenação. A Bulk API 2.0 desativa o próprio fracionamento interno quando uma consulta contém qualquer um dos dois, o que torna uma extração grande mais lenta e mais propensa a esgotar o tempo. Critérios de filtro seletivos são o remédio do próprio Salesforce para uma consulta grande ou lenta demais.
Adequação a volume e rotatividade
Seção intitulada “Adequação a volume e rotatividade”Este formato, ler o objeto por inteiro em um agendamento, é adequado a objetos de volume moderado e rotatividade moderada: Accounts, Opportunities, Leads, Campaigns e objetos personalizados de tamanho semelhante.
É a ferramenta errada para objetos de alto volume e alta rotatividade, como Task, EmailMessage ou um objeto personalizado grande com milhões de linhas mudando diariamente. Uma extração completa noturna desses gasta tempo de relógio e capacidade de 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, como um intervalo de datas, um tipo de registro ou um proprietário, a transforma de volta em uma extração de volume moderado.
Quando uma execução não termina
Seção intitulada “Quando uma execução não termina”| O que você vê | O que aconteceu | O que fazer |
|---|---|---|
| Um erro informando que o job ainda está em execução após 15 minutos | A etapa espera em primeiro plano o Salesforce concluir a consulta, e essa espera é limitada. Nada avança o job em segundo plano. A etapa falha, para que as etapas seguintes não sejam executadas sobre uma tabela que esta extração não gravou. | Retome o fluxo de trabalho ou execute a etapa novamente. Ela retoma a espera no mesmo job do Salesforce e nunca envia um segundo. Se continuar excedendo 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 lida de novo | A janela foi executada antes. A contagem de linhas exibida é a da execução anterior. | Execute a extração com uma Tag da janela distinta ou avance a variável a partir da qual a tag é montada; consulte Janelas de extração são executadas uma vez. |
| Um erro que nomeia um job com falha ou abortado | Um job de consulta em massa com falha não produz resultados parciais e não pode ser retomado. A janela está agora esgotada. | Execute novamente com uma Tag da janela distinta. Reexecutar a mesma janela reproduz a falha e não envia nada, e editar a configuração da etapa sob a mesma tag é recusado como conflito. |
| Uma recusa que nomeia o limite de solicitações do Salesforce | A cota contínua de solicitações de API de 24 horas da organização foi esgotada. O Salesforce não documenta nenhum retry-after para ela. | Aguarde a janela liberar e depois execute novamente; a extração ainda pode ser retomada, nada se perdeu. |
| Uma recusa que nomeia um campo e seu tipo no Salesforce | Esse tipo de campo não pode ser gravado, ou o usuário Run As não pode ler o campo. | Consulte Campos que a etapa recusa e a segurança em nível de campo do usuário Run As. |
O Salesforce mantém os resultados de um job de consulta concluído recuperáveis por 7 dias, o que torna uma extração interrompida retomável, e é o que limita por quanto tempo uma retomada pode esperar antes que os resultados desapareçam. Os jobs ficam visíveis no Salesforce em Setup > Environments > Jobs > Bulk Data Load Jobs.
Relacionados
Seção intitulada “Relacionados”- Etapas do Salesforce
- Conectar ao Salesforce: a configuração do lado da organização, do início ao fim
- Conector REST do Salesforce: referência dos campos da conexão
- Executar uma etapa em um fluxo de trabalho