Przejdź do głównej zawartości

Odczytuje jeden obiekt Salesforce — standardowy lub niestandardowy — do tabeli projektu przez Bulk API 2.0 Salesforce. Wybierz połączenie Salesforce, obiekt i pola; krok buduje zapytanie, stronicuje cały zbiór wyników i ładuje każdą kolumnę jako typ zadeklarowany przez Salesforce. Nie trzeba pisać żadnego zapytania.

Do Salesforce łączymy się bezpośrednio z chmury przez jego REST API, więc ten krok nie wymaga agenta PlaidLink.

Pole Wymagane Uwagi
Połączenie Salesforce Tak Połączenie Salesforce, przez które odbywa się odczyt. Połączeniami zarządza się w Tools > Connections.
Środowisko Nie Które ze środowisk połączenia czytać — skieruj środowisko sandbox na organizację sandbox, a produkcyjne na produkcję. Środowisko projektu (domyślne) używa środowiska połączenia projektu. Stałe środowisko zawsze używa wybranego przez Ciebie środowiska. Zobacz Przypinanie kroku do jednego środowiska.
Obiekt Tak Nazwa API obiektu — Account, Opportunity, Invoice__c. Selektor wymienia obiekty, które może odpytywać użytkownik Run As połączenia, i akceptuje też wpisaną nazwę, więc zapisany krok nadal działa, gdy wykrywanie jest niedostępne.
Tabela docelowa Tak Tabela projektu, do której trafiają wiersze.
Uwzględnij usunięte i zarchiwizowane rekordy Nie Odczytuje też rekordy z Kosza i zarchiwizowane aktywności, tak jak robi to queryAll w Salesforce.
Pola Tak Zaznacz pola do wyodrębnienia. Wymagane jest co najmniej jedno: Bulk API 2.0 odrzuca wybór całego obiektu, więc lista kolumn jest zawsze wyliczana.
Filtr Nie Zawęża ekstrakcję w Salesforce. Zobacz Filtrowanie w Salesforce.
Tag okna Nie Nazywa okno ekstrakcji. Zobacz Okna ekstrakcji uruchamiane raz.

Id jest zawsze uwzględniane, niezależnie od tego, czy je zaznaczysz — to klucz, po którym scalane jest każde ponowne uruchomienie. Pole waluty pobiera również swoje CurrencyIsoCode, jeśli obiekt je ma.

Podgląd na karcie Źródło pokazuje do 100 wierszy tego, co krok odczytałby, bez jego uruchamiania. Zmienne w filtrze są podstawiane tak, jak robi to uruchomienie, ale formaty zmiennych, takie jak {x:>9}, nie są obsługiwane. Podgląd nie jest dostępny w zablokowanym projekcie. Jeśli filtr używa czegoś, czego Podgląd nie może sprawdzić jako tylko do odczytu, informuje, że należy uruchomić krok.

Każde uruchomienie odczytuje obiekt w całości, z uwzględnieniem filtra, i scala każdą stronę z tabelą docelową po Id. Wiersz już obecny w tabeli jest zastępowany w miejscu, więc przerwane uruchomienie, które jest wznawiane, niczego nie ładuje dwukrotnie.

Załadowane kolumny używają typów zadeklarowanych przez Salesforce we własnych metadanych pól, nigdy typu odgadniętego z pierwszej strony danych. Kolumna Trafia jako w selektorze pól to właśnie ten zadeklarowany typ, więc kształt zatwierdzony w formularzu jest kształtem, jaki otrzymuje tabela.

Typ pola Salesforce Trafia jako
id, reference, string, textarea, phone, url, email, picklist, multipicklist, combobox tekst
boolean wartość logiczna
date data
datetime znacznik czasu
time czas
int liczba całkowita lub 64-bitowa liczba całkowita, gdy pole deklaruje 10 lub więcej cyfr
double, currency, percent liczba — szeroka liczba dziesiętna, 38 cyfr z 10 miejscami po przecinku

Z tej tabeli wynikają trzy konwencje, które warto znać, zanim zaczniesz budować na wynikach:

  • Waluta trafia jako liczba, a nie jako typ walutowy. Prawdziwe organizacje deklarują pola walutowe ze skalą 0, 2, 3 i 4, więc każdy typ liczbowy trafia do jednej liczby dziesiętnej wystarczająco szerokiej dla wszystkich. Kolumna nie ma symbolu waluty ani ograniczenia liczby miejsc dziesiętnych dla pola. Tam, gdzie obiekt ma CurrencyIsoCode, ta kolumna jest dołączana obok pola waluty, aby kwota zachowała swoją walutę; organizacja jednowalutowa nie ma takiego pola w obiekcie i żadne nie jest wymyślane.
  • Procent to liczba całkowita, którą zgłasza Salesforce. 20 oznacza 20 procent, a nie 0.2. Nic nie jest przeskalowywane w trakcie wczytywania.
  • Pusta wartość trafia jako NULL. Wyniki Bulk nie odróżniają prawdziwego null od jawnego pustego ciągu, więc oba trafiają jako NULL — w każdej kolumnie, także tekstowej. Kolumna, która musi zachować semantykę pustego ciągu, wymaga pola formuły po stronie Salesforce.

Niektórych typów pól Salesforce nie można uczciwie załadować, więc selektor pól oznacza je jako nieużyteczne i podaje powód, zamiast pozwolić na zapisanie kroku, który zawiedzie w czasie uruchomienia. Każde odrzucenie podaje nazwę pola i jego typ Salesforce.

Typ pola Salesforce Dlaczego Co zrobić zamiast tego
address, location (pola złożone) Pole złożone nie ma bezpośrednio odczytywalnej wartości w zapytaniu Bulk. Zaznacz jego pola składowe — BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry oraz szerokość i długość geograficzną geolokalizacji. Selektor podaje składowe dla pola, które masz przed sobą.
base64 Zawartość plików i blobów nigdy nie jest zwracana w treści; wymaga osobnego pobrania binarnego, którego ten krok nie wykonuje. Odczytaj pozostałe pola rekordu, a załączniki obsłuż osobno.
encryptedstring Salesforce zwraca zamaskowaną wartość zamiast błędu, gdy użytkownik Run As nie ma View Encrypted Data, i nic nie odróżnia zamaskowanych danych od prawdziwych. Ciche ładowanie wierszy z gwiazdkami jest gorsze niż odmowa. Zdecyduj świadomie, czy dane w ogóle powinny opuścić Salesforce; nie ma obsługiwanego sposobu ich wyodrębnienia tym krokiem.
anyType Prawdziwy typ może różnić się w każdym wierszu, a kolumna tabeli ma dokładnie jeden typ. Wyodrębnij pole o określonym typie lub pole formuły, które renderuje wartość jako tekst.
Dowolny typ, którego krok nie rozpoznaje Odrzucany zamiast ładowany jako tekst, co po cichu zmieniłoby znaczenie wartości. Zgłoś to do pomocy technicznej, aby typ otrzymał mapowanie.

Tag okna nazywa okno danych, które ładuje uruchomienie — okres lub etykietę partii, taką jak 2026-09. Przyjmuje zmienne przepływu pracy: tag {period} jest rozwiązywany do wartości tej zmiennej za każdym razem, gdy krok się uruchamia.

Okno ekstrakcji jest uruchamiane raz. Ponowne uruchomienie okna, które już się zakończyło, nie wraca do Salesforce: krok informuje wprost, że nie czytał ponownie, i podaje, że pokazana liczba wierszy należy do wcześniejszego uruchomienia. To głośne, a nie ciche zachowanie bez działania, i właśnie ono zapobiega temu, by ponowne uruchomienie stronicowało drugą kopię zbioru wyników, który już został załadowany.

Są trzy sposoby użycia kroku:

  • Pozostaw tag pusty i traktuj krok jako jednorazowe ładowanie. Pierwsze uruchomienie czyta; drugie uruchomienie tego samego kroku odtwarza i zgłasza, że nie czytało ponownie. Użyj tego do zbudowania i sprawdzenia ekstrakcji oraz dla tabeli ładowanej raz.
  • Wpisz tag i zmień go, gdy ładujesz następne okno — 2026-09, potem 2026-10. Edycja tagu rozpoczyna nowe okno, więc miesięczne ładowanie przesuwane ręcznie działa dokładnie tak, jak to wygląda.
  • Zbuduj tag ze zmiennej przepływu pracy dla bezobsługowego cyklicznego pobierania — na przykład {period}, ustawionej przez wcześniejszy krok przepływu pracy na ładowany okres. Każde zaplanowane uruchomienie nazywa własne okno, a ponowne uruchomienie w tym samym okresie wznawia lub odtwarza to okno zamiast rozpoczynać kolejne.

Wywołujący REST API lub MCP przekazuje extract_tag bezpośrednio i sam dostarcza odrębną wartość dla każdego okna.

Przerwane uruchomienie wznawia to samo okno, więc utrzymuj tag stały tak długo, jak okno może jeszcze potrzebować zakończenia. Zmiana tagu rozpoczyna nowe okno i nowe zapytanie w Salesforce. Zmieniaj tag za każdym razem, gdy zmieniasz filtr lub pola: edycja konfiguracji pod tagiem, który już został uruchomiony, jest odrzucana jako konflikt.

Zawężaj ekstrakcję w Salesforce, zamiast pobierać cały obiekt i filtrować potem. Każdy człon filtra to pole, operator i wartość; człony łączą się przez AND. Wartość może używać zmiennej przepływu pracy, takiej jak {region}.

Operator Uwagi
=, !=, <, <=, >, >= Porównywane z wartością w postaci wpisanej.
LIKE Użyj % jako symbolu wieloznacznego, na przykład Acme%.
IN, NOT IN Podaj listę wartości rozdzielonych przecinkami.

Zarówno pole, jak i operator są sprawdzane względem wybranych pól przed zbudowaniem zapytania i nie ma swobodnej klauzuli WHERE do napisania — więc filtr nie może wyjść poza ekstrakcję. Filtruj po polu, które również zaznaczono; filtr wskazujący pole, którego ekstrakcja nie wybiera, jest odrzucany.

Krok nie oferuje limitu wierszy ani sortowania. Bulk API 2.0 wyłącza własne wewnętrzne dzielenie na części, gdy zapytanie zawiera którekolwiek z nich, co sprawia, że duża ekstrakcja jest wolniejsza i bardziej narażona na przekroczenie limitu czasu. Selektywne kryteria filtra to własne lekarstwo Salesforce na zapytanie, które jest zbyt duże lub zbyt wolne.

Ten kształt — odczyt obiektu w całości, według harmonogramu — pasuje do obiektów o umiarkowanym wolumenie i umiarkowanej zmienności: Accounts, Opportunities, Leads, Campaigns oraz obiektów niestandardowych o podobnym rozmiarze.

Jest niewłaściwym narzędziem dla obiektów o dużym wolumenie i dużej zmienności, takich jak Task, EmailMessage lub duży obiekt niestandardowy z milionami wierszy zmieniających się codziennie. Nocne pełne pobranie takich obiektów zużywa czas zegarowy i przepustowość API, których nie zużyłaby synchronizacja przyrostowa. Gdy obiekt jest duży, ale interesuje Cię tylko jego część, filtr ograniczający ekstrakcję — zakres dat, typ rekordu, właściciel — zamienia to z powrotem w pobieranie o umiarkowanym wolumenie.

Co widać Co się stało Co zrobić
Błąd informujący, że zadanie nadal działa po 15 minutach Krok czeka na pierwszym planie, aż Salesforce zakończy zapytanie, a to oczekiwanie jest ograniczone. Nic nie posuwa zadania do przodu w tle. Krok kończy się niepowodzeniem, aby kolejne kroki nie uruchamiały się na tabeli, której ta ekstrakcja nie zapisała. Wznów przepływ pracy lub uruchom krok ponownie. Krok wznawia oczekiwanie na to samo zadanie Salesforce i nigdy nie wysyła drugiego. Jeśli stale przekracza limit, zawęź ekstrakcję kryteriami filtra.
Ostrzeżenie, że okno już się zakończyło i nie było odczytane ponownie Okno zostało uruchomione wcześniej. Pokazana liczba wierszy pochodzi z wcześniejszego uruchomienia. Uruchom ekstrakcję z innym Tag okna albo przesuń zmienną, z której zbudowano tag — zobacz Okna ekstrakcji uruchamiane raz.
Błąd wskazujący nieudane lub przerwane zadanie Nieudane zadanie zapytania Bulk nie daje wyników częściowych i nie może zostać wznowione. Okno jest teraz wyczerpane. Uruchom ponownie z innym Tag okna. Ponowne uruchomienie tego samego okna odtwarza niepowodzenie i niczego nie wysyła, a edycja konfiguracji kroku pod tym samym tagiem jest odrzucana jako konflikt.
Odmowa wskazująca limit żądań Salesforce Wyczerpano kroczący 24-godzinny limit żądań API organizacji. Salesforce nie dokumentuje dla niego czasu ponowienia. Poczekaj, aż okno się zwolni, a następnie uruchom ponownie — ekstrakcję nadal można wznowić, nic nie zostało utracone.
Odmowa wskazująca jedno pole i jego typ Salesforce Tego typu pola nie można załadować albo użytkownik Run As nie może odczytać pola. Zobacz Pola, które krok odrzuca oraz zabezpieczenia na poziomie pól użytkownika Run As.

Salesforce przechowuje wyniki ukończonego zadania zapytania jako możliwe do pobrania przez 7 dni, co umożliwia wznowienie przerwanej ekstrakcji — i ogranicza, jak długo wznowienie może czekać, zanim wyniki znikną. Zadania są widoczne w Salesforce w Setup > Environments > Jobs > Bulk Data Load Jobs.