Definieren und Veröffentlichen von Plattformereignissen

Lernziele

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

Definieren eines Plattformereignisses
Beschreiben, wie Plattformereignisnachrichten in Apex veröffentlicht werden können
Veröffentlichen eines Ereignisses mithilfe einer Apex-Methode
Veröffentlichen eines Ereignisses mithilfe von Klicks in einem Prozess oder Flow
Veröffentlichen eines Ereignisses mithilfe der REST-API durch Einfügen eines sObjects

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

Definieren und Veröffentlichen von Plattformereignissen

Sie wissen nun, was Plattformereignisse sind und wann sie verwendet werden. Gehen wir nun das Definieren eines Plattformereignisses praktisch an! Erinnern Sie sich noch an die Agentur Cloud News? Lassen Sie uns eine Definition eines Plattformereignisses erstellen, die die Daten von Nachrichtenereignissen enthält.

Definieren Sie ein Plattformereignis namens "Cloud News":

Geben Sie unter Setup im Feld "Schnellsuche" den Text "Plattformereignisse" ein und wählen Sie dann Plattformereignisse aus.
Klicken Sie auf der Seite "Plattformereignisse" auf Neues Plattformereignis.
Geben Sie "Cloud News" in "Bezeichnung" ein.
Geben Sie "Cloud News" in "Bezeichnung - Plural" ein.
Geben Sie "Cloud news events deliver news at your fingertips" in "Beschreibung" ein.
Behalten Sie für "Veröffentlichungsverhalten" die Standardeinstellung Nach Commit veröffentlichen bei.
Klicken Sie auf Speichern.
Klicken Sie in der Themenliste "Benutzerdefinierte Felder & Beziehungen" auf Neu.
Wählen Sie Text und klicken Sie auf Weiter.
Geben Sie "Location" in "Feldbezeichnung/-name" ein.
Geben Sie in "Länge" 100 ein. Übernehmen Sie die Standardeinstellungen für die anderen Felder und lassen Sie das Feld "Beschreibung" frei. Klicken Sie auf Speichern.
Führen Sie die Schritte 7-9 aus, um die nächsten beiden Felder hinzuzufügen:

Feldbezeichnung/-name	Feldtyp
Dringend	Kontrollkästchen
News Content	Textfeld (Lang)

Sie haben für das zuvor definierte Ereignis "Cloud News" Felder verschiedener Typen erstellt, z. B. ein Textfeld und ein Kontrollkästchen. Plattformereignisse unterstützen die folgenden Feldtypen:

Kontrollkästchen
Datum
Datum/Uhrzeit
Zahl
Text
Textfeld (Lang)

Ereignisspeicherung und das Systemfeld "ReplayId"

Salesforce speichert Plattformereignisse mit hohem Volumen 72 Stunden im Ereignisbus Ereignisse mit Standardvolumen, die vor Version Spring '19 definiert wurden, werden 24 Stunden im Ereignisbus gespeichert

Neu definierte Ereignisse haben standardmäßig ein hohes Volumen. Ereignisse mit Standardvolumen sind die Vorgänger von Ereignissen mit hohem Volumen und können nicht länger definiert werden.

Mit der Pub/Sub-API können Sie gespeicherte Ereignisse aus dem Ereignisbus abrufen. Sie können alle gespeicherten Ereignisse abrufen oder die Wiedergabe-ID eines Ereignisses als Basis für den abgerufenen Teil von Ereignissen angeben. Mit Apex-Auslösern können Sie einen angehaltenen Auslöser fortsetzen und die frühesten zurückbehaltenen unverarbeiteten Ereignisse auswählen. Im weiteren Verlauf dieses Moduls lernen Sie, wie Sie Abonnements von Apex-Auslösern verwalten.

Auch wenn Salesforce Ereignisnachrichten vorübergehend speichert, können Sie diese nicht mithilfe von SOQL oder SOSL abfragen. Außerdem können Sie Ereignisnachrichten nicht auf der Benutzeroberfläche in Berichten, Listenansichten und Suchvorgängen verwenden.

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

API-Namenssuffix

Wenn Sie ein Plattformereignis erstellen, fügt das System zum Erstellen des API-Namens des Ereignisses das Suffix "__e" an. Für das Ereignis "Cloud News" lautet der API-Name beispielsweise "Cloud_News__e". Verwenden Sie den API-Namen, wenn Sie z. B. in Apex, über die REST-API oder die Pub/Sub-API programmgesteuert auf das Ereignis verweisen.

Plattformereignisse und Transaktionen

Plattformereignisse, die mit dem Veröffentlichungsverhalten Nach Commit veröffentlichen definiert sind, sind transaktional und können zurückgesetzt werden. Diejenigen, die mit dem Verhalten Sofort veröffentlichen definiert sind, sind dies jedoch nicht und können nicht zurückgesetzt werden. Beachten Sie folgende Verhaltensunterschiede.

Veröffentlichungsverhalten "Nach Commit veröffentlichen"

Ein Plattformereignis, das mit dem Verhalten Nach Commit veröffentlichen definiert ist, wird erst veröffentlicht, wenn für die Transaktion ein Commit erfolgt ist. Definieren Sie ein Ereignis mit dieser Option, wenn Abonnenten auf Daten angewiesen sind, für die Veröffentlichungstransaktion einen Commit ausführt. Ein Prozess veröffentlicht beispielsweise eine Ereignisnachricht und erstellt einen Aufgabendatensatz. Ein zweiter Prozess, der für das Ereignis abonniert ist, wird ausgelöst und erwartet, den Aufgabendatensatz vorzufinden. Ein weiterer Grund für die Wahl dieses Verhaltens ist, wenn Sie nicht möchten, dass die Ereignisnachricht veröffentlicht wird, falls die Transaktion fehlschlägt.

Veröffentlichungsverhalten "Sofort veröffentlichen"

Ein Plattformereignis, das mit dem Verhalten Sofort veröffentlichen definiert ist, wird veröffentlicht, wenn der Veröffentlichungsaufruf erfolgt. Wählen Sie diese Option, wenn die Ereignisnachricht unabhängig vom Erfolg der Transaktion veröffentlicht werden soll. Wählen Sie diese Option auch, wenn der Publisher und die Abonnenten unabhängig sind und sich die Abonnenten nicht auf Daten verlassen, für die der Publisher einen Commit ausgeführt hat. So ist beispielsweise das Verhalten der sofortigen Veröffentlichung für ein Ereignis geeignet, das zu Protokollierungszwecken verwendet wird. Mit dieser Option kann ein Abonnent die Ereignisnachricht erhalten, bevor für Daten von der Publisher-Transaktion ein Commit ausgeführt wird.

Veröffentlichen von Ereignissen

Wenn sich Ihre Anwendung auf der Salesforce-Plattform befindet, können Sie Ereignisse mithilfe einer Apex-Methode oder dem deklarativen Tool Flow Builder veröffentlichen. Wenn Sie über eine externe Anwendung verfügen, können Sie Ereignisse mithilfe von Salesforce-APIs veröffentlichen, zu denen auch die Pub/Sub-API und die Daten-APIs wie die REST-API gehören.

Veröffentlichen von Ereignisnachrichten mithilfe von Apex

Zum Veröffentlichen von Ereignisnachrichten erstellen Sie eine Instanz des Ereignisses und übergeben sie an die EventBus.publish-Methode.

Das folgende Beispiel erstellt ein Ereignis des Typs Cloud_News__e, veröffentlicht es und prüft anschließend, ob die Veröffentlichung erfolgreich war oder Fehler aufgetreten sind. Die EventBus.publish()-Methode gibt ein Database.SaveResult-Objekt zurück, welches das Ergebnis der Veröffentlichung enthält. Wenn isSuccess() den Wert true zurückgibt, wird die Anforderung zum Veröffentlichen in Salesforce in eine Warteschlange gestellt und die Ereignisnachricht asynchron veröffentlicht. Wenn isSuccess() den Wert false zurückgibt, führte der Vorgang der Ereignisveröffentlichung zu Fehlern, die im Database.Error-Objekt zurückgegeben werden. Diese Methode löst aufgrund eines erfolglosen Veröffentlichungsvorgangs keine Ausnahme aus.

Sie können den Apex-Codeausschnitt in der Developer Console ausführen.

Wählen Sie im Schnellzugriffsmenü () Developer Console aus.
Klicken Sie auf Debug | Open Execute Anonymous Window (Debuggen | Fenster für die anonyme Ausführung öffnen).

Fügen Sie in dem neuen Fenster Folgendes hinzu und klicken Sie dann auf Execute (Ausführen).

// Create an instance of the event and store it in the newsEvent variable
Cloud_News__e newsEvent = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=true,
           News_Content__c='Lake Road is closed due to mudslides.');
// Call method to publish events
Database.SaveResult sr = EventBus.publish(newsEvent);
// Inspect publishing result
if (sr.isSuccess()) {
    System.debug('Successfully published event.');
} else {
    for(Database.Error err : sr.getErrors()) {
        System.debug('Error returned: ' +
                     err.getStatusCode() +
                     ' - ' +
                     err.getMessage());
    }
}

Um mehrere Ereignisse im selben Aufruf zu veröffentlichen, fügen Sie Ihre Ereignisse einer Ereignisliste hinzu und übergeben die Liste an die EventBus.publish()-Methode. Die Ausgabe dieser Methode ist ein Array von Database.SaveResult-Objekten, je eines für jedes veröffentlichte Ereignis. EventBus.publish() kann selbst dann bestimmte übergebene Ereignisse veröffentlichen, wenn andere Ereignisse aufgrund von Fehlern nicht veröffentlicht werden können. Die Methode EventBus.publish() löst keine Ausnahmen aus, die von einem nicht erfolgreichen Veröffentlichungsvorgang verursacht wurden. Dieses Verhalten ähnelt dem der Apex Database.insert()-Methode beim Aufruf mit der Option für Teilerfolg.

// List to hold event objects to be published.
List<Cloud_News__e> newsEventList = new List<Cloud_News__e>();
// Create event objects.
Cloud_News__e newsEvent1 = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=true,
           News_Content__c='Lake Road is closed due to mudslides.');
Cloud_News__e newsEvent2 = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=false,
           News_Content__c='Small incident on Goat Lane causing traffic.');
// Add event objects to the list.
newsEventList.add(newsEvent1);
newsEventList.add(newsEvent2);
// Call method to publish events.
List<Database.SaveResult> results = EventBus.publish(newsEventList);
// Inspect publishing result for each event
for (Database.SaveResult sr : results) {
    if (sr.isSuccess()) {
        System.debug('Successfully published event.');
    } else {
        for(Database.Error err : sr.getErrors()) {
            System.debug('Error returned: ' +
                        err.getStatusCode() +
                        ' - ' +
                        err.getMessage());
        }
    }
}

Wenn Systemressourcen verfügbar werden, veröffentlicht Salesforce die in eine Warteschlange gestellten Ereignisse aus dem EventBus.publish()-Aufruf asynchron und speichert sie für eine spezifische Aufbewahrungsfrist im Ereignisbus. In den meisten Fällen müssen Sie sich keine Gedanken über das Endergebnis der Veröffentlichung von Ereignissen in der Warteschlange machen, da die letztendliche Veröffentlichung erfolgreich ist. In seltenen Fällen kann ein interner Systemfehler auftreten und zum Fehlschlagen der asynchronen Veröffentlichung führen. Wenn Sie eine Bestätigung zum Endergebnis der Ereignisveröffentlichung erhalten möchten, verwenden Sie Apex-Veröffentlichungsrückmeldungen. Weitere Informationen finden Sie unter Get the Result of Asynchronous Platform Event Publishing with Apex Publish Callbacks im Platform Events Developer Guide.

Die Salesforce-Plattform bietet Zuteilungen für die Anzahl der Ereignisse, die Sie in Ihrer Organisation definieren können und der Ereignisse, die Sie pro Stunde veröffentlichen können. Für Ereignisse, die mit dem Verhalten "Nach Commit veröffentlichen" konfiguriert sind, wird jede Ausführung einer Methode als eine DML-Anweisung auf den Apex-Grenzwert für DML-Anweisungen angerechnet. Sie können die Ausschöpfung des Grenzwerts mit der Apex-Methode Limits.getDMLStatements() überprüfen. Für Ereignisse, die mit dem Verhalten "Sofort veröffentlichen" konfiguriert sind, wird jede Ausführung einer Methode auf einen separaten Grenzwert für die Veröffentlichung von Ereignissen von 150 Aufrufen von EventBus.publish() angerechnet. Sie können die Ausschöpfung des Grenzwerts mit der Apex-Methode Limits.getPublishImmediateDML() überprüfen. Weitere Informationen finden Sie im Abschnitt "Ressourcen".

Veröffentlichen von Ereignisnachrichten mithilfe von Klicks

Um Ereignisnachrichten ohne Programmieren zu veröffentlichen, verwenden Sie die Funktionen zur Datensatzerstellung in Flow Builder. Konfigurieren Sie das Element "Datensatzerstellung", um eine Instanz des Plattformereignisses (Cloud_News__e) zu erstellen, und legen Sie dann die Werte für das Ereignis fest. Um den Wert eines booleschen Felds wie Urgent__c festzulegen, verwenden Sie {!$GlobalConstant.True}.

Veröffentlichen von Ereignisnachrichten mithilfe von Salesforce-APIs

Externe Anwendungen nutzen eine API zum Veröffentlichen von Plattformereignisnachrichten. Sie können Ereignisse mithilfe der Pub/Sub-API oder mit Daten-APIs wie SOAP-API, REST-API oder Bulk-API veröffentlichen.

Bei der Verwendung von Daten-APIs veröffentlichen Sie Ereignisse auf dieselbe Weise, in der Sie sObjects einfügen. Wie in Apex wird die Ereignisnachricht asynchron veröffentlicht. Wenn Sie ein Ereignis veröffentlichen und den Erfolgsstatus true erhalten, wird die Veröffentlichungsanforderung in Salesforce in eine Warteschlange gestellt.

Für das Ereignis "Cloud News" können Sie z. B. Ereignisbenachrichtigungen veröffentlichen, indem Sie Cloud_News__e-Datensätze einfügen. Im folgenden Beispiel wird in der REST-API ein Ereignis des Typs Cloud_News__e erstellt.

REST-Endpunkt des sObjects:

Anforderungstext einer POST-Anforderung:

Nach Erstellen der Plattformereignisnachricht sieht die REST-Antwort wie in dieser Ausgabe aus.

Sie können ein beliebiges REST-API-Tool oder eine HTTP-Clientanwendung verwenden, um die REST-API aufzurufen. Sie können z. B. Postman verwenden, indem Sie die folgenden Schritte ausführen. Wenn Sie noch nicht mit Postman vertraut sind, arbeiten Sie am besten das Projekt Schnelleinstieg: Verbinden von Postman mit Salesforce durch, um die Sammlung von Salesforce-APIs einzurichten und zu forken. Weitere Informationen zu Postman finden Sie im Abschnitt "Ressourcen".

Verbinden Sie Ihre Developer Edition-Organisation mit Postman.

Melden Sie sich bei Ihrer Trailhead Developer Edition-Organisation an.
Öffnen Sie die Anwendung Postman, wählen Sie einen Arbeitsbereich aus und navigieren Sie zu Ihrem Fork der Salesforce-API-Sammlung.
Blättern Sie auf der Registerkarte "Authorization" (Autorisierung) ganz nach unten und klicken Sie auf Get New Access Token (Neues Zugriffstoken beziehen).
Klicken Sie auf Allow (Zulassen).
Kopieren Sie im Dialog "Manage Access Tokens" (Zugriffstoken verwalten) den Instanz-URL in die Zwischenablage.
Klicken Sie auf Use Token (Token verwenden).
Fügen Sie auf der Registerkarte "Variables" (Variablen) in der Zeile "_endpoint" (Endpunkt) in der Spalte CURRENT VALUE (Aktueller Wert) den URL der Instanz ein, den Sie gerade kopiert haben, und klicken Sie dann auf Save (Speichern). Möglicherweise müssen Sie den Dokumentationsbereich schließen, um die Schaltfläche "Save" (Speichern) zu sehen.
Testen Sie, ob Ihre Verbindung funktioniert.

Wählen Sie in "Collections" (Sammlungen) Ihren Fork der Salesforce-API-Sammlung aus.
Wählen Sie REST aus, um die REST-APIs aufzuklappen.
Wählen Sie GET Limits aus und klicken Sie dann auf Send (Senden).
Im Antwortfenster sollte das Feld "Status" wie folgt angezeigt werden. Status: 200 OK. Falls nicht, wiederholen Sie die Schritte, um ein neues Token zu beziehen.

Rufen Sie eine REST-API auf, um Ereignisbenachrichtigungen zu veröffentlichen.

Klicken Sie in Ihrem Fork der Salesforce-API-Sammlung auf REST.
Klicken Sie auf SObjects, um die Option aufzuklappen.
Klicken Sie auf POST SObject Create.
Geben Sie auf der Registerkarte "Params" (Parameter) unter "Path Variables" (Pfadvariablen) für SOBJECT_API_NAME die Angabe Cloud_News__e ein.

Fügen Sie auf der Registerkarte Body (Text) den folgenden JSON-Text ein.

{
   "Location__c" : "Mountain City",
   "Urgent__c" : true,
   "News_Content__c" : "Lake Road is closed due to mudslides."
}

Klicken Sie auf Senden. Die Antwort, die Salesforce nach Posten des Ereignisses zurückgibt, sieht wie folgt aus.

{
  "id" : "e00xx0000000001AAA",
  "success" : true,
  "errors" : [
       {
            "statusCode": "OPERATION ENQUEUED",
            "message": "08ffc869-b9f8-4cff-a4ba-8dff9b3dd6cb",
            "fields": []
       }
   ]
}

Nachdem Sie gelernt haben, wie Ereignisse definiert und veröffentlicht werden, wollen wir sie nun abonnieren!

Ressourcen

Benötigen Sie Hilfe?

Mehr entdecken