Salesforce: Objekt abfragen
Beschreibung
Abschnitt betitelt „Beschreibung“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.
Konfiguration
Abschnitt betitelt „Konfiguration“| 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
Abschnitt betitelt „Vorschau“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.
Wie die Zeilen abgelegt werden
Abschnitt betitelt „Wie die Zeilen abgelegt werden“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.
Was als was abgelegt wird
Abschnitt betitelt „Was als was abgelegt wird“| 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
CurrencyIsoCodefü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.
20bedeutet 20 Prozent, nicht0.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
NULLabgelegt — in jeder Spalte, auch bei Text. Eine Spalte, die die Semantik einer leeren Zeichenfolge behalten muss, benötigt auf der Salesforce-Seite ein Formelfeld.
Felder, die der Schritt ablehnt
Abschnitt betitelt „Felder, die der Schritt ablehnt“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. |
Extraktionsfenster laufen nur einmal
Abschnitt betitelt „Extraktionsfenster laufen nur einmal“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, dann2026-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.
Filtern in Salesforce
Abschnitt betitelt „Filtern in Salesforce“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.
Eignung nach Volumen und Änderungshäufigkeit
Abschnitt betitelt „Eignung nach Volumen und Änderungshäufigkeit“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.
Wenn eine Ausführung nicht abgeschlossen wird
Abschnitt betitelt „Wenn eine Ausführung nicht abgeschlossen wird“| 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.
Verwandte Themen
Abschnitt betitelt „Verwandte Themen“- Salesforce-Schritte
- Mit Salesforce verbinden — die Einrichtung auf Seiten der Organisation, von Anfang bis Ende
- Salesforce-REST-Konnektor — Referenz der Verbindungsfelder
- Einen einzelnen Schritt in einem Workflow ausführen