Verwendung von Apex-Callouts und ausgehenden Nachrichten mit Heroku

Lernziele

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

• Senden von Apex-Callouts und ausgehenden Nachrichten an Heroku
  
• Erörterung der Anwendungsfälle für Apex-Callouts und ausgehende Nachrichten
  

Callouts an Heroku-Anwendungen

Manchmal müssen Ereignisse in Salesforce aufgrund des Umfangs oder Typs des ausgeführten Prozesses von einem externen System verarbeitet werden. Beispiel: Ein Benutzer in Salesforce lädt ein Bild hoch, dessen Größe für die künftige Verwendung geändert werden muss. Heroku kann ein Ereignis aus Salesforce empfangen und in Reaktion darauf einen bestimmten Prozess ausführen. Die Ausgabe des Prozesses könnte optional mittels der REST-APIs oder Heroku Connect wieder in Salesforce gespeichert werden.

Es gibt verschiedene Methoden, eine Heroku-Anwendung auf der Basis eines Ereignisses in Salesforce aufzurufen: Apex HTTP-Callouts, ausgehende Nachrichten oder HTTP-Aktionen in Flow. Ein Apex HTTP-Callout nimmt dagegen programmgesteuert einen REST-Aufruf einer Heroku-Anwendung vor. Eine ausgehende Nachricht ist eine Aktion, die einen SOAP-Aufruf deklarativ durchführt. Bei beiden Methoden empfängt die Heroku-Anwendung eine Anforderung mit der Nutzlast aus Ereignisdetails und führt dann die Aktion durch.

Statten Sie den Blog Posts Swagger / OpenAPI + Salesforce = LIKE und Simplified API Integrations with External Services einen Besuch ab, um Informationen zu HTTP-Aktionen in Flow und externen Services zu erhalten.

Callouts mit Apex-Auslösern

Sie können Apex-Auslöser für Salesforce-Objekte definieren, um folgende Ereignisse zu behandeln:

• insert (Einfügen)
  
• update (Aktualisieren)
  
• delete (Löschen)
  
• merge (Zusammenführen)
  
• upsert (Aktualisieren und einfügen)
  
• undelete (Löschen rückgängig)
  

Der Auslöser kann einen Apex-Callout nutzen, um einen REST JSON-Aufruf an einen Endpunkt in einer Heroku-Anwendung abzusetzen. Das folgende Beispiel zeigt einen Apex-Auslöser, der eine Heroku-Anwendung aufruft:

 trigger NewContactWebhookTrigger on Contact (after insert) {

  String url = 'https://foo.herokuapp.com/new_contact';

  String content = Webhook.jsonContent(Trigger.new, Trigger.old);

  Webhook.callout(url, content);

} 

Die referenzierte Webhook Apex-Klasse lautet wie folgt:

 public class Webhook {

  public static String jsonContent(List<Object> triggerNew, List<Object> triggerOld) {

    String newObjects = '[]';

    if (triggerNew != null) {

      newObjects = JSON.serialize(triggerNew);

    }

    String oldObjects = '[]';

    if (triggerOld != null) {

      oldObjects = JSON.serialize(triggerOld);

    }

    String userId = JSON.serialize(UserInfo.getUserId());

    String content = '{"new": ' + newObjects + ', "old": ' + oldObjects + ', "userId": ' + userId + '}';

    return content;

  }

  @future(callout=true) public static void callout(String url, String content) {

    Http h = new Http();

    HttpRequest req = new HttpRequest();

    req.setEndpoint(url);

    req.setMethod('POST');

    req.setHeader('Content-Type', 'application/json');

    req.setBody(content);

    h.send(req);

  }

} 

Die jsonContent-Methode nimmt die Auslöserdaten und serialisiert sie in JSON. Die callout-Methode führt den HTTP Post zu Heroku mit der JSON-Nutzlast durch.

Wie bei ausgehenden Nachrichten können Sie die Heroku-Anwendung mit jeder Open Source-Technologie für Web oder REST erstellen. Bei Verwendung von JavaScript, Node.js und Express könnte der Endpunkt definiert werden als:

 app.post("/new_contact", function(req, res) {

  // do something with req.body

  res.status(201).end();

});

Im Anforderungshandler stellt 'req.body' die deserialisierten JSON-Daten dar, die der Apex-Auslöser sendet.

Bei Apex-Auslösern können Sie eine Art vorab freigegebenen Schlüssel verwenden, um Anforderungen zu authentifizieren und dadurch das Risiko böswilliger Anforderungen zu vermeiden. Sie können außerdem festlegen, dass die Nutzlast eine Sitzungs-ID beinhalten muss, damit die Heroku-Anwendung REST-API-Anforderungen an Salesforce stellen darf, um Daten abzurufen oder zu ändern.

Weitere Informationen zu Apex-Callouts finden Sie in der Salesforce-Dokumentation Invoking Callouts Using Apex (Aufrufen von Callouts mithilfe von Apex). Suchen Sie die Heroku-Dokumentation Make Apex and Workflow Callouts to your API (Vornehmen von Apex- und Workflow-Callouts an Ihre API) auf, um mehr über die Apex-Integration mit einem externen Dienst zu erfahren.

Callouts mit ausgehenden Nachrichten

Mit Aktionen des Typs "Ausgehende Nachricht" definieren Sie deklarativ einen Callout an ein externes System und einen durch Datensatz ausgelösten Flow zum Senden des Callouts.

Um bei der Flow-Ausführung eine Heroku-Anwendung aufzurufen, erstellen Sie zuerst eine Aktion des Typs "Ausgehende Nachricht". Geben Sie einen Heroku-Anwendungsendpunkt als Endpunkt-URL an.

Wenn Sie Send Session ID auswählen, kann die Heroku-Anwendung dieses Token verwenden, um REST-API-Aufrufe im Namen des Benutzers durchzuführen. Wenn Sie die Sitzungs-ID nicht senden, kann nicht geprüft werden, ob die Anforderung gültig war oder schädliche Aufrufe an den API-Endpunkt Ihrer Heroku-Anwendung erfolgen.

Heroku-seitig können Sie den Ereignishandler mit jeder Open Source-Technologie für Web oder REST implementieren. Da die Nachricht im SOAP-Format vorliegt, müssen Sie jedoch die XML analysieren können. Mit JavaScript, Node.js, Express und der Bibliothek express-xml-bodyparser haben Sie einen Endpunkt, der eine ausgehende Nachricht verarbeitet und die SOAP-Nachricht analysiert.

app.post("/new_contact", function(req, res) { var notification = req.body["soapenv:envelope"]["soapenv:body"][0]["notifications"][0]; var sessionId = notification["sessionid"][0]; var data = {}; if (notification["notification"] !== undefined) { var sobject = notification["notification"][0]["sobject"][0]; Object.keys(sobject).forEach(function(key) { if (key.indexOf("sf:") == 0) { var newKey = key.substr(3); data[newKey] = sobject[key][0]; } }); // do something #awesome with the data and sessionId } res.status(201).end(); });

In diesem Beispiel erhält die Heroku-Anwendung jedes Mal, wenn ein Kontakt erstellt wird, die Kontaktdetails und kann diese Daten ganz nach Bedarf nutzen.

Nachdem Sie die Aktion "Ausgehende Nachricht" erstellt haben, erstellen Sie den Flow, der sie aufruft. Der Flow kann von einem beliebigen Salesforce-Objekt wie Kontakt oder Account ausgelöst werden, wenn entweder:

• Ein Datensatz erstellt wird
  
• Ein Datensatz aktualisiert wird
  
• Ein Datensatz erstellt oder aktualisiert wird
  
• Ein Datensatz gelöscht wird
  

Wenn Sie den Flow beim Aktualisieren eines Datensatzes auslösen, können Sie angeben, ob der Flow jedes Mal ausgelöst werden soll, wenn der Datensatz aktualisiert wird und die Bedingungsanforderungen erfüllt, oder die Auslösung nur erfolgen soll, wenn der Datensatz aktualisiert wird, um die Bedingungsanforderungen zu erfüllen.

Bei durch Datensatz ausgelösten Flows können Sie Eingangsbedingungen festlegen, die einschränken, welche Datensätze den Flow auslösen. Verwenden Sie diese Funktion, um Kriterien dafür festzulegen, welche Datensätze den Callout senden.

Nachdem Sie das Startelement des Flows konfiguriert haben, erstellen Sie ein Aktionselement. Geben Sie in das Feld "Aktion" die erstellte Aktion des Typs "Ausgehende Nachricht" ein. Geben Sie dann eine Bezeichnung für das Element ein, klicken Sie auf "Fertig" und speichern Sie Ihren Flow. Wenn der Flow dieses Element ausführt, sendet es den Callout, der in der-Aktion "Ausgehende Nachricht" definiert ist.

Flows können auch auf eine Antwort von Heroku warten. Weitere Informationen finden Sie unter Flow-Element: Pause in der Salesforce-Hilfe.

Ressourcen

• SOAP API Developer Guide: Setting Up Outbound Messaging
  
• Salesforce-Hilfe: Aktionen vom Typ "Ausgehende Nachricht"
  
• Salesforce-Hilfe: Flow-Element: Pause
  
• Apex Developer Guide: Invoking HTTP Callouts
  
• Trailhead: Einführung in Node.js auf Heroku
  
• JAMES WARD: Quick Start to Node.js on Heroku