Verwenden der REST-API

Lernziele

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

• Anmelden bei der Anwendung Postman und Navigieren zum Ordner "REST" in "Salesforce API Collection"
• Verwenden der Ressource "GET SObject Describe"
• Erstellen eines Accounts unter Verwendung der REST-API
• Ausführen einer Abfrage mit der REST-API

Hinweis

Lernen Sie auf Deutsch? In diesem Badge ist für die praktischen Trailhead-Aufgaben Englisch als Bearbeitungssprache festgelegt. Übersetzungen werden zur Referenz in Klammern angegeben. Vergewissern Sie sich, dass Sie in Ihrem Trailhead-Playground (1) das Gebietsschema auf USA und (2) die Sprache auf Englisch festgelegt haben. (3) Verwenden Sie zum Kopieren und Einfügen nur die englischen Werte. Die zugehörigen Anweisungen finden Sie hier.

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

REST-Ressourcen und -Methoden

Sie verwenden jetzt Postman, um einige API-Aufrufe zu erstellen. Sie können REST-Anforderungen über einen beliebigen HTTP-Absender stellen. Und Postman ist nur eines von vielen Tools, die Sie für die Interaktion mit Ihrer Salesforce-Organisation über die API einsetzen können.  

Der erste Schritt besteht darin, einen neuen Trailhead Playground zu erstellen, ihn mit der Anwendung Postman zu verbinden, CORS (Cross-Origin Resource Sharing) einzurichten und einen Fork zur Salesforce API Collection zu erstellen. Absolvieren Sie hierfür Schnelleinstieg: Verbinden von Postman mit Salesforce. 

Sie können wie bei jeder anderen HTTP-Schnittstelle REST-API-Aufrufe an Ihren Trailhead Playground richten, indem Sie die Ressourcen in der Anwendung Postman unter "Salesforce API Collection" im Ordner "REST" verwenden. Wenn Sie in der Salesforce API Collection eine Ressource auswählen, wird der URI im oberen Bereich des Hauptfensters angezeigt. 

Beschreiben des Objekts "Account"

Sehen wir uns nun an, wie dies funktioniert.

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

1. Wählen Sie in "Collections" Ihren Fork der Salesforce APIs Collection aus.
2. Klicken Sie auf den Ordner REST.
3. Klicken Sie auf SObject.
4. Klicken Sie auf GET SObject Describe.
5. Öffnen Sie im Hauptbereich die Registerkarte Params (Parameter).
6. Geben Sie unter "Path Variables" (Pfadvariablen) in der Zeile SOBJECT_API_NAME der Spalte VALUE Account ein.

Ehe Sie sich die Ergebnisse Ihrer Abfrage ansehen, lassen Sie uns kurz den URI dieser Ressource aufschlüsseln.

• GET: die für diesen API-Aufruf verwendete HTTP-Methode.
• {{_endpoint}}: die Stelle, an der die Anforderung erfolgt. In diesem Fall haben Sie den URL Ihres Trailhead Playgrounds in das Feld "_endpoint" in den Variablen zum Herstellen einer Verbindung mit Salesforce eingefügt.
• /services/data: gibt an, dass Sie eine REST-API-Anforderung stellen.
• /v {{version}}: die API-Versionsnummer. Die doppelten geschweiften Anführungszeichen bedeuten, dass diese Einstellung als Variable festgelegt werden kann.
• /sobjects: gibt an, dass wir auf eine Ressource unter der Gruppierung "sObject" zugreifen.
• /:SOBJECT_API_Name: das sObject, für das die Aktion erfolgt, in diesem Fall "Account".
• /describe: eine Aktion, in diesem Fall eine Describe-Anforderung.

Gut gemacht, Kapitän! Die Metadaten für "Account" werden auf dem Bildschirm angezeigt und Postman hat die Antwort ansehnlich formatiert. Wenn Sie die JSON-Antwort in Rohformat sehen möchten, klicken Sie auf Raw (Rohformat).

Die Metadaten für "Account" werden im JSON-Format angezeigt. Da die REST-API sowohl JSON als auch XML unterstützt, ändern wir nun den Anforderungs-Header, damit wir eine XML-Antwort erhalten. 

1. Klicken Sie im Anforderungsfenster auf Headers (Header).
2. Fügen Sie einen neuen Header mit Accept als Key (Schlüssel) und application/xml als Value (Wert).

Ihre Anforderungs-Header sehen nun wie folgt aus.

{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

{
"ShippingCity" : "Melbourne"
}

SELECT Name From Account WHERE ShippingCity = 'Melbourne'

Beispiele für Node.js und Ruby

const jsforce = require("jsforce");const conn = new jsforce.Connection({
  // you can change loginUrl to connect to sandbox or prerelease env.
  // loginUrl : "https://test.salesforce.com"
});
// Log in with basic SOAP login (see documentation for other auth options)
conn.login(
  process.env.USERNAME,
  process.env.PASSWORD + process.env.SECURITY_TOKEN,
  (err, res) => {
    if (err) {
      return console.error("Failed to log in to Salesforce: ", err);
    }
    console.log("Successfully logged in!");
    // Run a SOQL query
    conn.query("SELECT Id, Name FROM Account LIMIT 5", (err, result) => {
      if (err) {
        return console.error("Failed to run SOQL query: ", err);
      }
      // Display query results
      const { records } = result;
      console.log(`Fetched ${records.length} records:`);
      records.forEach(record => {
        console.log(`- ${record.Name} (${record.Id})`);
      });
    });
  }
);

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