Verwenden der SOAP-API

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:

• Erstellen einer WSDL-Datei für Ihre Organisation
  
• Verwenden von SoapUI, um ein SOAP-Projekt aus der WSDL-Datei zu erstellen
  
• Anmelden bei Ihrem Trailhead Playground mit der SOAP-API
  
• Erstellen eines Accounts unter Verwendung der SOAP-API
  

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

Unternehmens- und Partner-WSDL

Wenn Sie schon in den Wassern einer anderen SOAP-basierten API gesegelt sind, wissen Sie, dass die WSDL-Datei (Web Services Description Language) im Prinzip die Seekarte ist, die die Verwendung der API erklärt. Sie enthält die Bindungen, Protokolle und Objekte für die Durchführung von API-Aufrufen.

Salesforce bietet zwei WSDLs der SOAP-API für zwei unterschiedliche Anwendungsfälle. Die Unternehmens-WSDL ist für eine einzelne Salesforce-Organisation optimiert. Sie ist streng typisiert und spiegelt die spezifische Konfiguration Ihrer Organisation wider. Das heißt, zwei Unternehmens-WSDLs, die in zwei unterschiedlichen Organisationen generiert wurden, enthalten unterschiedliche Informationen.

Die Partner-WSDL ist für die Verwendung mit vielen Salesforce-Organisationen optimiert. Sie ist locker typisiert und ändert sich nicht in Abhängigkeit von der spezifischen Konfiguration einer Organisation. Wenn Sie eine Integration für eine einzelne Salesforce-Organisation erstellen, verwenden Sie normalerweise die Unternehmens-WSDL. Für die Verwendung mit mehreren Organisationen verwenden Sie die Partner-WSDL.

In dieser Lektion verwenden wir die Unternehmens-WSDL für die Erkundung der SOAP-API. Zunächst erstellen wir eine WSDL-Datei für Ihre Organisation. Geben Sie in Ihrem Trailhead Playground unter Setup in das Feld "Schnellsuche" die Angabe "API" ein und wählen Sie dann API aus. Klicken Sie auf der Seite "API WSDL" auf Unternehmens-WSDL generieren.

Klicken Sie auf der Seite "Unternehmens-WSDL generieren" auf Generieren. Wenn die WSDL generiert wurde, klicken Sie mit der rechten Maustaste auf die Seite und speichern die WSDL als XML-Datei auf Ihrem Computer. Wir brauchen sie in Kürze.

Ein Tipp für den Umgang mit der Unternehmens-WSDL: Die Unternehmens-WSDL spiegelt die spezifische Konfiguration Ihrer Organisation wider. Sobald Sie also eine Metadatenänderung an Ihrer Organisation vornehmen, müssen Sie auch die WSDL-Datei neu generieren. So verhindern Sie, dass die WSDL-Datei nicht mehr der Konfiguration der Organisation entspricht.

Erstellen eines SOAP-Projekts mit SoapUI

Wir haben die WSDL-Datei jetzt erstellt und müssen nun einen Weg finden, die Informationen zu extrahieren, damit wir SOAP-API-Anforderungen erstellen können. In der Websprache bezeichnet man dies als "Einspeisen der WSDL". So wie sich eine Riesenkrake ein Schiff voller hilfloser Seeleute einverleibt, so speisen Tools wie der WSC (Web Services Connector) die WSDL-Datei ein. Anschließend erstellen die Tools Klassen, die Ihnen ermöglichen, unter Verwendung gängiger Programmiersprachen Anforderungen mit der SOAP-API durchzuführen.

In dieser Lektion verwenden wir ein Drittanbietertool namens SoapUI zum Einspeisen unserer Unternehmens-WSDL. SoapUI ist eine kostenlose Open-Source-Anwendung zum Testen von Webservices. Zum Einstieg laden Sie SoapUI OpenSource von der SoapUI-Website herunter und installieren die Anwendung. Installieren Sie nur die SoapUI-Komponente.

Stellen Sie sicher, dass die Version von Java, die SoapUI bündelt und verwendet, mit den Sicherheitsrichtlinien Ihres Unternehmens kompatibel ist. Um die von SoapUI verwendete Java-Version zu ermitteln, wählen Sie in SoapUI Help | System Settings (Hilfe | Systemeinstellungen) aus. Weitere Informationen finden Sie unter www.soapui.org.

Wenn Sie SoapUI installiert und gestartet haben, wechseln Sie zum Menü "File" und wählen New SOAP Project aus. Als Projektnamen geben Sie "Exploring Salesforce SOAP API" ein. Zur Angabe der Ausgangs-WSDL unter "Initial WSDL" wechseln Sie an den Speicherort, an dem Sie die Unternehmens-WSDL gespeichert haben, und wählen sie aus. Lassen Sie die restlichen Optionen unverändert. Ihr SoapUI-Fenster sieht etwa wie folgt aus.

Klicken Sie auf OK. Nach ein paar Sekunden Verarbeitungszeit wird ein Ordner namens "Exploring Salesforce SOAP API" im Navigationsbereich auf der linken Bildschirmseite angezeigt. Unter diesem Ordner befindet sich der Eintrag "SoapBinding", der mehrere Vorgänge enthält.

Was wird uns da gerade angezeigt? Jeder Vorgang entspricht einer SOAP-API-Anforderung, die wir durchführen können. Die Eigenschaften der einzelnen Vorgänge werden aus den Informationen in der WSDL-Datei eingelesen. Jeder Vorgang enthält zudem eine XML-Beispielanforderung, die den HTTPS-Endpunkt des Vorgangs und eine bereits formulierte SOAP-Nachricht enthält.

Noch etwas: Salesforce erfordert, dass für alle Verbindungen TLS 1.2 oder höher verwendet wird. Wenn Sie SoapUI mit Java 7 verwenden, ist TLS 1.2 standardmäßig nicht aktiviert. Wenn Sie versuchen, mit einer alten Version von TLS eine Verbindung mit Salesforce herzustellen, erhalten Sie eine Fehlermeldung. Die gute Nachricht ist, dass es eine ziemlich einfache Lösung gibt. In diesem nützlichen Blogpost finden Sie weitere Informationen.

Wir sind jetzt startklar und können SOAP-API-Anforderungen durchführen. Volle Segel voraus, Kapitän!

Anmelden bei Ihrem Trailhead Playground

Blättern Sie in SoapUI nach unten bis zum Vorgang "login". Erweitern Sie den Vorgang und doppelklicken Sie auf Request 1. Daraufhin wird ein Beispiel für eine SOAP login-Anforderung angezeigt.

Im Folgenden werden die Bestandteile des Endpunkt-URI (1) kurz erklärt.

• https://: Gibt sicheres HTTPan.
  
• login.salesforce.com: Oberste Domäne für eine Anmeldeanforderung.
  
• /services/Soap: Gibt an, dass wir eine SOAP-API-Anforderung stellen.
  
• /c: Gibt an, dass wir die Unternehmens-WSDL verwenden. Verwenden Sie /u für die Partner-WSDL.
  
• /36.0: API-Versionsnummer. Das Präfix v fehlt, da es nicht bei allen APIs vor der Versionsnummer vorhanden ist. Dieses Verhalten ist eine Eigenart von Salesforce-APIs.
  
• /0DF36000000LHZw: Paketversionsnummer.
  

Da wir bei diesem Beispiel wir keine verwalteten Pakete verwenden, können wir die Paketversionsnummer am Ende des URI entfernen. Lassen Sie uns dies als Nächstes erledigen.

Die SOAP-Nachricht (2) enthält alles, was wir in einer SOAP-Nachricht erwarten: einen Umschlag, eine Kopfzeile und einen Nachrichtentext.

Die Eigenschaften im Element LoginScopeHeader betreffen die Authentifizierung von Benutzern des Self-Service- und Kundenportals. Da wir uns für unsere Zwecke keine Gedanken um diese Werte machen müssen, löschen wir das gesamte <urn:LoginScopeHeader>-Element (alles ab <urn: LoginScopeHeader> bis </urn:LoginScopeHeader>). Markieren Sie den Text im Fenster und drücken Sie die Taste ENTFERNEN.

Sehen Sie sich als Nächstes das <urn:login>-Element im Nachrichtentext an. Dieses Element ist das Herzstück der Anmeldeanforderung. Hier geben wir unsere Anmeldeinformationen an. Ersetzen Sie die ? durch Ihren Benutzernamen und Ihr Kennwort für Ihren Trailhead Playground.

Hierfür benötigen Sie Ihre Trailhead Playground-Anmeldedaten. Suchen und öffnen Sie im App Launcher "Playground Starter" und führen Sie die folgenden Schritte aus. Wenn Sie die Anwendung "Playground Starter" nicht sehen, lesen Sie in der Salesforce-Hilfe den Artikel Festlegen von Benutzername und Kennwort für Ihren Trailhead Playground.

1. Klicken Sie auf die Registerkarte Get Your Login Credentials (Anmeldeinformationen abrufen) und notieren Sie Ihren Benutzernamen.
   
2. Klicken Sie auf Mein Kennwort zurücksetzen. Dadurch wird eine E-Mail an die E-Mail-Adresse gesendet, die Ihrem Benutzernamen zugeordnet ist.
   
3. Klicken Sie auf den Link in der E-Mail.
   

Da Sie die API-Anforderung von einer für Salesforce unbekannten IP-Adresse aus durchführen, müssen Sie Ihr Sicherheitstoken an das Ende Ihres Kennworts anhängen. Lautet Ihr Kennwort beispielsweise meinkennwort und Ihr Sicherheitstoken ist XXXXXXXXXX, geben Sie meinkennwortXXXXXXXXXX innerhalb des Elements <urn:password> ein.

Klicken Sie auf Ihren Avatar rechts oben im Bildschirm, wählen Sie "Settings (Einstellungen" aus und aktivieren Sie dann unter "My Personal Information (Meine persönliche Daten)" die Einstellung "Reset My Security Token (Mein Sicherheitstoken zurücksetzen)". Klicken Sie auf "Reset Security Token (Sicherheitstoken zurücksetzen)", um eine E-Mail an die E-Mail-Adresse zu senden, die mit dem Trailhead Playground mit Ihrem Sicherheitstoken verknüpft ist.

Ihre SOAP-Nachricht sieht etwa wie folgt aus.

Klicken Sie auf die Wiedergabeschaltfläche (grünes Dreieck) in der linken oberen Ecke des Anforderungsfensters. Diese Schaltfläche sendet die Anforderung, sie wirft also quasi Ihre SOAP-Flaschenpost ins Meer. So sieht die Antwort aus, wenn wir sie einblenden.

Glückwunsch, Kapitän. Sie haben sich erfolgreich angemeldet. Die Antwort enthält eine ganze Reihe von Informationen über Ihre Organisation und den Benutzer. Sie enthält vor allem Angaben zum Namen für "Meine Domäne" und zur Sitzungs-ID Ihrer Organisation, die wir für künftige Anforderungen verwenden (siehe Markierung).

Kopieren Sie die Instanz und die Sitzungs-ID in eine Textdatei. Wir nutzen diese Angaben in Kürze.

Da sich die Instanz Ihrer Organisation mit hoher Wahrscheinlichkeit ändern wird, sollten Sie Verweise auf die Instanz beim Erstellen von Integrationen nicht hartcodieren. Verwenden Sie stattdessen den Anmelde-URL für "Meine Domäne" Ihrer Organisation. Mithilfe von "Meine Domäne" konfigurieren Sie für Ihre Salesforce-Organisation eine kundenspezifische Domäne. Bei Verwendung von "Meine Domäne" müssen Sie keine Instanznamen mehr ändern. Sie können außerdem Ihre Marke hervorheben, Ihre Organisation sicherer gestalten und Ihre Anmeldeseite personalisieren.

Erstellen eines Accounts

Genau wie mit der REST-API erstellen wir jetzt einen Account mit der SOAP-API. Suchen Sie im Navigationsbereich auf der linken Bildschirmseite den Vorgang "create". Erweitern Sie den Vorgang und doppelklicken Sie auf Request 1.

Da das Erstellen eines Datensatzes komplizierter als die Anmeldung ist, enthält die create()-Nachricht von SOAP viel mehr Elemente. Die meisten Elemente befinden sich im Anforderungs-Header und der Großteil davon ist optional. Zur Vereinfachung werden wir die meisten Header-Angaben löschen. Sie sollten sich jedoch merken, dass Ihnen die von diesen Headern bereitgestellten Optionen beim Erstellen eines Datensatzes zur Verfügung stehen. Informationen zu den Funktionen der einzelnen Header finden Sie im SOAP API Developer Guide im Thema "SOAP Headers".

Ein Header, den wir nicht löschen sollten, ist SessionHeader. Dieser Header enthält die Sitzungs-ID, die wir aus der login()-Antwort kopiert haben. Löschen Sie die anderen Header, ab <urn:EmailHeader> bis </urn:AssignmentRuleHeader>. Ihre Nachricht sieht nun wie folgt aus.

Kopieren Sie die Sitzungs-ID aus der zuvor erstellten Textdatei und fügen Sie sie anstelle des Fragezeichens (?) in das Tag <urn:sessionId> ein.

Wir müssen noch einige weitere Anpassungen am Nachrichtentext vornehmen. Zuerst geben wir an, dass wir einen Account erstellen. Ändern Sie den Text im Tag <urn:sObjects> so, dass er wie folgt aussieht: <urn:sObjects xsi:type="urn1:Account" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> . Diese Änderung gibt unter Verwendung der XML-Schema-Instanzdeklaration den richtigen Datensatztyp an.

Wir möchten dem Account auch einen Namen geben. Fügen Sie <Name>Sample SOAP Account</Name> im sObjects-Element hinzu. Löschen Sie zudem die Elemente fieldsToNull und Id. Ihre Nachricht sieht jetzt etwa wie folgt aus.

Eine letzte Änderung muss noch gemacht werden, bevor wir die Anforderung durchführen. Ändern Sie den Endpunkt, damit anstelle von "login" die Instanz Ihrer Organisation angegeben wird, und entfernen Sie die Paketversion am Ende des URI. Der Endpunkt-URI sollte in etwa wie folgt aussehen: https://MyDomainName.trailblaze.develop.my.salesforce.com/services/Soap/c/36.0.

Jetzt sind wir bereit zum Senden der Anforderung! Klicken Sie erneut auf das grüne Dreieck. Es hat funktioniert! Sehen wir uns die Antwort an.

Sehen Sie sich den Header LimitInfoHeader an. Dieser Header gibt Informationen über Ihre API-Nutzung zurück. Laut dem obigen Beispiel haben wir 9 von 100.000 der für heute zulässigen Aufrufe verbraucht.

Sehen Sie sich im Antworttext das <result> an. <success>true</success> zeigt an, dass der Datensatz erfolgreich erstellt wurde. <id> enthält die ID des Datensatzes, die Sie in künftigen Anforderungen verwenden können.

Sie haben nun die Grundlagen für die Durchführung von Anforderungen mit der SOAP-API kennengelernt. Natürlich hat jeder Vorgang eigene Parameter und Eigenheiten. Verwenden Sie den SOAP API Developer Guide als Orientierungshilfe, wenn Sie damit beginnen, Integrationslösungen mit der SOAP-API zu schreiben.

Ressourcen

• SOAP API Developer Guide
• SOAP API Cheatsheet
• SOAP API Sample WSDL Structures
• SOAP API Web Services Connector (WSC)
• SoapUI Homepage