Erfassen Sie Ihre Fortschritte
Trailhead-Startseite
Trailhead-Startseite

Verwenden der Streaming-API

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:
  • Beschreiben des Hauptvorteils der Push-Technologie gegenüber der Pull-Technologie
  • Erstellen eines PushTopic und Empfangen von Ereignisbenachrichtigungen
  • Definieren eines Plattformereignisses und Ableiten des Abonnementkanals
  • Bekanntmachen einer Nachricht mit allgemeinem Streaming
  • Festlegen von Wiedergabeoptionen für dauerhaftes Streaming

Streamen von Ereignissen

Zum Abschluss unserer Entdeckungsreise durch die Daten-APIs von Salesforce sehen wir uns eine API an, die einen ganz anderen Verwendungszweck hat. Mit der Streaming-API können Sie per Push-Übertragung Benachrichtigungen als Stream von Salesforce an Clientanwendungen senden. Die Übertragung basiert dabei auf Kriterien, die Sie selbst definieren. Wie unterscheidet sich die Push-Übertragung von Benachrichtigungen vom Pull-Paradigma unserer anderen APIs, bei dem die Clientanwendung Daten von Salesforce anfordert (Pull)? Lassen Sie uns diese Fragestellung aus der Sicht des Schiffskapitäns betrachten.

Stellen Sie sich vor, Sie segeln über den weiten Ozean und möchten frühzeitig über lauernde Gefahren, andere Schiffe und Schatzinseln informiert werden. Sie schicken daher einen Matrosen als Aussichtsposten in den Ausguck. Kehren Sie jetzt wieder in die Welt der Entwickler zurück. Angenommen, Sie schreiben mit der REST- oder SOAP-API eine Anwendung, die regelmäßig prüft, ob Accounts geändert wurden. Auch hier können Sie einen "Aussichtsposten" einrichten, indem Sie Accountdaten kontinuierlich anfordern und prüfen, ob sie mit den alten Daten übereinstimmen.

Stellen Sie sich jetzt vor, Sie wären wieder auf Ihrem Schiff und hätten eine nagelneue Radaranzeige zur Verfügung. In diesem Fall ist der Matrose im Ausguck unnötig, da die Radaranzeige einen Signalton ausgibt, sobald ein interessantes Objekt in die Nähe kommt.

Die Streaming-API ist quasi Ihr Radar. Mit dieser API können Sie Ereignisse definieren und Benachrichtigungen per Push-Verfahren an Ihre Clientanwendung senden, sobald Ereignisse auftreten. Sie müssen nicht aktiv auf Datenänderungen prüfen und nicht ständig Salesforce abfragen und unnötige API-Anforderungen senden.

Die Streaming-API kann wie ein Radargerät zum Erkennen von Datenänderungen und Senden von Benachrichtigungen eingesetzt werden

Die Nachverfolgung von Datenänderungen in Salesforce ist besonders nützlich, wenn Geschäftsdaten in einem System außerhalb von Salesforce gespeichert werden. Mit der Streaming-API können Sie mithilfe von PushTopic- und Datenänderungserfassungs-Ereignissen dafür sorgen, dass Ihre externe Quelle mit Ihren Salesforce-Daten synchron ist. Die Streaming-API ermöglicht Ihnen zudem, in Reaktion auf Datenänderungen in Salesforce Geschäftslogik in einem externen System zu verarbeiten. Sie können die Streaming-API beispielsweise dazu verwenden, ein Fulfillment Center zu benachrichtigen, sobald eine Opportunity aktualisiert wird.

Hinweis

Hinweis

Weitere Informationen über die Datenänderungserfassung finden Sie im Trailhead-Modul Datenänderungserfassung – Grundlagen.

Zusätzlich zu Datenänderungen können Sie die Streaming-API auch zum Übertragen benutzerdefinierter Benachrichtigungen zu Plattformereignissen und für allgemeines Streaming verwenden. So kann eine Anwendung beispielsweise Benachrichtigungen zu Plattformereignissen für Aufträge erstellen, die von einem Auftragserfüllungsservice verarbeitet werden. Eine Anwendung könnte auch generische Ereignisse erfassen und eine Meldung anzuzeigen, wenn demnächst ein Zeitfenster für die Systemwartung beginnt oder ein neues Angebot für Benutzer verfügbar ist.

PushTopics

Ein PushTopic ist ein sObject, das die Kriterien der Ereignisse enthält, auf die geprüft werden soll, wie etwa Datenänderungen an einem bestimmten Objekt. Sie definieren die Kriterien als SOQL-Abfrage im PushTopic und geben die Datensatzvorgänge an, zu denen Benachrichtigungen gesendet werden sollen (erstellen, aktualisieren, löschen und wiederherstellen). Zusätzlich zu den Ereigniskriterien stellt ein PushTopic auch den Kanal dar, den Clientanwendungen abonnieren.

Dazu erfahren Sie mehr, wenn wir ein eigenes PushTopic erstellen.

Unterstützte Objekte in PushTopic-Abfragen

PushTopic-Abfragen unterstützen alle benutzerdefinierten Objekte und einige gängige Standardobjekte wie Account, Kontakt und Opportunity. Eine vollständige Liste unterstützter Standardobjekte finden Sie im Streaming API Developer Guide, der im Abschnitt "Ressourcen" genannt ist.

PushTopics und Benachrichtigungen

Mit einem PushTopic können Sie die Objekte, Felder und Kriterien definieren, zu denen Sie Ereignisbenachrichtigungen erhalten möchten. Das folgende Beispiel zeigt, wie Sie ein PushTopic in Apex definieren und einfügen. Nach der Erstellung dieses PushTopic können Sie diesen PushTopic-Kanal abonnieren, um Änderungen an Accounts nachzuverfolgen, bei denen die Stadt der Rechnungsanschrift San Francisco lautet. Dieses PushTopic gibt an, dass die Felder für ID, Name und Telefon in jeder Benachrichtigung angegeben werden. Standardmäßig werden Benachrichtigungen für Erstellungs-, Aktualisierungs-, Lösch- und Wiederherstellungsvorgänge gesendet, die den Abfragekriterien entsprechen.
PushTopic pushTopic = new PushTopic();
pushTopic.Name = 'AccountUpdates';
pushTopic.Query = 'SELECT Id, Name, Phone FROM Account WHERE BillingCity=\'San Francisco\'';
pushTopic.ApiVersion = 37.0;
insert pushTopic;

Definieren Sie mindestens Name, Abfrage und API-Version des PushTopic. Für die restlichen Eigenschaften können Sie Standardwerte verwenden. Standardmäßig sind die Felder in der Feldliste der SELECT-Anweisung und der WHERE-Klausel die Felder, die Benachrichtigungen auslösen. Benachrichtigungen werden nur für die Datensätze gesendet, die die Kriterien in der WHERE-Klausel erfüllen. Benachrichtigungen beinhalten die Felder aus der SELECT-Klausel. Wenn Sie ändern möchten, welche Felder Benachrichtigungen auslösen, legen Sie pushTopic.NotifyForFields auf einen dieser Werte fest.

Wert NotifyForFields
Beschreibung
Alle
Benachrichtigungen werden für alle Änderungen an Datensatzfeldern gesendet, vorausgesetzt, die bewerteten Datensätze stimmen mit den in der WHERE-Klausel festgelegten Kriterien überein.
Referenced (Standard)
Änderungen an Feldern, die in der SELECT- und der WHERE-Klausel referenziert werden, werden bewertet. Benachrichtigungen werden für die bewerteten Datensätze nur gesendet, wenn sie die in der WHERE-Klausel festgelegten Kriterien erfüllen.
Sie können Folgendes auswählen:
Änderungen an Feldern, die in der SELECT-Klausel referenziert werden, werden bewertet. Benachrichtigungen werden für die bewerteten Datensätze nur gesendet, wenn sie die in der WHERE-Klausel festgelegten Kriterien erfüllen.
Ort
Änderungen an Feldern, die in der WHERE-Klausel referenziert werden, werden bewertet. Benachrichtigungen werden für die bewerteten Datensätze nur gesendet, wenn sie die in der WHERE-Klausel festgelegten Kriterien erfüllen.
Wenn Sie Benachrichtigungseinstellungen explizit festlegen möchten, legen Sie die folgenden Eigenschaften auf "true" oder "false" fest. Standardmäßig sind alle Werte auf "true" festgelegt.
pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;

Beim Erstellen eines Accounts wird eine Ereignisbenachrichtigung erstellt. Die Benachrichtigung liegt in JSON-Format vor und enthält die Felder, die wir in der PushTopic-Abfrage festgelegt haben: Id, Name und Telefon. Die Ereignisbenachrichtigung sollte etwa so aussehen:

{
  "clientId": "lxdl9o32njygi1gj47kgfaga4k",
  "data": {
    "event": {
      "createdDate": "2016-09-16T19:45:27.454Z",
      "replayId": 1,
      "type": "created"
    },
    "sobject": {
      "Phone": "(415) 555-1212",
      "Id": "001D000000KneakIAB",
      "Name": "Blackbeard"
    }
  },
  "channel": "/topic/AccountUpdates"
}

Der Benachrichtigungstext enthält den Kanal für das PushTopic, dessen Namensformat /topic/PushTopicName lautet. Bei der Erstellung eines PushTopic wird der Kanal automatisch erstellt.

PushTopic-Abfragen

Nehmen wir uns einen Augenblick Zeit, um uns die Abfrage genauer anzusehen, die wir gerade für unser PushTopic definiert haben. PushTopic-Abfragen sind normale SOQL-Abfragen. Wenn Sie also mit SOQL vertraut sind, ist Ihnen das Format bereits bekannt. Das Format der Abfrage lautet:
SELECT <comma-separated list of fields> FROM <Salesforce object> WHERE <filter criteria>

Damit sichergestellt wird, dass Benachrichtigungen zeitnah versendet werden, gelten folgende Bedingungen für PushTopic-Abfragen.

  • Die Feldliste der SELECT-Anweisung muss das Feld "Id" enthalten.
  • Es ist nur ein Objekt pro Abfrage zulässig.
  • Das Objekt muss für die angegebene API-Version gültig sein.
Bestimmte Abfragen, wie z. B. aggregierte Abfragen oder Semi-Joins werden nicht unterstützt.

Benutzerdefinierte Benachrichtigungen zu Plattformereignissen

Verwenden Sie Plattformereignisse, um benutzerdefinierte Benachrichtigungen mit einem vordefinierten Schema zu veröffentlichen und zu abonnieren. Im Gegensatz zu PushTopic- und Datenänderungserfassungs-Ereignissen sind Plattformereignisse nicht an Salesforce-Datensätze gebunden und werden nicht automatisch von Salesforce veröffentlicht. Stattdessen definieren Sie das Schema einer Plattformereignisnachricht, indem Sie ein Plattformereignis erstellen und Felder hinzufügen. Außerdem veröffentlichen Clients Plattformereignisse mit deklarativen Tools auf der Lightning-Plattform, Apex oder APIs.

Das versionierte Schema eines Plattformereignisses ermöglicht es Abonnenten, Ereignisse deterministisch zu analysieren. Jede Schemaversion entspricht einer eindeutigen Schema-ID, die in der Ereignisbenachrichtigung enthalten ist.

Definieren eines Plattformereignisses

Zum Definieren eines Plattformereignisses in der Benutzeroberfläche geben Sie in Setup den Text "Plattformereignisse" in das Feld "Schnellsuche" ein und wählen dann Plattformereignisse aus. Das Hinzufügen von Feldern zu einem Plattformereignis ist ähnlich wie das Hinzufügen von Feldern zu einem benutzerdefinierten Objekt. Es wird eine Teilmenge der Feldtypen unterstützt.

Der API-Name eines Plattformereignisses enthält das Suffix __e. Wenn Sie beispielsweise ein Plattformereignis mit der Bezeichnung "Order Event" erstellen, lautet der API-Name Order_Event__e.

Wenn Sie ein Plattformereignis definieren, wird automatisch ein Kanalname vergeben. Der Kanalname basiert auf dem API-Namen des Ereignisses und hat das Format /event/Ereignisname. Beispiel: /event/Order_Event__e.

Veröffentlichen von Plattformereignissen

Sie können Plattformereignisse mit diesen deklarativen oder programmgesteuerten Tools in der Lightning-Plattform veröffentlichen:

  • Prozessgenerator und Aktion "Datensatz erstellen"
  • Flow mit einem Element des Typs "Datensatzerstellung"
  • Apex-Methode EventBus.publish()
  • REST API-Ressource sobjects
  • SOAP API-Aufruf create()

Weitere Einzelheiten finden Sie in der Dokumentation zu Plattformereignissen im Abschnitt "Ressourcen".

Subscribing to Platform Events

Die Streaming-API stellt den Abonnementmechanismus für mehrere Ereignistypen bereit, Plattformereignisse eingeschlossen. Neben der Streaming-API können Sie Plattformereignisse auch mithilfe der Lightning-Plattform abonnieren.

  • Mit dem Prozessgenerator und einem Prozess, der beim Auftreten eines Plattformereignisses startet
  • Mit einem Flow, der wartet, bis ein Plattformereignis eintritt
  • Apex-Auslöser
  • Mit der Streaming-API unter Verwendung der Messaging-Bibliothek CometD
  • Die Lightning-Komponente empApi

Dieses Beispiel ist eine Plattformereignisnachricht für das Bestellereignis (Order Event).

{
  "data": {
    "schema": "dffQ2QLzDNHqwB8_sHMxdA",
    "payload": {
      "CreatedDate": "2018-08-22T12:11:40.517Z",
      "CreatedById": "005D0000001cSZs",
      "Order_Number__c": "12345",
      "Has_Shipped__c": true
    },
    "event": {
      "replayId": 1
    }
  },
  "channel": "/event/Order_Event__e"
}

Weitere Einzelheiten finden Sie in der Dokumentation zu Plattformereignissen im Abschnitt "Ressourcen".

Benutzerdefinierte Benachrichtigungen mit allgemeinem Streaming

Bevor Sie alleine in See stechen können, sollten wir uns noch kurz dem allgemeinen Streaming zuwenden. Die Streaming-API unterstützt das Senden von Benachrichtigungen mit einer allgemeinen Nutzlast, die nicht an Salesforce-Datenänderungen gebunden sind.
Nutzen Sie allgemeines Streaming, um benutzerdefinierte Benachrichtigungen mit beliebigen Nutzlasten und ohne vordefiniertes Schema zu senden und zu empfangen. Allgemeines Streaming ermöglicht Ihnen, Benachrichtigungen gezielt für eine Benutzergruppe zu veröffentlichen. Damit Sie das allgemeine Streaming nutzen können, ist Folgendes erforderlich:
  • Ein Streaming-Kanal, der den Kanal definiert
  • Ein oder mehrere Clients, die den Kanal abonnieren
  • Die Ressource "Streaming Channel Push", um Ereignisse im Kanal zu überwachen und aufzurufen
Sie können einen Streaming-Kanal für das allgemeine Streaming entweder über die Anwendung "Streaming-Kanäle" der Benutzeroberfläche oder über die API erstellen. Ein Streaming-Kanal wird durch das sObject StreamingChannel dargestellt, Sie können ihn also über Apex, REST-API oder SOAP-API erstellen. Das Format des Kanalnamens für allgemeines Streaming ist /u/Kanalname. Dieser Apex-Codeausschnitt erstellt beispielsweise einen Kanal namens "Broadcast".
StreamingChannel ch = new StreamingChannel();
ch.Name = '/u/Broadcast';
insert ch;

Sie können sich alternativ auch dafür entscheiden, dass Salesforce den Streaming-Kanal dynamisch für Sie erstellt, falls er noch nicht vorhanden ist. Zum Aktivieren dynamischer Streaming-Kanäle in Ihrer Organisation geben Sie in Setup in das Feld Schnellsuche den Text "Benutzeroberfläche" ein und wählen dann Benutzeroberfläche aus. Wählen Sie auf der Seite "Benutzeroberfläche" die Option Dynamische Streaming-Kanal-Erstellung aktivieren aus.

Sie können den Kanal mit einem CometD-Client abonnieren. (Der Abschnitt "Ressourcen" enthält einen Link zu einer Beispielanleitung im Streaming API Developer Guide.)

Zum Erzeugen von Ereignissen senden Sie eine POST-Anforderung an dieselbe REST-Ressource. Ersetzen Sie XX.0 durch die API-Version und "Streaming-Kanal-ID" durch die ID Ihres Kanals.

/services/data/vXX.0/sobjects/StreamingChannel/Streaming Channel ID/push
Hinweis

Hinweis

Zum Ermitteln Ihrer Kanal-ID führen Sie eine SOQL-Abfrage nach StreamingChannel aus. Zum Beispiel: SELECT Id, Name FROM StreamingChannel

Beispiel für den REST-Anforderungstextkörper.

{
  "pushEvents": [
      {
          "payload": "Broadcast message to all subscribers",
          "userIds": []
      }
   ]
}
Hinweis

Hinweis

Anstatt Nachrichten an alle Abonnenten zu senden, geben Sie mithilfe des optionalen Felds "userIds" eine Liste abonnierter Benutzer an, an die Benachrichtigungen gesendet werden sollen. Sie können auch die GET-Methode der REST-API-Push-Ressource für den Streaming-Kanal verwenden, um eine Liste der aktiven Abonnenten des Kanals abzurufen.

Die Ereignisbenachrichtigung, die der abonnierte Client erhält, sollte etwa wie folgt aussehen.

{
  "clientId": "1p145y6g3x3nmnlodd7v9nhi4k",
  "data": {
    "payload": "Broadcast message to all subscribers",
    "event": {
      "createdDate": "2016-09-16T20:43:39.392Z",
      "replayId": 1
    }
  },
  "channel": "/u/Broadcast"
}

Beachten Sie, dass diese Ereignisbenachrichtigung das Feld replayID enthält. 

Dank Ereignisbenachrichtigungen können Sie jetzt zuversichtlich in See stechen und Ihre Schatzinsel suchen!

Abrufen in der Vergangenheit liegender Benachrichtigungen mit dauerhaftem Streaming

Bis jetzt haben Sie die verschiedenen Arten von Ereignissen kennengelernt. Was passiert, wenn ein Salesforce-Datensatz erstellt oder eine benutzerdefinierte Benachrichtigung erzeugt wird, bevor ein Client einen Ereigniskanal abonniert bzw., während ein Client nicht verbunden ist? Vor der API-Version 37.0 hätte der Client die entsprechende Benachrichtigung verpasst. Ab API-Version 37.0 speichert Salesforce PushTopic-Ereignisse, generische Ereignisse und Plattformereignisse mit Standardvolumen 24 Stunden und Ereignisse mit hohem Volumen 72 Stunden. Sie können die Ereignisnachrichten in diesem Zeitfenster jederzeit abrufen. Prima!

Ab API-Version 37.0 enthält jede Ereignisbenachrichtigung ein Feld namens ReplayId. Vergleichbar mit der Videowiedergabe gibt Streaming API die gesendeten Ereignisbenachrichtigungen mit dem Feld ReplayId wieder.

Jeder Ereignisnachricht wird eine undurchsichtige ID zugeordnet, die im Feld "ReplayId enthalten ist. Der Feldwert "ReplayId", der vom System eingetragen wird, wenn das Ereignis an Abonnenten gesendet wird, bezieht sich auf die Position des Ereignisses im Ereignis-Stream. "Replay ID"-Werte sind bei aufeinander folgenden Ereignissen nicht unbedingt fortlaufend. So kann beispielsweise das Ereignis, das auf das Ereignis mit der ID 999 folgt, die ID 1025 haben. Ein Abonnent kann einen Wiedergabe-ID-Wert speichern und beim erneuten Abonnement für den Abruf von Ereignissen verwenden, die innerhalb des Zeitfensters für die Speicherung liegen. Abonnenten können so beispielsweise verpasste Ereignisse nach einem Verbindungsfehler abrufen. Abonnenten dürfen keine neuen Wiedergabe-IDs auf der Grundlage einer gespeicherte Wiedergabe-ID berechnen, um auf andere Ereignisse im Stream zu verweisen.

Tabelle 1 Wiedergabeoptionen
Wiedergabeoption
Beschreibung
Verwendung
Wiedergabe-ID
Abonnent empfängt alle gespeicherten Ereignisse, die nach dem mit seinem replayId-Wert angegebenen Ereignis stattfinden, und neue Ereignisse.
Informieren Sie sich über verpasste Ereignisse nach einer bestimmten Ereignismeldung, z. B. nach einem Verbindungsabbruch. Um Ereignisse mit einer bestimmten Wiedergabe-ID zu abonnieren, speichern Sie die Wiedergabe-ID der Ereignismeldung, nach der Sie gespeicherte Ereignisse abrufen möchten. Verwenden Sie dann diese Wiedergabe-ID, wenn Sie erneut abonnieren.
-1
Abonnent empfängt neue Ereignisse, die nach dem Abonnementzeitpunkt des Client übertragen werden.
Wir empfehlen Clients das Abonnement mit der Option -1, um neue Ereignisnachrichten zu empfangen. Benötigen Clients frühere Ereignisnachrichten, können sie eine der anderen Wiedergabeoptionen verwenden.
-2
Abonnent empfängt alle Ereignisse, einschließlich vergangener Ereignisse, die innerhalb des Zeitfensters für die Speicherung der Benachrichtigungen liegen, sowie neuer Ereignisse.
Informieren Sie sich über verpasste Ereignisse und rufen Sie alle gespeicherten Ereignisse ab, z. B. nach einem Verbindungsabbruch. Diese Option sollten Sie nur selten verwenden. Ein Abonnement mit der Option -2 kann die Performance herabsetzen, wenn eine große Anzahl von Ereignisnachrichten gespeichert wurden.

Die folgende Abbildung zeigt, wie Ereignisnutzer einen Ereignis-Stream bei der Festlegung verschiedener Wiedergabeoptionen lesen können.

Streaming von Ereignissen mit Wiedergabeoptionen