Verwenden der Bulk-API 2.0

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 der Webanwendung Postman
  
• 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
  

Hinweis

Lernen Sie auf Deutsch? Beginnen Sie die Aufgabe in einem Trailhead Playground in der Sprache Deutsch und verwenden Sie für die Navigation die in Klammern angegebenen Übersetzungen. Kopieren und fügen Sie nur die Angaben in Englisch ein, da zur Überprüfung der Aufgabe Daten in Englisch benötigt werden. Wenn Sie die Aufgabe in Ihrer deutschen Organisation nicht bestehen, empfehlen wir Ihnen folgende Vorgehensweise: (1) Stellen Sie das Gebietsschema auf USA um, (2) legen Sie Englisch als Sprache fest (Anweisungen dazu finden Sie hier) und (3) klicken Sie erneut auf die Schaltfläche "Check Challenge" (Aufgabe überprüfen).

Weitere Details dazu, wie Sie die übersetzte Trailhead-Umgebung optimal nutzen können, finden Sie unter dem Badge "Trailhead in Ihrer Sprache".

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.

Einrichten des Playgrounds und von Postman

Zum Erkunden der Bulk-API erstellen wir einige Accountdatensätze mit Postman.

1. Melden Sie sich bei Ihrem Trailhead Playground an.
   
2. Melden Sie sich bei der Webanwendung Postman an.
   
3. Verbinden Sie Ihren Playground mit Postman, indem Sie ein neues Token beziehen.
   
4. Testen Sie mit der Ressource "REST GET Limits", ob Ihre Verbindung funktioniert.
   

In Schnelleinstieg: Verbinden von Postman mit Salesforce haben Sie erfahren, wie das geht. Sehen Sie sich das Projekt also noch einmal an, wenn Sie sich bei einem der Schritte nicht mehr ganz sicher sind.

Erstellen eines Bulk-Auftrags

Der erste Schritt ist die Erstellung eines Auftrags im Fork der Salesforce API Collection. Ein Auftrag gibt den Vorgangstyp und das verwendete Datenobjekt an. Er fungiert als Bucket, dem wir Daten zur Verarbeitung hinzufügen.

1. Öffnen Sie in "Collections" (Sammlungen) den Ordner Bulk v2.
   
2. Klicken Sie auf POST Create job.
   

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. Die HTTP-Methode ist POST.

Beachten Sie den URI, der im Hauptfenster erstellt wurde, nachdem Sie auf die Ressource in der Sammlung geklickt haben: /services/data/v{{version}}/jobs/ingest. Zu diesem URI möchten wir ein paar Dinge anmerken:

• Sie 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.
  

Lassen Sie uns nun den Anforderungstext erstellen.

Um einen Bulk-API 2.0-Auftrag zu erstellen, geben Sie mithilfe des Anforderungsfelds lineEnding das Zeilenende an, das zur Erstellung des CSV-formatierten Texts verwendet wird. Die Bulk-API 2.0 unterstützt zwei Zeilenendformate: Zeilenvorschub (LF) und Wagenrücklauf plus Zeilenvorschub (CRLF). Die Standardeinstellung für lineEnding, sofern nicht angegeben, ist LF. Je nach Betriebssystem werden zur Kennzeichnung des Zeilenendes unterschiedliche Zeichen verwendet:

• Unter Unix/Linux/OS X LF (Zeilenvorschub, '\n', 0x0A)
  
• Unter Windows/DOS CRLF (Wagenrücklauf plus Zeilenvorschub, '\r\n', 0x0D0A)
  

Beachten Sie, dass Texteditoren zum Erstellen einer CSV-Datei möglicherweise für ein bestimmtes Zeilenendformat konfiguriert sind, das die Standardeinstellung des Betriebssystems überschreibt.

1. Kopieren Sie den CSV-Beispieltext aus Ihrem Browser und fügen Sie ihn in einen Texteditor ein, um die Formatierung zu löschen. Geben Sie das entsprechende Zeilenende mit dem Anforderungsfeld lineEnding abhängig vom verwendeten Betriebssystem und Texteditor an. In unserem Beispiel nutzen wir einen Windows-Computer mit "CRLF" als Wert für den Parameter lineEnding.
   

{
"operation" : "insert",
"object" : "Account",
"contentType" : "CSV",
"lineEnding" : "CRLF"
}

2. Kopieren Sie den CSV-Beispieltext aus dem Texteditor und fügen Sie ihn in Postman in die Registerkarte "Body" (Text) ein.
   
3. Klicken Sie auf Save (Speichern).
   
4. Klicken Sie auf Send (Senden) und sehen Sie sich die Antwort an.
   

Die Antwort enthält alle möglichen Eigenschaften des Auftrags, von denen uns die meisten im Moment nicht interessieren, da Sie noch keine Daten hinzugefügt haben. Lassen Sie uns dennoch einen Blick auf ein paar Details werfen. 

1. Sehen Sie sich die Zeile "id" an. Hier wird die für diesen Auftrag zurückgegebene Auftrags-ID gezeigt.
   

1. Klicken Sie im Abschnitt "Requests" (Anforderungen) auf die Registerkarte Tests.
   
2. Dieses Skript fügt die Auftrags-ID automatisch der Variablen __jobID hinzu. Dadurch wird die Auftrags-ID in künftige Anforderungen eingefügt, sodass Sie sie nicht mehr kopieren und einfügen müssen.
   

2. Als Nächstes sehen wir uns die Eigenschaft "state" an.
   

1. Wenn Sie einen Auftrag erstellen, wird der Status ("state") automatisch auf "Open" (Offen) festgelegt. Das heißt, der Auftrag ist bereit, Daten zu empfangen.
   

3. Und zuletzt werfen wir einen Blick auf die Eigenschaft "contentUrl".
   

1. Diese Eigenschaft zeigt den URL, mit dem wir Daten für den Auftrag laden.
   

Hinzufügen von Daten zum Auftrag

Jetzt können Sie 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 in Postman eine neue Anforderung. Klicken Sie in Ihrem Fork der "Salesforce API Collection" im Ordner "Bulk v2" auf PUT Upload Job Data. Beachten Sie, dass PUT die HTTP-Methode ist.

In diesem Beispiel fügen Sie eine Datensatzmenge mit nur vier Accounts hinzu. Normalerweise verwenden Sie die Bulk-API, um Tausende oder Millionen von Datensätzen hinzuzufügen, das Prinzip ist jedoch dasselbe. Sie können eine CSV-Datei hochladen, indem Sie das Optionsfeld "Binary" (Binär) auswählen und Ihre CSV-Datei hochladen, oder Sie können eine Liste einfügen. In diesem Beispiel fügen wir eine Liste ein.

1. Klicken Sie auf die Registerkarte Body (Textkörper) und wählen Sie in der Dropdown-Liste Raw (Rohdaten) aus.
   
2. Kopieren Sie den folgenden Text in einen Texteditor, um alle überflüssigen Formatierungen zu entfernen, und kopieren Sie ihn dann aus der Textdatei in das Feld für den Anforderungstext.
   

"Name"
"Global Treasures & Mapping Company"
"Ahab’s Mighty Masts"
"Planks R Us"
"Cap’n Cook’s Kitchen Supplies"

3. Klicken Sie auf Headers (Header). Beachten Sie, dass für "Content Type" (Inhaltstyp) text/csv angegeben ist. Das liegt daran, dass Sie in Ihrer ersten Anforderung den Inhaltstyp angegeben haben.

     4. Klicken Sie auf Save (Speichern).

5. Klicken Sie auf Send (Senden).

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

Schließen des Auftrags

Nachdem Sie Ihre Daten übermittelt haben, müssen Sie Salesforce mitteilen, dass die Daten verarbeitet werden sollen. 

1. Klicken Sie in Ihrem Salesforce-API-Fork in "Bulk v2" im Ordner "Query" auf PATCH Close or Abort a Job.
   
2. Klicken Sie auf die Registerkarte Body (Textkörper) und achten Sie darauf, dass "state" bereits mit "UploadComplete" ausgefüllt ist.
   

     3. Klicken Sie auf die Registerkarte Headers (Header) und beachten Sie, dass "Content-Type" auf application/json festgelegt ist.

4. Klicken Sie auf Send (Senden).

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

Sie haben Ihre Daten übermittelt und Salesforce wissen lassen, dass das Hochladen der Daten abgeschlossen ist. Jetzt ist es am Server, die Anforderung zu verarbeiten. Sie können den Fortschritt des Servers überwachen, indem Sie den Status des Auftrags auf der Salesforce-Benutzeroberfläche oder über die API prüfen. Schauen wir uns die einzelnen Methoden an.

Sie können den Status des Auftrags in Ihrem Trailhead Playground wie folgt überprüfen. 

1. Geben Sie unter Setup im Feld "Schnellsuche" den Text Aufträge für das Massenladen von Daten ein.
   
2. 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.

Sie können den Status des Auftrags in Ihrem Ordner "Bulk v2" wie folgt überprüfen.

1. Wählen Sie GET Job Info aus. Beachten Sie, dass GET die für diese Art von Anforderung verwendete HTTP-Methode ist.
   
2. Klicken Sie auf Send (Senden).
   

Das Ergebnis sollte etwa wie folgt aussehen:

Wenn "state" noch UploadComplete statt JobComplete lautet, verarbeitet Salesforce den Auftrag noch. Das macht aber nichts. Die Verarbeitung erfolgt in wenigen Minuten. Gönnen Sie sich in der Zwischenzeit doch ein Tässchen Kokosmilch und prüfen Sie dieselbe Anforderung anschließend erneut. Wenn Sie Glück hatten und Ihr Auftrag bereits verarbeitet wurde, fahren Sie mit dem Abrufen der Auftragsergebnisse fort.

Abrufen der Auftragsergebnisse

Sobald der "state" (Status) eines Auftrags JobComplete (oder Failed) lautet, können wir Ergebnisinformationen in Form erfolgreich oder nicht erfolgreich verarbeiteter Datensätze abrufen.

Sehen wir uns die erfolgreich verarbeiteten Datensätze im Ordner "Bulk v2" an.

1. Klicken Sie auf die Ressource GET Get Job Successful Record Results. Beachten Sie, dass GET die HTTP-Methode ist.
   
2. Klicken Sie auf Send (Senden). Das Ergebnis sollte etwa wie folgt aussehen:
   

Salesforce gibt eine Liste aller Datensätze im Auftrag zurück, die erfolgreich verarbeitet wurden. In diesem Modul haben Sie mehrere Accountdatensätze erstellt. Zeile 1 enthält die Wertetypen der Antworten, die darunter zurückgegeben werden. Die Listendaten enthalten die Datensatz-IDs der erstellten Datensätze, den Wert "true" für die Spalten sf__Created und die Namen der erstellten Accounts. Gut gemacht! 

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 Sie aus Salesforce eine Liste mit Datensätzen, bei denen während der Verarbeitung Fehler aufgetreten sind, und weitere Informationen über die Fehlerursache abrufen. Sehen wir uns die nicht erfolgreich verarbeiteten Datensätze im Ordner "Bulk v2" an.

1. Wählen Sie die Ressource GET Get Job Failed Record Results aus. Beachten Sie, dass GET wiederum die HTTP-Methode ist.
   
2. Klicken Sie auf Send (Senden). Die Ergebnisse sehen etwa wie folgt aus.
   

Postman gibt eine Liste der Datensätze, bei denen während der Verarbeitung Fehler aufgetreten sind, und ferner die Datensatz-ID und die Fehlermeldung zurück. In diesem Fall wurden alle Ihre Datensätze erfolgreich eingefügt. Die Liste der Datensätze ist daher leer. Gute Arbeit, Kapitän.

Ressourcen

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