Salesforce: Consultar objeto
Descrição
Seção intitulada “Descrição”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.
Configuração
Seção intitulada “Configuração”| 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
Seção intitulada “Pré-visualização”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.
Como as linhas são carregadas
Seção intitulada “Como as linhas são carregadas”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.
O que resulta em quê
Seção intitulada “O que resulta em quê”| 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.
20significa 20 por cento, não0.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.
Campos que o passo recusa
Seção intitulada “Campos que o passo recusa”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-09e depois2026-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.
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 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.
Adequação ao volume e à variação
Seção intitulada “Adequação ao volume e à variação”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.
Quando uma execução não termina
Seção intitulada “Quando uma execução não termina”| 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.
Relacionado
Seção intitulada “Relacionado”- Passos Salesforce
- Ligar ao Salesforce — a configuração do lado da organização, do princípio ao fim
- Conector REST do Salesforce — referência dos campos da ligação
- Executar um passo num fluxo de trabalho