Erfassen Sie Ihre Fortschritte
Trailhead-Startseite
Trailhead-Startseite

Verwenden der Bulk-API

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:
  • Beschreiben, wie sich eine asynchrone Anforderung von einer synchronen Anforderung unterscheidet
  • Erstellen eines Bulk-Auftrags mit dem REST Explorer in Workbench
  • Importieren von Daten in Ihre Salesforce-Organisation durch Hinzufügen von Daten zu einem Auftrag
  • Überwachen eines laufenden Auftrags
  • Abrufen der Ergebnisse für einen Auftrag

Bulk-API und asynchrone Anforderungen

Die Bulk-API basiert auf REST-Prinzipien und ist für den Umgang mit großen Datensets optimiert. Sie ermöglicht das asynchrone Einfügen, Aktualisieren, gleichzeitige Aktualisieren/Einfügen oder Löschen vieler Datensätze. Asynchron heißt hier, Sie können eine Anforderung senden und sich später die Ergebnisse ansehen. Salesforce verarbeitet die Anforderung im Hintergrund.

Die SOAP und REST APIs dagegen verwenden synchrone Anforderungen und sind für Echtzeit-Clientanwendungen optimiert, bei denen jeweils nur wenige Datensätze aktualisiert werden. Sie können diese beiden APIs zwar auch zum Verarbeiten einer größeren Anzahl an Datensätzen verwenden, sie sind jedoch weniger praktisch, wenn die Datensets Hunderte oder Tausende von Datensätzen enthalten. Das asynchrone Framework der Bulk-API ist so konzipiert, dass das Verarbeiten von Daten aus einigen Tausend bis hin zu Millionen von Datensätzen effizient und problemlos möglich ist.

Die einfachste Möglichkeit zur Verwendung der Bulk-API besteht darin, sie für das Verarbeiten von Datensätzen in Data Loader über CSV-Dateien zu aktivieren. Wenn Sie den Data Loader verwenden, müssen Sie keine eigene Clientanwendung schreiben. Manchmal ist es aufgrund spezieller Anforderungen notwendig, eine benutzerdefinierte Anwendung zu schreiben. Mit der Bulk-API nehmen Sie das Steuerrad selbst in die Hand und setzen Kurs auf eine Lösung, die Ihre Anforderungen erfüllt.

Bei dieser Lektion verwenden Sie eine neuere Version der Bulk-API mit der Bezeichnung Bulk API 2.0. Wenn Sie das in der dieser Lektion Gelernte auf die vorherige, weiterhin unterstützte Version der Bulk-API anwenden möchten, müssen Sie andere Ressourcen-URIs verwenden und sowohl Batches als auch Aufträge erstellen und verwalten. Weitere Informationen zur Vorgängerversion der Bulk-API finden Sie im Bulk API Developer Guide.

Importieren von Daten in Ihre Organisation

Bei unserer Erkundung der Bulk-API verwenden wir Workbench zum Erstellen einige Accountdatensätze.

Erstellen eines Bulk-Auftrags

Da die Bulk-API auf REST basiert, können wir den REST Explorer von Workbench verwenden, um Bulk-API-Anforderungen durchzuführen.
  1. Melden Sie sich bei Ihrem Trailhead Playground an und navigieren Sie zu Workbench.
  2. Wählen Sie als Umgebung Production aus. Wählen Sie als API-Version die höchste verfügbare Versionsnummer aus. Aktivieren Sie unbedingt das Kontrollkästchen I agree to the terms of service.
  3. Klicken Sie auf Login with Salesforce.
  4. Wählen Sie im oberen Menü utilities | REST Explorer aus.

Nun sind wir bereit, unsere Daten hochzuladen. Der erste Schritt ist die Erstellung eines Auftrags. Ein Auftrag gibt den Vorgangstyp und das verwendete Datenobjekt an. Er fungiert als Bucket, in den wir Daten zur Verarbeitung hinzufügen.

Wir verwenden die Ressource /jobs/ingest, um einen Auftrag zu erstellen. Diese Ressource kann auch zum Abrufen einer Liste aktueller Aufträge verwendet werden.

Zum Erstellen eines Auftrags senden wir an /jobs/ingest eine POST-Anforderung, deren Anforderungstext die Eigenschaften des Auftrags enthält. Da die Bulk-API auf REST basiert, hat die Anforderung die vertraute Form einer REST-Anforderung mit vier Komponenten: URI, HTTP-Methode, Header und Anforderungstext. Wie bereits erwähnt, ist die Methode POST.

Für den URI ersetzen Sie den Text im URI-Textfeld durch folgenden Text: /services/data/vXX.0/jobs/ingest, wobei XX.0 für die verwendete API-Version steht. Zu diesem URI möchten wir ein paar Dinge anmerken:
  • Wir verwenden /services/data, also denselben Endpunkt wie für die REST-API. Die Bulk-API nutzt dasselbe Framework wie die REST API, was bedeutet, dass die Bulk-API viele gleiche Funktionen unterstützt, wie etwa die OAuth-Authentifizierung.
  • /jobs/ingest gibt an, dass wir auf die Ressource zugreifen, um Bulk-API-Aufträge zu erstellen.
Für den Anforderungstext kopieren Sie den folgenden Text und fügen ihn ein.
{
  "operation" : "insert",
  "object" : "Account",
  "contentType" : "CSV",
  "lineEnding" : "CRLF"
}

Diese Eigenschaften geben an, dass wir den insert-Vorgang für die Daten verwenden möchten, die wir an den Auftrag senden. Gesendet werden Accountdaten im CSV-Format. Die Bulk-API unterstützt Nutzlast im CSV-Format.

Ihr REST Explorer sieht etwa wie folgt aus.

Anforderung zur Auftragserstellung im REST Explorer

Klicken Sie auf Execute und sehen Sie sich die Antwort an.

Antwort auf die Anforderung zur Auftragserstellung

Die Antwort enthält alle möglichen Eigenschaften für den Auftrag, von denen uns die meisten im Moment nicht interessieren, da wir noch keine Daten hinzugefügt haben. Einige Eigenschaften möchten wir jedoch kurz erwähnen. Sehen Sie sich die Auftrags-ID (id) an und kopieren Sie sie in eine Textdatei. Wir verwenden sie später, um Daten zum Auftrag hinzuzufügen und den Auftragsstatus abzurufen. Sehen Sie sich außerdem die Eigenschaft state an. Wenn Sie einen Auftrag erstellen, wird der Status ("state") automatisch auf "Open" (Offen) festgelegt. Das heißt, der Auftrag ist bereit, Daten zu empfangen. Und zuletzt werfen wir einen Blick auf die Eigenschaft contentUrl. Diese Eigenschaft zeigt den URL, den wir verwenden, um Daten für den Auftrag zu laden.

Hinzufügen von Daten zum Auftrag

Jetzt können wir Accountdaten in Ihren Auftrag einfügen. Daten für einen Auftrag werden als Datensatzmenge in einer PUT-Anforderung an den Server gesendet. Der Server verarbeitet die Datensatzmenge und ermittelt dabei die optimale Methode zum Laden der Daten in Salesforce. Sie müssen dann nur noch die Daten hochladen.

Erstellen Sie eine neue Anforderung in Workbench. Ersetzen Sie den Text im URI-Textfeld durch folgenden Text: /services/data/v XX.0/jobs/ingest/jobID/batches. Ersetzen Sie jobID durch die Auftrags-ID, die Sie zuvor kopiert haben. Wählen Sie als HTTP-Methode PUT aus.

In diesem Beispiel fügen wir eine Datensatzmenge aus nur vier Accounts hinzu. Normalerweise verwenden Sie die Bulk-API, um Tausende oder Millionen von Datensätzen hinzuzufügen, das Prinzip ist jedoch dasselbe. Kopieren Sie den folgenden CSV-Text in den Anforderungstext.
"Name"
"Sample Bulk API Account 1"
"Sample Bulk API Account 2"
"Sample Bulk API Account 3"
"Sample Bulk API Account 4"

Wir verwenden CSV-Daten, das wir dieses Format beim Erstellen des Auftrags festgelegt haben.

Klicken Sie auf Header und ändern Sie Content-Type in text/csv. Ihre Anforderung sieht etwa wie folgt aus.

Hinzufügen von Auftragsdaten mit dem REST Explorer

Klicken Sie auf Execute (Ausführen).

Die Antwort besteht nur aus dem Statuscode 201 (Erstellt), der bedeutet, dass Salesforce die Auftragsdaten erfolgreich erhalten hat.

Schließen des Auftrags

Wir haben unsere Daten jetzt übertragen und weisen Salesforce nun an, die Daten zu verarbeiten. Dazu ändern wir den Auftragsstatus von "Open" in UploadComplete.
Ersetzen Sie den Text im URI-Textfeld durch folgenden Text: /services/data/v XX.0/jobs/ingest/ jobID. Ersetzen Sie auch hier XX durch die verwendete API-Version und Auftrags-ID durch die ID des Auftrags. Wählen Sie als HTTP-Methode PATCH aus. Klicken Sie auf Header und legen Sie Content-Type auf application/json fest. Ersetzen Sie den Text im Anforderungstext durch folgenden JSON-Text.
{
   "state" : "UploadComplete"
}

Klicken Sie auf Execute (Ausführen). Die Antwort enthält Informationen über den Auftragsstatus. Die Eigenschaft state gibt an, dass der Auftragsstatus UploadComplete lautet. An diesem Punkt beginnt Salesforce mit der Verarbeitung des Auftrags.

Prüfen des Auftragsstatus

Wir haben unsere Daten übertragen. Wir haben Salesforce mitgeteilt, dass wir mit dem Hochladen von Daten fertig sind. Jetzt ist es am Server, die Anforderung zu verarbeiten. Wir können die Fortschritte des Servers überwachen, indem wir den Status des Auftrags über die API oder die Salesforce-Benutzeroberfläche prüfen. Geben Sie in Salesforce unter "Setup" im Feld Schnellsuche den Text "Aufträge für das Massenladen von Daten" ein und wählen Sie Aufträge für das Massenladen von Daten aus. Auf dieser Seite können Sie den Status eines Auftrags prüfen. Sie können auch auf eine Auftrags-ID klicken, um die Statusangaben zu prüfen und detaillierte Ergebnisse für diesen Auftrag abzurufen.

In der API verwenden wir die Ressource /jobs/ingest/jobID zum Überwachen eines Auftrags. Ersetzen Sie den Text im URI-Textfeld durch folgenden Text: /services/data/vXX.0/jobs/ingest/jobID (nehmen Sie die üblichen Ersetzungen vor). Wählen Sie als HTTP-Methode GET aus.

Klicken Sie auf Execute (Ausführen). Das Ergebnis sollte etwa wie folgt aussehen:

Prüfen des Auftragsstatus

Lautet der state noch UploadComplete anstelle von JobComplete, dann verarbeitet Salesforce den Auftrag noch. Das macht aber nichts. Die Verarbeitung erfolgt in wenigen Minuten. Gönnen Sie sich in der Zwischenzeit doch ein Gläschen Rum und prüfen Sie dieselbe Anforderung anschließend erneut. Wenn Sie Glück hatten und Ihr Auftrag bereits verarbeitet wurde, fahren Sie entweder damit fort, die Auftragsergebnisse abzurufen oder gönnen sich die kleine Rum-Pause trotzdem.

Abrufen der Auftragsergebnisse

Sobald der Zustand (state) eines Auftrags JobComplete (oder Failed) lautet, können wir Ergebnisinformationen in Form von erfolgreich oder nicht erfolgreich verarbeiteten Datensätzen abrufen.

Sehen wir uns zuerst die erfolgreich verarbeiteten Datensätze an. Ersetzen Sie im REST Explorer von Workbench den Text im URI-Textfeld durch folgenden Text: /services/data/vXX.0/jobs/ingest/jobID/successfulResults (nehmen Sie die üblichen Ersetzungen vor). Wählen Sie als HTTP-Methode GET aus.

Klicken Sie auf Execute (Ausführen). Das Ergebnis sollte etwa wie folgt aussehen:

Überprüfen der erfolgreichen Ergebnisse

Salesforce gibt eine CSV-Datei mit einer Liste aller Datensätze aus dem Auftrag zurück, die erfolgreich verarbeitet wurden. In diesem Modul haben wir mehrere Accountdatensätze erstellt. Die CSV-Daten enthalten die Datensatz-ID des erstellten Datensatzes und den Wert TRUE für die Spalte sf__Created.

Manchmal können einige Datensätze nicht verarbeitet werden. Vielleicht versuchte der Auftrag, bereits vorhandene Accountdatensätze zu erstellen. Vielleicht fehlten in den Auftragsdaten erforderliche Felder. In diesen Fällen können wir aus Salesforce eine Liste mit Datensätzen abrufen, die die Datensätze aufführt, bei denen während der Verarbeitung Fehler auftraten, und weitere Informationen über die Fehlerursache enthält.

Ersetzen Sie im REST Explorer den Text im URI-Textfeld durch folgenden Text: /services/data/vXX.0/jobs/ingest/jobID/failedResults (nehmen Sie die üblichen Ersetzungen vor). Wählen Sie als HTTP-Methode GET aus.

Klicken Sie auf Execute (Ausführen). Die Ergebnisse sehen etwa wie folgt aus.

Überprüfen der fehlgeschlagenen Ergebnisse

Salesforce gibt eine CSV-Datei zurück, die eine Liste der Datensätze enthält, bei denen während der Verarbeitung Fehler auftraten, und zusätzlich die Datensatz-ID und die Fehlermeldung aufführt. In diesem Fall wurden alle Ihre Datensätze erfolgreich eingefügt. Die Liste der Datensätze ist daher leer. Gute Arbeit, Kapitän.

Ressourcen

Bulk API 2.0 Developer Guide

Bulk API Developer Guide (ältere Version der Bulk-API, die in dieser Lektion nicht behandelt wird)

Workbench

Hinweis

Hinweis

Nicht vergessen: Dieses Modul bezieht sich auf Salesforce Classic. Wenn Sie Ihre Übungs-Organisation starten, wechseln Sie zu Salesforce Classic, um diese Aufgabe abzuschließen.