Erfassen Sie Ihre Fortschritte
Trailhead-Startseite
Trailhead-Startseite

Verwenden der REST-API

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:
  • Anmelden bei Workbench und Navigieren zum REST Explorer
  • Verwenden der Describe-Ressource
  • Erstellen eines Accounts unter Verwendung der REST-API
  • Ausführen einer Abfrage mit der REST-API

REST-Ressourcen und -Methoden

Land in Sicht! Kapitän, der Ausguck meldet "Insel REST voraus". Bevor wir ankern und die API verwenden, sollten wir einen Blick auf die REST-Ressourcen und -Methoden werden.

Eine REST-Ressource stellt eine Abstraktion einer Information oder Aktion dar, wie etwa ein einzelner Datensatz, eine Sammlung von Datensätzen oder eine Abfrage. Jede Ressource in der REST-API wird durch einen benannten URI (Uniform Resource Identifier) identifiziert. Der Zugriff auf Ressourcen erfolgt mit standardmäßigen HTTP-Methoden (HEAD, GET, POST, PATCH, DELETE). Die REST-API basiert auf der Nutzung von Ressourcen, ihrer URIs und den Links zwischen ihnen.

Sie verwenden eine Ressource für die Interaktion mit Ihrer Salesforce-Organisation. Beispielsweise haben Sie folgende Möglichkeiten:
  • Abrufen von zusammenfassender Informationen über die API-Versionen, die Ihnen zur Verfügung stehen
  • Abrufen detaillierter Informationen über ein Salesforce-Objekt wie z. B. Account, Benutzer oder ein benutzerdefiniertes Objekt
  • Durchführen einer Abfrage oder Suche
  • Aktualisieren oder Löschen von Datensätzen

Eine REST-Anforderung besteht aus vier Komponenten: einem Ressourcen-URI, einer HTTP-Methode, Anforderungs-Headern und einem Anforderungstext. Anforderungs-Header geben Metadaten für die Anforderung an. Der Anforderungstext gibt, falls notwendig, Daten für die Anforderung an. Wenn keine Daten angegeben werden müssen, wird der Anforderungstext weggelassen.

Beschreiben des Objekts "Account"

Schluss mit den Trockenübungen. Wir verwenden jetzt Workbench, um einige API-Aufrufe zu erstellen. Workbench ist eine Suite aus Tools, welche die Interaktion mit Ihrer Salesforce-Organisation über die API ermöglichen. Die Sie REST-Anforderungen von jedem HTTP-Sender aus senden können, stehen Ihnen auch zahlreiche andere Tools zur Verfügung (z. B. cURL oder Postman). Da Workbench jedoch ein benutzerfreundliches Framework speziell für Salesforce-APIs bereitstellt, ist dies ein guter Einstieg, bis Sie in der Lage sind, eine ausgewachsene Integrationslösung zu schreiben.
Der erste Schritt besteht in der Anmeldung bei Workbench.
  1. Melden Sie sich bei Ihrem Trailhead Playground an und navigieren Sie zu Workbench.
  2. Wählen Sie als Umgebung Production aus.
  3. Wählen Sie als API-Version die höchste verfügbare Versionsnummer aus.
  4. Aktivieren Sie unbedingt das Kontrollkästchen I agree to the terms of service.
  5. Klicken Sie auf Login with Salesforce.

Daraufhin wird die Workbench-Startseite angezeigt. Bei diesem Modul verwenden wir nur eines der vielen Tools von Workbench, den REST Explorer.

Wählen Sie im oberen Menü utilities | REST Explorer aus.

REST Explorer von Workbench

Sie können REST-API-Aufrufe vom REST Explorer aus durchführen, wie von jeder beliebigen anderen HTTP-Schnittstelle aus. Der Text im Textfeld ist ein Ressourcen-URI. Für mehr Benutzerfreundlichkeit wird die oberste Domäne beim angezeigten URI weggelassen. Der vollständige URI der Ressource, die in das URI-Textfeld eingetragen wird, lautet beispielsweise https://foo.my.salesforce.com/services/data/v36.0.

Die Optionsschaltflächen oberhalb des URI stehen für die standardmäßigen HTTP-Methoden. Für einen API-Aufruf geben Sie den Ressourcen-URI ein, wählen die gewünschte Methode aus, fügen nach Bedarf Header hinzu und klicken auf Execute (Ausführen).

Lassen Sie uns die Ressource "SObject Describe" ausprobieren. Diese Ressource gibt in Kombination mit der GET-Methode Metadaten über ein Objekt und seine Felder zurück.

Wir werden nun das Objekt "Account" beschreiben. Ersetzen Sie den vorhandenen Text im URI-Textfeld durch /services/data/vXX.0/sobjects/account/describe, wobei XX für die verwendete API-Version steht.

URI zum Beschreiben eines Accounts
Sehen wir uns kurz die Bestandteile des URI dieser Ressource an.
  • /services/data: Gibt an, dass wir eine REST-API-Anforderung durchführen.
  • /V36.0: API-Versionsnummer
  • /sobjects: Gibt an, dass wir auf eine Ressource unter der sObject-Gruppierung zugreifen.
  • /account: sObject, für das die Aktion durchgeführt wird, in diesem Fall ist dies "account"
  • dDescribe: Aktion, in diesem Fall eine Describe-Anforderung

Stellen Sie nun sicher, dass die Methode GET ausgewählt ist, und klicken Sie auf Execute (Ausführen).

Antwort zur Beschreibung des Accountobjekts

Gute Arbeit, Kapitän. Die Account-Metadaten werden auf dem Bildschirm angezeigt. Und Workbench hat die Antwort ansehnlich formatiert. Wenn Sie die JSON-Antwort in Rohformat sehen möchten, klicken Sie auf Show Raw Response (Rohantwort anzeigen).

JSON-Antwort zur Beschreibung des Accountobjekts

Im JSON-Format werden die Account-Metadaten unterhalb einiger HTTP-Antwortheader angezeigt. Da die REST-API sowohl JSON als auch XML unterstützt, ändern wir nun den Anforderungs-Header, damit wir eine XML-Antwort erhalten. Klicken Sie neben den HTTP-Methoden auf Headers (Header). Ersetzen Sie im Header-Wert "Accept" die Angabe application/json durch application/xml. Ihre Anforderungs-Header sehen nun wie folgt aus.

Anforderungs-Header zur Angabe von XML

Klicken Sie auf Execute (Ausführen). Die XML-Rohantwort wird zurückgegeben. Hurra!

Erstellen eines Accounts

Jetzt erstellen wir ein Account mit der SObject-Ressource und der POST-Methode. Ersetzen Sie den vorhandenen Text im URI-Textfeld durch /services/data/vXX.0/sobjects/account, wobei XX für die verwendete API-Version steht. Wählen Sie POST aus. Wie Sie sehen, wird nun ein Textbereich "Request Body" (Anforderungstext) eingeblendet, in dem wir die Feldwerte für unseren neuen Account angeben. Zunächst ändern wir jedoch den Accept-Header wieder in JSON.

Klicken Sie auf Headers (Header). Ändern Sie "Accept: application/xml" wieder in "Accept: application/json". Ihre Anforderung sieht nun wie folgt aus.

REST-Anforderungs-Header
Geben Sie im Anforderungstext folgenden Text ein.
{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

Klicken Sie auf Execute (Ausführen). Die daraufhin angezeigte Antwort sieht so aus:

Erfolgreiche Anforderung zur Accounterstellung in der REST-API

Bei "success: true" wurde der Account mit der zurückgegebenen ID erstellt. Blenden Sie den Ordner "errors" ein, um nach Fehlern zu sehen.

Lassen Sie uns jetzt spaßeshalber einen zweiten Account erstellen, ohne einen Accountnamen anzugeben. Ersetzen Sie den Text im Anforderungstextbereich durch folgenden Text.
{
  "ShippingCity" : "San Francisco"
}

Klicken Sie auf Execute (Ausführen).

Oje. Haben Sie eine Antwort des Typs REQUIRED_FIELD_MISSING erhalten? Blenden Sie zuerst den Ordner REQUIRED_FIELD_MISSING und dann den Ordner fields ein. Die eingeblendete Antwort sieht wie folgt aus.

Wenn wir keinen Accountnamen angeben, wird ein Fehler gemeldet.
Da Name ein Pflichtfeld beim Erstellen eines Accounts ist, hat der Server die Anforderung nicht verarbeitet und eine Fehlermeldung zurückgegeben. Glücklicherweise werden alle Informationen, die zum Beheben des Fehlers notwendig sind, in der Fehlerantwort angegeben. Geben Sie nun den Namen NewAccount2 an und ändern Sie den Wert von ShippingCity im Anforderungstext. Ersetzen Sie den Text im Anforderungstextbereich durch folgenden Text.
{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

Klicken Sie auf Execute (Ausführen). Geschafft!

Ausführen einer Abfrage

Stellen wir uns nun einmal vor, Sie oder ein anderer Benutzer haben Hunderte Accounts erstellt. Sie möchten die Namen aller Accounts feststellen, bei denen der Ort der Lieferanschrift "San Francisco" lautet. Sie können die Query-Ressource verwenden, um eine SOQL-Abfrage auszuführen und genau die gewünschten Datensätze abzurufen.

Ersetzen Sie den Text im URI-Textfeld durch folgenden Text: /services/data/v XX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco', wobei XX für die verwendete API-Version steht.

In der Abfragezeichenfolge wurden Leerzeichen durch das +-Zeichen ersetzt, um den URI korrekt zu codieren. Weitere Informationen über das Codieren von HTML URLs finden Sie unter dem entsprechenden Link im Abschnitt "Ressourcen". Stellen Sie sicher, dass die Methode GET ausgewählt ist, und klicken Sie auf Execute (Ausführen).

Blenden Sie den Ordner records ein. Sehen Sie einen Ordner mit dem Namen des ersten Accounts, den wir erstellt haben, NewAccount1? Kein Problem. Klicken Sie darauf. Klicken Sie nun auf den Ordner attributes. Neben "url" wird der Ressourcen-URI des Accounts angegeben, der zurückgegeben wurde. Ihre Antwort sieht etwa wie folgt aus.

Abfrageantwort gibt einen Accountdatensatz zurück

Wenn Sie eine Integrationslösung schreiben, können Sie diesen URI aus der Antwort verwenden, um auf weitere Details über diesen Account zuzugreifen.

Beispiele für Node.js und Ruby

Sie haben jetzt gerade einen Vorgeschmack darauf bekommen, was mit der REST-API alles möglich ist. Wenn Sie von Workbench zum Schreiben von Code wechseln, interagieren Sie mit der REST-API natürlich mit der Programmiersprache Ihrer Wahl. Glücklicherweise haben erfahrene Salesforce-Entwickler Wrapper für verschiedene Sprachen geschrieben, die das Einspeisen von REST-API erleichtern. Im Folgenden finden Sie zwei in Node.js und Ruby geschriebene Beispielabfragen, die die Wrapper Nforce bzw. Restforce verwenden.

Node.js-Beispiel mit Nforce

var nforce = require('nforce');
// create the connection with the Salesforce connected app
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});
// authenticate and return OAuth token
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // execute the query
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // output the account names
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

Ruby-Beispiel mit Restforce

require 'restforce'
# create the connection with the Salesforce connected app
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']
# execute the query
accounts = client.query("select id, name from account limit 5")
# output the account names
accounts.each do |account|
  p account.Name
end

Ressourcen

REST API Developer Guide

Getting Started with Salesforce REST in Java

HTML URL Encoding Reference

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.