Verwenden der Bulk-API 2.0

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"
}

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.

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.

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

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