Ir al contenido

Lee un objeto de Salesforce, estándar o personalizado, en una tabla de proyecto mediante Bulk API 2.0 de Salesforce. Elija la conexión de Salesforce, el objeto y los campos; el paso crea la consulta, pagina todo el conjunto de resultados y guarda cada columna con el tipo que Salesforce declara para ella. No hay ninguna consulta que escribir.

Salesforce se alcanza directamente desde la nube mediante su API REST, por lo que este paso no necesita ningún agente PlaidLink.

Campo Obligatorio Notas
Conexión de Salesforce Sí La conexión de Salesforce a través de la cual leer. Las conexiones se administran en Tools > Connections.
Entorno No Cuál de los entornos de la conexión se lee: dirija un entorno de pruebas a la organización de pruebas y uno de producción a producción. Entorno del proyecto (el valor predeterminado) usa el entorno de la conexión del proyecto. Entorno fijo usa siempre el que usted elija. Consulte Fijar un paso a un entorno.
Objeto Sí El nombre de API del objeto: Account, Opportunity, Invoice__c. El selector enumera los objetos que el usuario Run As de la conexión puede consultar y también acepta un nombre escrito, de modo que un paso guardado sigue funcionando mientras la detección no esté disponible.
Tabla de destino Sí La tabla de proyecto en la que se guardan las filas.
Incluir registros eliminados y archivados No Lee también los registros de la Papelera de reciclaje y las actividades archivadas, como hace un queryAll de Salesforce.
Campos Sí Marque los campos que se van a extraer. Se requiere al menos uno: Bulk API 2.0 rechaza una selección de todo el objeto, por lo que la lista de columnas siempre se enumera de forma explícita.
Filtro No Acota la extracción en Salesforce. Consulte Filtrar en Salesforce.
Etiqueta de ventana No Nombra la ventana de extracción. Consulte Las ventanas de extracción se ejecutan una vez.

Id siempre se incluye, lo marque o no: es la clave sobre la que se combina cada nueva ejecución. Un campo de moneda también trae su CurrencyIsoCode cuando el objeto lo tiene.

Vista previa en la pestaña Origen muestra hasta 100 filas de lo que leería el paso, sin ejecutarlo. Las variables del filtro se rellenan de la manera en que las rellena una ejecución, pero no se admiten formatos de variable como {x:>9}. La vista previa no está disponible en un proyecto bloqueado. Si el filtro usa algo que la vista previa no puede comprobar como de solo lectura, le indica que ejecute el paso.

Cada ejecución lee el objeto completo, sujeto a su filtro, y combina cada página en la tabla de destino por Id. Una fila que ya está en la tabla se reemplaza en el sitio, de modo que una ejecución interrumpida que se reanuda no vuelve a guardar nada dos veces.

Las columnas guardadas usan los tipos que Salesforce declara en los metadatos de sus propios campos, nunca un tipo deducido a partir de la primera página de datos. La columna Se guarda como del selector de campos es ese tipo declarado, de modo que la forma que aprueba en el formulario es la forma que obtiene la tabla.

Tipo de campo de Salesforce Se guarda como
id, reference, string, textarea, phone, url, email, picklist, multipicklist, combobox texto
boolean booleano
date fecha
datetime marca de tiempo
time hora
int entero, o un entero de 64 bits cuando el campo declara 10 o más dígitos
double, currency, percent numérico: un decimal amplio, de 38 dígitos con 10 posiciones decimales

De esa tabla se derivan tres convenciones que conviene conocer antes de crear algo sobre la salida:

  • La moneda se guarda como un número, no como un tipo de moneda. Las organizaciones reales declaran campos de moneda con escalas de 0, 2, 3 y 4, así que todos los tipos numéricos se guardan en un decimal lo bastante amplio para todos ellos. La columna no tiene símbolo de moneda ni restricción de posiciones decimales por campo. Cuando el objeto incluye CurrencyIsoCode, esa columna acompaña al campo de moneda para que el importe conserve su moneda; una organización con una sola moneda no tiene ese campo en el objeto, y no se inventa ninguno.
  • Un porcentaje es el número entero que informa Salesforce. 20 significa 20 por ciento, no 0.2. No se reescala nada al importar.
  • Un valor vacío se guarda como NULL. Los resultados de Bulk no pueden distinguir un nulo verdadero de una cadena vacía explícita, así que ambos se guardan como NULL, en todas las columnas, incluido el texto. Una columna que deba conservar la semántica de cadena vacía necesita un campo de fórmula en el lado de Salesforce.

Algunos tipos de campo de Salesforce no se pueden guardar fielmente, por lo que el selector de campos los marca como inutilizables y nombra el motivo en lugar de dejarle guardar un paso que falla en tiempo de ejecución. Cada rechazo nombra el campo y su tipo de Salesforce.

Tipo de campo de Salesforce Por qué Qué hacer en su lugar
address, location (campos compuestos) Un campo compuesto no tiene un valor que se pueda leer directamente en una consulta Bulk. Marque sus campos componentes: BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, y la latitud y la longitud de la geolocalización. El selector nombra los componentes del campo que tiene delante.
base64 El contenido de archivos y blobs nunca se devuelve en línea; necesita una descarga binaria independiente que este paso no realiza. Lea los demás campos del registro y gestione los adjuntos por separado.
encryptedstring Salesforce devuelve un valor enmascarado en lugar de un error cuando el usuario Run As no tiene View Encrypted Data, y nada distingue los datos enmascarados de los reales. Guardar en silencio filas de asteriscos es peor que rechazarlo. Decida deliberadamente si los datos deben salir de Salesforce; no hay una forma admitida de extraerlos con este paso.
anyType El tipo real puede variar de una fila a otra, y una columna de tabla tiene exactamente un tipo. Extraiga un campo con tipo, o un campo de fórmula que represente el valor como texto.
Cualquier tipo que el paso no reconozca Se rechaza en lugar de guardarse como texto, lo cual cambiaría discretamente el significado del valor. Plantéelo al soporte para que el tipo reciba una asignación.

Las ventanas de extracción se ejecutan una vez

Sección titulada «Las ventanas de extracción se ejecutan una vez»

Etiqueta de ventana nombra la ventana de datos que carga una ejecución: un período o una etiqueta de lote como 2026-09. Admite variables del flujo de trabajo: una etiqueta {period} se resuelve con el valor de esa variable cada vez que se ejecuta el paso.

Una ventana de extracción se ejecuta una vez. Volver a ejecutar una ventana que ya se completó no vuelve a Salesforce: el paso informa claramente de que no volvió a leer e indica que el recuento de filas que muestra pertenece a la ejecución anterior. Es una operación nula ruidosa, no silenciosa, y es el comportamiento que evita que una nueva ejecución pagine una segunda copia de un conjunto de resultados que ya guardó.

Hay tres maneras de usar el paso:

  • Deje la etiqueta en blanco y trate el paso como una carga única. La primera ejecución lee; una segunda ejecución del mismo paso reproduce el resultado e informa de que no volvió a leer. Úselo para crear y validar la extracción, y para una tabla que carga una sola vez.
  • Escriba una etiqueta y cámbiela cuando cargue la ventana siguiente: 2026-09 y luego 2026-10. Editar la etiqueta inicia una ventana nueva, así que una carga mensual que alguien avanza a mano funciona exactamente como se lee.
  • Cree la etiqueta a partir de una variable del flujo de trabajo para una extracción periódica desatendida; por ejemplo {period}, establecida por un paso anterior del flujo de trabajo con el período que se está cargando. Cada ejecución programada nombra su propia ventana, y una nueva ejecución dentro del mismo período reanuda o reproduce esa ventana en lugar de iniciar otra.

Un llamador de la API REST o de MCP pasa extract_tag directamente y proporciona él mismo un valor distinto para cada ventana.

Una ejecución interrumpida reanuda la misma ventana, así que mantenga constante la etiqueta mientras esa ventana pueda necesitar terminar. Cambiar la etiqueta inicia una ventana nueva y una consulta nueva en Salesforce. Cambie la etiqueta siempre que cambie el filtro o los campos: editar la configuración bajo una etiqueta que ya se ejecutó se rechaza como un conflicto.

Acote la extracción en Salesforce en lugar de traer todo el objeto y filtrar después. Cada término de filtro es un campo, un operador y un valor; los términos se combinan con AND. Un valor puede usar una variable del flujo de trabajo, como {region}.

Operador Notas
=, !=, <, <=, >, >= Se comparan con el valor tal como se escribió.
LIKE Use % como comodín, por ejemplo Acme%.
IN, NOT IN Indique una lista de valores separados por comas.

Tanto el campo como el operador se comprueban con los campos que seleccionó antes de crear la consulta, y no hay ninguna cláusula WHERE de texto libre que escribir, de modo que un filtro no puede ir más allá de la extracción. Filtre por un campo que también haya marcado; se rechaza un filtro que nombre un campo que la extracción no selecciona.

El paso no ofrece límite de filas ni ordenación. Bulk API 2.0 desactiva su propia división interna en bloques cuando una consulta incluye cualquiera de los dos, lo que hace que una extracción grande sea más lenta y más propensa a agotar el tiempo de espera. Los criterios de filtro selectivos son el remedio propio de Salesforce para una consulta demasiado grande o demasiado lenta.

Esta forma (leer el objeto completo, según una programación) es adecuada para objetos de volumen y rotación moderados: Accounts, Opportunities, Leads, Campaigns y objetos personalizados de tamaño similar.

Es la herramienta equivocada para objetos de alto volumen y alta rotación como Task, EmailMessage o un objeto personalizado grande con millones de filas que cambian a diario. Una extracción completa nocturna de esos gasta tiempo real y capacidad de API que una sincronización incremental no gastaría. Cuando el objeto es grande pero solo una parte es interesante, un filtro que acote la extracción (un intervalo de fechas, un tipo de registro, un propietario) la convierte de nuevo en una extracción de volumen moderado.

Qué ve Qué ocurrió Qué hacer
Un error de que el trabajo sigue en ejecución después de 15 minutos El paso espera en primer plano a que Salesforce termine la consulta, y esa espera tiene un límite. Nada hace avanzar el trabajo en segundo plano. El paso falla, de modo que los pasos posteriores no se ejecutan sobre una tabla que esta extracción no ha escrito. Reanude el flujo de trabajo o vuelva a ejecutar el paso. Reanuda la espera en el mismo trabajo de Salesforce y nunca envía un segundo trabajo. Si sigue superando el límite, acote la extracción con criterios de filtro.
Una advertencia de que la ventana ya se completó y no se volvió a leer La ventana se ejecutó antes. El recuento de filas mostrado es el de la ejecución anterior. Ejecute la extracción con una Etiqueta de ventana distinta, o avance la variable a partir de la cual se crea la etiqueta; consulte Las ventanas de extracción se ejecutan una vez.
Un error que nombra un trabajo fallido o abortado Un trabajo de consulta Bulk fallido no produce resultados parciales y no se puede reanudar. La ventana ya está agotada. Vuelva a ejecutar con una Etiqueta de ventana distinta. Volver a ejecutar la misma ventana reproduce el fallo y no envía nada, y editar la configuración del paso bajo la misma etiqueta se rechaza como un conflicto.
Un rechazo que nombra el límite de solicitudes de Salesforce Se agotó la cuota de solicitudes de API de 24 horas móviles de la organización. Salesforce no documenta ningún tiempo de reintento para ello. Espere a que la ventana se libere y vuelva a ejecutar: la extracción sigue siendo reanudable y no se perdió nada.
Un rechazo que nombra un campo y su tipo de Salesforce Ese tipo de campo no se puede guardar, o el usuario Run As no puede leer el campo. Consulte Campos que el paso rechaza y la seguridad a nivel de campo del usuario Run As.

Salesforce mantiene recuperables durante 7 días los resultados de un trabajo de consulta completado, lo que hace que una extracción interrumpida sea reanudable, y lo que limita cuánto tiempo puede esperar una reanudación antes de que los resultados desaparezcan. Los trabajos se ven en Salesforce en Setup > Environments > Jobs > Bulk Data Load Jobs.