Zum Inhalt springen

Liest ein Salesforce-Objekt — Standard- oder benutzerdefiniertes — über die Bulk API 2.0 von Salesforce in eine Projekttabelle. Wählen Sie die Salesforce-Verbindung, das Objekt und die Felder; der Schritt baut die Abfrage auf, ruft die gesamte Ergebnismenge seitenweise ab und legt jede Spalte als den Typ ab, den Salesforce dafür deklariert. Sie müssen keine Abfrage schreiben.

Salesforce wird direkt über die Cloud mit seiner REST-API erreicht, daher benötigt dieser Schritt keinen PlaidLink-Agent.

Feld Erforderlich Hinweise
Salesforce-Verbindung Ja Die Salesforce-Verbindung, über die gelesen wird. Verbindungen werden unter Tools > Connections verwaltet.
Umgebung Nein Welche der Umgebungen der Verbindung gelesen wird — richten Sie eine Sandbox-Umgebung auf die Sandbox-Organisation und eine Produktionsumgebung auf die Produktion. Projektumgebung (der Standard) verwendet die Verbindungsumgebung des Projekts. Feste Umgebung verwendet immer die Umgebung, die Sie auswählen. Siehe Einen Schritt auf eine Umgebung festlegen.
Objekt Ja Der API-Name des Objekts — Account, Opportunity, Invoice__c. Die Auswahl listet die Objekte auf, die der Run-As-Benutzer der Verbindung abfragen kann, und akzeptiert auch einen eingegebenen Namen, sodass ein gespeicherter Schritt weiterarbeitet, solange die Ermittlung nicht verfügbar ist.
Zieltabelle Ja Die Projekttabelle, in der die Zeilen abgelegt werden.
Gelöschte und archivierte Datensätze einbeziehen Nein Liest zusätzlich Datensätze im Papierkorb und archivierte Aktivitäten, so wie es ein Salesforce-queryAll tut.
Felder Ja Markieren Sie die zu extrahierenden Felder. Mindestens eines ist erforderlich: Die Bulk API 2.0 lehnt eine Auswahl des gesamten Objekts ab, daher wird die Spaltenliste immer einzeln aufgeführt.
Filter Nein Schränkt die Extraktion in Salesforce ein. Siehe Filtern in Salesforce.
Fenster-Tag Nein Benennt das Extraktionsfenster. Siehe Extraktionsfenster laufen nur einmal.

Id ist immer enthalten, ob Sie es markieren oder nicht — es ist der Schlüssel, über den jede erneute Ausführung zusammenführt. Ein Währungsfeld ruft außerdem sein CurrencyIsoCode ab, sofern das Objekt eines hat.

Vorschau auf der Registerkarte Quelle zeigt bis zu 100 Zeilen dessen, was der Schritt lesen würde, ohne ihn auszuführen. Variablen im Filter werden so eingesetzt, wie eine Ausführung sie einsetzt, Variablenformate wie {x:>9} werden jedoch nicht unterstützt. Die Vorschau ist in einem gesperrten Projekt nicht verfügbar. Wenn der Filter etwas verwendet, das die Vorschau nicht als schreibgeschützt prüfen kann, fordert sie Sie auf, den Schritt auszuführen.

Jede Ausführung liest das Objekt vollständig, vorbehaltlich Ihres Filters, und führt jede Seite über Id in die Zieltabelle zusammen. Eine Zeile, die bereits in der Tabelle steht, wird an Ort und Stelle ersetzt, sodass eine unterbrochene Ausführung, die fortgesetzt wird, nichts doppelt ablegt.

Die abgelegten Spalten verwenden die Typen, die Salesforce in seinen eigenen Feldmetadaten deklariert, nie einen anhand der ersten Datenseite erratenen Typ. Die Spalte Abgelegt als in der Feldauswahl ist dieser deklarierte Typ, sodass die Form, die Sie im Formular genehmigen, die Form ist, die die Tabelle erhält.

Salesforce-Feldtyp Abgelegt als
id, reference, string, textarea, phone, url, email, picklist, multipicklist, combobox Text
boolean Boolean
date Datum
datetime Zeitstempel
time Uhrzeit
int Ganzzahl oder eine 64-Bit-Ganzzahl, wenn das Feld 10 oder mehr Stellen deklariert
double, currency, percent numerisch — eine breite Dezimalzahl mit 38 Stellen und 10 Nachkommastellen

Drei Konventionen ergeben sich aus dieser Tabelle und sind es wert, bekannt zu sein, bevor Sie auf der Ausgabe aufbauen:

  • Währung wird als Zahl abgelegt, nicht als Währungstyp. Reale Organisationen deklarieren Währungsfelder mit den Skalen 0, 2, 3 und 4, daher wird jeder numerische Typ in einer Dezimalzahl abgelegt, die breit genug für alle ist. Die Spalte hat kein Währungssymbol und keine Einschränkung der Nachkommastellen pro Feld. Wo das Objekt CurrencyIsoCode führt, kommt diese Spalte neben dem Währungsfeld mit, damit der Betrag seine Währung behält; eine Organisation mit nur einer Währung hat kein solches Feld am Objekt, und es wird auch keines erfunden.
  • Ein Prozentwert ist die ganze Zahl, die Salesforce meldet. 20 bedeutet 20 Prozent, nicht 0.2. Beim Einlesen wird nichts umskaliert.
  • Ein leerer Wert wird als NULL abgelegt. Bulk-Ergebnisse können einen echten Nullwert nicht von einer expliziten leeren Zeichenfolge unterscheiden, daher werden beide als NULL abgelegt — in jeder Spalte, auch bei Text. Eine Spalte, die die Semantik einer leeren Zeichenfolge behalten muss, benötigt auf der Salesforce-Seite ein Formelfeld.

Manche Salesforce-Feldtypen lassen sich nicht korrekt ablegen, daher kennzeichnet die Feldauswahl sie als unbrauchbar und nennt den Grund, statt Sie einen Schritt speichern zu lassen, der zur Laufzeit fehlschlägt. Jede Ablehnung nennt das Feld und seinen Salesforce-Typ.

Salesforce-Feldtyp Grund Was zu tun ist
address, location (zusammengesetzte Felder) Ein zusammengesetztes Feld hat in einer Bulk-Abfrage keinen direkt lesbaren Wert. Markieren Sie seine Komponentenfelder — BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry sowie Breiten- und Längengrad der Geolokalisierung. Die Auswahl nennt die Komponenten für das Feld, das Sie vor sich haben.
base64 Datei- und Blob-Inhalte werden nie inline zurückgegeben; es ist ein separater binärer Download nötig, den dieser Schritt nicht ausführt. Lesen Sie die übrigen Felder des Datensatzes und behandeln Sie Anhänge separat.
encryptedstring Salesforce gibt einen maskierten Wert statt eines Fehlers zurück, wenn dem Run-As-Benutzer View Encrypted Data fehlt, und nichts unterscheidet maskierte Daten von echten. Stillschweigend Zeilen aus Sternchen abzulegen ist schlimmer als abzulehnen. Entscheiden Sie bewusst, ob die Daten Salesforce überhaupt verlassen sollen; es gibt keinen unterstützten Weg, sie über diesen Schritt zu extrahieren.
anyType Der tatsächliche Typ kann sich von Zeile zu Zeile unterscheiden, und eine Tabellenspalte hat genau einen Typ. Extrahieren Sie ein typisiertes Feld oder ein Formelfeld, das den Wert als Text darstellt.
Jeder Typ, den der Schritt nicht erkennt Wird abgelehnt, statt als Text abgelegt zu werden, was die Bedeutung des Werts unbemerkt verändern würde. Wenden Sie sich an den Support, damit der Typ eine Zuordnung erhält.

Das Fenster-Tag benennt das Datenfenster, das eine Ausführung lädt — eine Periode oder eine Batch-Bezeichnung wie 2026-09. Es akzeptiert Workflow-Variablen: Ein Tag {period} wird bei jeder Ausführung des Schritts zum Wert dieser Variablen aufgelöst.

Ein Extraktionsfenster läuft einmal. Das erneute Ausführen eines bereits abgeschlossenen Fensters geht nicht zurück zu Salesforce: Der Schritt meldet klar, dass er nicht erneut gelesen hat, und sagt, dass die angezeigte Zeilenanzahl zur früheren Ausführung gehört. Das ist ein auffälliges No-op, kein stilles, und es ist das Verhalten, das verhindert, dass eine erneute Ausführung eine zweite Kopie einer bereits abgelegten Ergebnismenge seitenweise abruft.

Es gibt drei Möglichkeiten, den Schritt zu verwenden:

  • Lassen Sie das Tag leer und behandeln Sie den Schritt als einmaliges Laden. Die erste Ausführung liest; eine zweite Ausführung desselben Schritts gibt das Ergebnis wieder und meldet, dass nicht erneut gelesen wurde. Verwenden Sie dies, um die Extraktion aufzubauen und zu validieren, und für eine Tabelle, die Sie einmal laden.
  • Geben Sie ein Tag ein und ändern Sie es, wenn Sie das nächste Fenster laden — 2026-09, dann 2026-10. Das Bearbeiten des Tags startet ein neues Fenster, sodass ein monatliches Laden, das jemand von Hand fortschreibt, genau so funktioniert, wie es sich liest.
  • Bauen Sie das Tag aus einer Workflow-Variablen auf, für einen unbeaufsichtigten wiederkehrenden Abruf — zum Beispiel {period}, von einem früheren Schritt im Workflow auf die zu ladende Periode gesetzt. Jede geplante Ausführung benennt ihr eigenes Fenster, und eine erneute Ausführung innerhalb derselben Periode setzt dieses Fenster fort oder gibt es wieder, statt ein weiteres zu starten.

Ein Aufrufer der REST-API oder des MCP übergibt extract_tag direkt und liefert pro Fenster selbst einen eindeutigen Wert.

Eine unterbrochene Ausführung setzt dasselbe Fenster fort, daher sollten Sie das Tag so lange konstant halten, wie dieses Fenster noch abgeschlossen werden muss. Das Ändern des Tags startet ein neues Fenster und eine neue Abfrage in Salesforce. Ändern Sie das Tag, wann immer Sie den Filter oder die Felder ändern: Das Bearbeiten der Konfiguration unter einem Tag, das bereits gelaufen ist, wird als Konflikt abgelehnt.

Schränken Sie die Extraktion in Salesforce ein, statt das gesamte Objekt abzurufen und danach zu filtern. Jeder Filterterm besteht aus einem Feld, einem Operator und einem Wert; Terme werden mit AND kombiniert. Ein Wert kann eine Workflow-Variable verwenden, etwa {region}.

Operator Hinweise
=, !=, <, <=, >, >= Wird mit dem Wert verglichen, wie er eingegeben wurde.
LIKE Verwenden Sie % als Platzhalter, zum Beispiel Acme%.
IN, NOT IN Geben Sie eine durch Kommas getrennte Liste von Werten an.

Sowohl das Feld als auch der Operator werden vor dem Aufbau der Abfrage gegen die ausgewählten Felder geprüft, und es gibt keine freie WHERE-Klausel zum Schreiben — ein Filter kann also nicht über die Extraktion hinausreichen. Filtern Sie nach einem Feld, das Sie auch markiert haben; ein Filter, der ein Feld nennt, das die Extraktion nicht auswählt, wird abgelehnt.

Der Schritt bietet weder ein Zeilenlimit noch eine Sortierung. Die Bulk API 2.0 schaltet ihr eigenes internes Chunking ab, wenn eine Abfrage eines von beiden enthält, was eine große Extraktion langsamer und anfälliger für Zeitüberschreitungen macht. Selektive Filterkriterien sind das Mittel von Salesforce selbst gegen eine Abfrage, die zu groß oder zu langsam ist.

Diese Form — das Objekt nach Zeitplan vollständig lesen — eignet sich für Objekte mit mittlerem Volumen und mittlerer Änderungshäufigkeit: Accounts, Opportunities, Leads, Campaigns und benutzerdefinierte Objekte ähnlicher Größe.

Für Objekte mit hohem Volumen und hoher Änderungshäufigkeit wie Task, EmailMessage oder ein großes benutzerdefiniertes Objekt mit Millionen täglich geänderter Zeilen ist es das falsche Werkzeug. Ein nächtlicher vollständiger Abruf davon verbraucht Laufzeit und API-Kapazität, die eine inkrementelle Synchronisierung nicht verbrauchen würde. Wo das Objekt groß ist, aber nur ein Teil davon interessant, macht ein Filter, der die Extraktion begrenzt — ein Datumsbereich, ein Datensatztyp, ein Besitzer —, daraus wieder einen Abruf mit mittlerem Volumen.

Was Sie sehen Was passiert ist Was zu tun ist
Ein Fehler, dass der Job nach 15 Minuten noch läuft Der Schritt wartet im Vordergrund darauf, dass Salesforce die Abfrage beendet, und dieses Warten ist begrenzt. Nichts treibt den Job im Hintergrund voran. Der Schritt schlägt fehl, sodass die nachfolgenden Schritte nicht mit einer Tabelle ausgeführt werden, die diese Extraktion nicht geschrieben hat. Wählen Sie für den Workflow Fortsetzen oder führen Sie den Schritt erneut aus. Er setzt das Warten auf demselben Salesforce-Job fort und sendet nie einen zweiten. Wenn die Grenze weiterhin überschritten wird, schränken Sie die Extraktion mit Filterkriterien ein.
Eine Warnung, dass das Fenster bereits abgeschlossen war und nicht erneut gelesen wurde Das Fenster ist schon einmal gelaufen. Die angezeigte Zeilenanzahl stammt von der früheren Ausführung. Führen Sie die Extraktion mit einem anderen Fenster-Tag aus oder schreiben Sie die Variable fort, aus der das Tag aufgebaut ist — siehe Extraktionsfenster laufen nur einmal.
Ein Fehler, der einen fehlgeschlagenen oder abgebrochenen Job nennt Ein fehlgeschlagener Bulk-Abfragejob liefert keine Teilergebnisse und kann nicht fortgesetzt werden. Das Fenster ist jetzt verbraucht. Führen Sie den Schritt mit einem anderen Fenster-Tag erneut aus. Das erneute Ausführen desselben Fensters gibt den Fehler wieder und sendet nichts, und das Bearbeiten der Konfiguration des Schritts unter demselben Tag wird als Konflikt abgelehnt.
Eine Ablehnung, die das Anfragelimit von Salesforce nennt Das rollierende 24-Stunden-Kontingent für API-Anfragen der Organisation ist erschöpft. Salesforce dokumentiert dafür kein Retry-After. Warten Sie, bis das Fenster abgelaufen ist, und führen Sie den Schritt dann erneut aus — die Extraktion lässt sich weiterhin fortsetzen, nichts ging verloren.
Eine Ablehnung, die ein Feld und seinen Salesforce-Typ nennt Dieser Feldtyp lässt sich nicht ablegen, oder der Run-As-Benutzer kann das Feld nicht lesen. Siehe Felder, die der Schritt ablehnt und die Sicherheit auf Feldebene des Run-As-Benutzers.

Salesforce hält die Ergebnisse eines abgeschlossenen Abfragejobs 7 Tage lang abrufbar, was eine unterbrochene Extraktion fortsetzbar macht — und begrenzt, wie lange eine Fortsetzung warten kann, bevor die Ergebnisse weg sind. Jobs sind in Salesforce unter Setup > Environments > Jobs > Bulk Data Load Jobs sichtbar.