Erfassen Sie Ihre Fortschritte
Trailhead-Startseite
Trailhead-Startseite

Abonnieren von Plattformereignissen

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:
  • Beschreiben, wie Nachrichten zu Plattformereignissen abonniert werden
  • Abonnieren eines Ereignisses auf der Plattform und in externen Anwendungen
  • Testen von Plattformereignissen in einer Apex-Testmethode
  • Abonnieren von Plattformereignissen mithilfe von CometD

Abonnieren von Plattformereignissen

Nachdem Sie erfahren haben, wie Plattformereignisse veröffentlicht werden, stellt sich nun die Frage, wie Sie sie abonnieren, um über die neuesten Nachrichten oder den Versand eines Pakets informiert zu werden? Auf der Salesforce-Plattform über Apex-Auslöser, Prozesse und Flows. Die Lightning-Komponente empApi und Visualforce-Anwendungen empfangen Ereignisbenachrichtigungen über CometD. Auch in einer externen Anwendung abonnieren Sie Ereignisse über CometD.

Abonnieren von Benachrichtigungen zu Plattformereignissen mithilfe von Apex-Auslösern

Sie haben Apex-Auslöser bislang wahrscheinlich schon einmal genutzt, um Aktionen auszuführen, die auf Datenbankereignissen basieren. Bei Plattformereignissen ist der Prozess ähnlich. Sie schreiben einfach für das Ereignisobjekt einen Apex-Auslöser des Typs "after insert", um eingehende Ereignisse zu abonnieren. In Apex bieten Auslöser einen automatischen Abonnementmechanismus. Sie müssen einen Kanal nicht explizit erstellen und überwachen. Auslöser empfangen Ereignisbenachrichtigungen aus verschiedenen Quellen unabhängig davon, ob diese über Apex oder APIs veröffentlicht wurden.

Plattformereignisse unterstützen nur "after insert"-Auslöser. Der "after insert"-Auslöser entspricht dem Zeitpunkt, nachdem ein Plattformereignis veröffentlicht wurde. Nachdem eine Ereignisnachricht veröffentlicht wurde, wird der "after insert"-Auslöser ausgelöst.

Ein Plattformereignisauslöser wird in der Developer Console erstellt.

  1. Klicken Sie auf das Symbol "Setup", wählen Sie Developer Console aus und klicken Sie auf File | New | Apex Trigger.
  2. Geben Sie einen Namen an, wählen Sie Ihr Ereignis für das sObject und klicken Sie auf Submit.

Die Developer Console fügt das after insert-Ereignis der Auslöservorlage automatisch hinzu. Außerdem können Sie einen Auslöser in Setup auf der Definitionsseite des Ereignisses in der Themenliste "Auslöser" erstellen. Sie müssen jedoch als Schlüsselwort after insert angeben.

Das folgende Beispiel zeigt einen Auslöser für das "Cloud News"-Ereignis. Es durchläuft jedes Ereignis und prüft mithilfe des Felds Urgent__c, ob die Nachricht dringend ist. Wenn die Nachricht dringend ist, löst der Auslöser einen Vorgang zum Entsenden eines Berichterstatters aus und fügt den Ort des Ereignisses dem Vorgangsthema hinzu.

// Trigger for listening to Cloud_News events.
trigger CloudNewsTrigger on Cloud_News__e (after insert) {
    // List to hold all cases to be created.
    List<Case> cases = new List<Case>();
    // Get queue Id for case owner
    Group queue = [SELECT Id FROM Group WHERE Name='Regional Dispatch' AND Type='Queue'];
    // Iterate through each notification.
    for (Cloud_News__e event : Trigger.New) {
        if (event.Urgent__c == true) {
            // Create Case to dispatch new team.
            Case cs = new Case();
            cs.Priority = 'High';
            cs.Subject = 'News team dispatch to ' +
                event.Location__c;
            cs.OwnerId = queue.Id;
            cases.add(cs);
        }
   }
    // Insert all cases corresponding to events received.
    insert cases;
}

Einrichten der Debug-Protokollierung

Im Gegensatz zu Standard- oder benutzerdefinierten Objekten werden Auslöser für Plattformereignisse nicht in derselben Apex-Transaktion ausgeführt wie derjenigen, in der das Ereignis veröffentlicht wurde. Der Auslöser wird in einem eigenen Prozess unter der Einheit "Automatisierter Prozess" (Systembenutzer) ausgeführt. Demzufolge werden Debug-Protokolle, die zur Ausführung des Auslösers gehören, von der Einheit "Automatisierter Prozess" erstellt und stehen nicht in der Entwicklerkonsole zur Verfügung. Fügen Sie zum Erfassen von Protokollen für Plattformereignisauslöser in Setup einen Verfolgungskennzeichnungseintrag für die Einheit "Automatisierter Prozess" hinzu.

  1. Geben Sie unter "Setup" im Feld "Schnellsuche" den Text "Debug-Protokolle" ein und klicken Sie dann auf Debug-Protokolle.
  2. Klicken Sie auf Neu.
  3. Wählen Sie Automatisierter Prozess für "Typ der verfolgten Einheit" aus.
  4. Wählen Sie das Anfangs- und Ablaufdatum für die Protokolle aus, die Sie erfassen möchten.
  5. Geben Sie für "Debugebene" * ein und klicken Sie auf Suchen.
  6. Wählen Sie eine vordefinierte Debugebene wie SFDC_DevConsole aus oder klicken Sie auf Neu, um eine eigene Debugebene zu erstellen.
  7. Klicken Sie auf Speichern.
Hinweis

Hinweis

Debug-Protokolle für Apex-Tests sind eine Ausnahme. Sie enthalten eine Protokollierung für Ereignisauslöser im selben Testausführungsprotokoll.

Hinweise zu Plattformereignisauslösern

Reihenfolge der Ereignisverarbeitung
Ein Auslöser verarbeitet Benachrichtigungen zu Plattformereignissen nacheinander in der Reihenfolge des Empfangs. Die Reihenfolge von Ereignissen basiert auf der Wiedergabe-ID des Ereignisses. Ein Apex-Auslöser kann ein Batch von Ereignissen gleichzeitig empfangen. Die Reihenfolge von Ereignissen wird innerhalb jedes Batches beibehalten. Die Ereignisse in einem Batch können von einem oder mehreren Publishern stammen.

Asynchrone Ausführung von Auslösern
Ein Plattformereignisauslöser wird in seinem eigenen Prozess asynchron ausgeführt und gehört nicht zur Transaktion, die das Ereignis veröffentlicht hat. Als Folge kann es eine Verzögerung zwischen dem Zeitpunkt der Veröffentlichung eines Ergebnisses und dem seiner Verarbeitung geben. Erwarten Sie nicht, dass das Ergebnis der Ausführung des Auslösers sofort nach der Veröffentlichung des Ereignisses verfügbar ist.

Systembenutzer "Automatisierter Prozess"
Da Plattformereignisauslöser nicht unter dem Benutzer ausgeführt werden, der sie ausführt (ausführender Benutzer), sondern unter dem Systembenutzer "Automatisierter Prozess", legen wir das Feld mit der Inhaber-ID in unserem "CloudNewsTrigger"-Beispiel explizit fest. Wir haben für das Auslöserbeispiel die ID einer beispielhaften Benutzerwarteschlange namens "Regional Dispatch" verwendet. Wenn Sie einen Salesforce-Datensatz mit dem Feld OwnerId im Auslöser erstellen, z. B. einen Kundenvorgang oder eine Opportunity, legen Sie die Inhaber-ID explizit fest. Für Kundenvorgänge und Leads können Sie den Inhaber auch mithilfe von Zuweisungsregeln festlegen.

Außerdem verweisen Systemfelder von Datensätzen, die beim Ereignisauslöser erstellt oder aktualisiert werden, wie CreatedById und LastModifiedById, auf die Einheit "Automatisierter Prozess" und nicht auf den ausführenden Benutzer. Gleichermaßen gilt, dass die Apex-Anweisung UserInfo.getUserId() die Einheit "Automatisierter Prozess" zurückgibt.

Apex-Obergrenzen
Wie Standard- oder benutzerdefinierte Objektauslöser unterliegen Plattformereignisauslöser Apex-Obergrenzen

Grenzwerte für Apex-Auslöser
Für Plattformereignisauslöser gelten viele der Grenzwerte für benutzerdefinierte und standardmäßige Objektauslöser. Sie können beispielsweise Apex-Callouts nicht synchron aus Auslösern erfolgen lassen.

Batchgröße für Auslöser
Die maximale Batchgröße in einem Plattformereignisauslöser sind 2.000 Ereignisnachrichten, was größer als die Batchgröße des Salesforce-Objektauslösers (200) ist. Die Batchgröße entspricht der Größe der Liste "Trigger.New". Sie können die Batchgröße eines Plattformereignisauslösers steuern und Grenzwerte sowie nicht abgefangene Ausnahmen durch Setzen eines Prüfpunkts behandeln. Weitere Informationen finden Sie im Platform Events Developer Guide unter Process Platform Event Messages in Smaller Batches in Apex Triggers.

Den Status aller Ereignisauslöser können Sie in Setup auf der Detailseite der Plattformereignisdefinition anzeigen. Unter "Abonnements" wird jeder aktive Auslöser zusammen mit Informationen zur Ausführung und Status aufgeführt. Zu den Informationen gehören die Wiedergabe-ID der letzten veröffentlichten und verarbeiteten Ereignisse. Der Status gibt an, ob der Auslöser ausgeführt wird oder aufgrund nicht zu korrigierender Fehler oder unzureichender Berechtigungen vom Abonnement getrennt ist. Der Status "Fehler" wird nur erreicht, wenn ein Auslöser mit der maximal zulässigen Anzahl wiederholt wurde. Der folgende Screenshot zeigt die Themenliste "Abonnements" auf der Ereignisdetailseite "Cloud News"

Hinweis

Hinweis

  • In der Themenliste "Abonnements" sind auch Flows und Prozesse aufgelistet, die für das Ereignis abonniert sind. 
  • Die Themenliste "Abonnements" enthält keine Abonnenten, die CometD oder die Lightning-Komponente empApi verwenden. Die anderen Typen von Abonnenten lernen Sie im weiteren Verlauf dieser Einheit kennen. 
  • Für Plattformereignisse mit hohem Volumen ist der Wert "Zuletzt veröffentlichte ID" nicht verfügbar und wird stets als "Nicht verfügbar" angezeigt.

Verwalten der Abonnenten von Apex-Auslösern eines Ereignisses

Setzen Sie ein ausgesetztes Abonnement an der Stelle fort, an der es unterbrochen wurde, beginnend mit der frühesten Ereignisnachricht, die im Ereignisbus verfügbar ist Wenn Sie Ereignisnachrichten umgehen möchten, die Fehler verursachen oder nicht mehr benötigt werden, können Sie das Abonnement von der Spitze aus fortsetzen und mit neuen Ereignisnachrichten beginnen.

Klicken Sie zum Verwalten des Abonnements eines Auslösers in der Themenliste "Abonnements" neben dem Apex-Auslöser auf Verwalten.

Wählen Sie auf der Detailseite des Abonnements die gewünschte Aktion aus.
  • Zum Aussetzen eines ausgeführten Abonnements klicken Sie auf Aussetzen.

  • Zum Fortsetzen eines ausgesetzten Abonnements beginnend mit der frühesten Ereignisnachricht, die im Ereignisbus verfügbar ist, klicken Sie auf Fortsetzen.
  • Zum Fortsetzen eines ausgesetzten Abonnements ab neuen Ereignisnachrichten klicken Sie auf Resume from Tip (Ab Spitze fortsetzen).


Sie können keine Abonnements für Flows und Prozesse über die Themenliste "Abonnements" verwalten.

Hinweis

Hinweis

Wenn Sie einen Auslöser speichern, wird das Abonnement des Auslösers automatisch fortgesetzt. Weitere Informationen finden Sie im Platform Events Developer Guide unter View and Manage an Event’s Subscribers on the Platform Event’s Detail Page.

Testen von Plattformereignisauslösern

Vergewissern Sie sich, dass Ihr Plattformereignisauslöser ordnungsgemäß funktioniert, indem Sie einen Apex-Test hinzufügen. Ehe Sie Apex-Code (einschließlich Auslösern) packen oder in der Produktion bereitstellen können, müssen Sie Ihren Apex-Code testen. Um Plattformereignisse in einem Apex-Test zu veröffentlichen, umgeben Sie die Veröffentlichungsanweisungen mit den Anweisungen "Test.startTest" und "Test.stopTest".

// Create test events
Test.startTest();
// Publish events
Test.stopTest();
// Perform validation here

In einem Testkontext wird der Veröffentlichungsvorgang beim Aufruf der Veröffentlichungsmethode in eine Warteschlange gestellt. Die "Test.stopTest()-"Anweisung bewirkt, dass die Ereignisveröffentlichung erfolgt. Überprüfen Sie hinter "Test.stopTest()" Ihre Validierungen.

Es folgt ein Beispiel einer Testklasse für unser "Cloud_News"-Ereignis und des zugehörigen Auslösers. Das Veröffentlichen des Ereignisses bewirkt, dass der zugehörige Auslöser ausgelöst wird. Nach der Anweisung "Test.stopTest()" prüft der Test, ob die Veröffentlichung erfolgreich war. Dazu wird der von "isSuccess()" zurückgegebene Wert in "Database.SaveResult" geprüft. Außerdem fragt der Test den Vorgang ab, den der Auslöser erstellt hat. Wenn ein Vorgangsdatensatz gefunden wird, wurden der Auslöser erfolgreich ausgeführt und der Test bestanden.

@isTest
public class PlatformEventTest {
    @isTest static void test1() {
        // Create test event instance
        Cloud_News__e newsEvent = new Cloud_News__e(
            Location__c='Mountain City',
            Urgent__c=true,
            News_Content__c='Test message.');
        Test.startTest();
        // Call method to publish events
        Database.SaveResult sr = EventBus.publish(newsEvent);
        Test.stopTest();
        // Perform validation here
        // Verify that the publish was successful
        System.assertEquals(true, sr.isSuccess());
        // Check that the case that the trigger created is present.
        List<Case> cases = [SELECT Id FROM Case];
        // Validate that this case was found.
        // There is only one test case in test context.
        System.assertEquals(1, cases.size());
    }
}

Abonnieren von Benachrichtigungen zu Plattformereignissen mithilfe einer Lightning-Komponente

Lightning-Anwendungen können die Lightning-Web- oder Aura-Komponente empApi verwenden, um in der Anwendung Ereignisse zu abonnieren.

Abonnieren in einer Lightning-Webkomponente

Um die empApi-Methoden in Ihrer Lightning-Webkomponente zu verwenden, importieren Sie die Methoden wie folgt aus dem Modul lightning/empApi.

import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled }
    from 'lightning/empApi';

Rufen Sie dann die importierten Methoden in Ihrem JavaScript-Code auf.

Ein Beispiel der Nutzung des Moduls lightning/empApi und eine vollständige Referenz finden Sie in der Lightning Component Library in der Dokumentation zu lightning-emp-api.

Abonnieren in einer Aura-Komponente

Um die empApi-Methoden in Ihrer Aura-Komponente zu verwenden, fügen Sie die Komponente lightning:empApi innerhalb Ihrer benutzerdefinierten Komponente hinzu und weisen Sie ihr das Attribut aura:id zu.

<lightning:empApi aura:id="empApi"/>

Fügen Sie anschließend im clientseitigen Controller Funktionen zum Aufrufen der Methoden der Komponente hinzu.

Ein Beispiel der Nutzung der Komponente lightning:empApi und eine vollständige Referenz finden Sie in der Lightning Component Library in der Dokumentation zu lightning:empApi.

Abonnieren von Benachrichtigungen zu Plattformereignissen mit Klicks

Um Ereignisnachrichten ohne Programmieraufwand zu abonnieren, erstellen Sie einen Prozess, der startet, wenn eine Ereignisnachricht empfangen wird.

Dieser Screenshot zeigt, dass ein Prozess startet, wenn ein Cloud News-Ereignis empfangen wird. Beim Start sucht der Prozess nach einem Kontaktdatensatz, bei dem "Postanschrift Stadt" mit dem Standort der Ereignisbenachrichtigung übereinstimmt.

Bildschirm mit Übereinstimmungskriterien im Prozessgenerator

Auf ähnliche Weise können Sie ein Plattformereignis in Flows abonnieren, indem Sie ein Pausenelement verwenden. Hier wird der Flow nicht gestattet, wenn ein Plattformereignis eintritt, sondern ein zuvor gestarteter Flow wartet auf eine Plattformereignisnachricht und wird dann fortgesetzt. Im Folgenden sehen Sie beispielsweise ein Pausenelement, das darauf wartet, dass Salesforce eine Cloud News-Ereignisnachricht erhält. Der Flow wird nur fortgesetzt, wenn der Standort des Ereignisses mit {!contact.MailingCity} übereinstimmt. {!contact} ist eine Datensatzvariable im Flow, die Werte für einen Kontaktdatensatz speichert.

Pausenkonfiguration im Flow Builder

Abonnieren von Benachrichtigungen zu Plattformereignissen mithilfe von CometD

Externe Anwendungen abonnieren Plattformereignisse mithilfe von CometD und führen ein sog. "Long Polling" durch. Die Lightning-Komponente empApi und Visualforce-Seiten, die auf der Plattform ausgeführt werden, können ebenfalls CometD nutzen und gelten als CometD-Clients. CometD ist ein skalierbarer HTTP-basierter Bus zur Weiterleitung von Ereignissen, der ein Comet genanntes AJAX-Push-Technologiemuster verwendet und das Bayeux-Protokoll implementiert. Long Polling, auch Comet-Programmierung genannt, ermöglicht die Emulation des Push-Vorgangs von Informationen von einem Server zu einem Client. Wie bei einem normalen Abfragevorgang verbindet sich der Client mit dem Server und fordert Informationen an. Doch anstatt eine leere Antwort zu senden, wenn die Informationen nicht verfügbar sind, speichert der Server die Anforderung und wartet, bis die Informationen vorliegen (ein Ereignis tritt ein).

Salesforce stellt mit dem EMP-Konnektor eine Java-Bibliothek bereit, die alle Details der Verbindungsherstellung mit CometD und Überwachung eines Kanals implementiert. Mithilfe des EMP-Konnektors können Sie Plattformereignisse ganz einfach abonnieren. Dabei blendet der EMP-Konnektor die Komplexität des Abonnierens von Ereignissen aus. Weitere Informationen zum EMP-Konnektor finden Sie im Java-Clientbeispiel im Streaming API Developer Guide.

Das Abonnieren von Benachrichtigungen zu Plattformereignissen über CometD ähnelt dem Abonnieren von PushTopic-Ereignissen oder allgemeinen Ereignissen. Der einzige Unterschied ist der Kanalname. Beim Namen des Kanals für Plattformereignisse muss die Groß-/Kleinschreibung beachtet und folgendes Format eingehalten werden.

/event/<EventName>__e

Wenn es beispielsweise ein Plattformereignis namens Cloud News gibt, geben Sie beim Abonnieren diesen Kanalnamen an.

/event/Cloud_News__e

Geben Sie die API-Version am Ende der CometD-URL wie folgt an.

// Connect to the CometD endpoint
    cometd.configure({
               url: 'https://<Salesforce_URL>/cometd/48.0/',
               requestHeaders: { Authorization: 'OAuth <Session_ID>'}
    });

Plattformereignisnachricht im JSON-Format

Die Nachricht eines übermittelten Plattformereignisses sieht so ähnlich aus wie das folgende Beispiel eines Cloud News-Ereignisses.

{
  "data": {
    "schema": "_2DBiqh-utQNAjUH78FdbQ",
    "payload": {
      "CreatedDate": "2017-04-27T16:50:40Z",
      "CreatedById": "005D0000001cSZs",
      "Location__c": "San Francisco",
      "Urgent__c": true,
      "News_Content__c": "Large highway is closed due to asteroid collision."
    },
    "event": {
      "replayId": 2
    }
  },
  "channel": "/event/Cloud_News__e"
}

Das Schemafeld in der Ereignisnachricht enthält die ID des Plattformereignisschemas (in diesem Beispiel "schema": "_2DBiqh-utQNAjUH78FdbQ"). Das Schema unterliegt der Versionierung, d. h., wenn sich das Schema ändert, ändert sich auch die Schema-ID.

Um zu bestimmen, ob sich das Schema eines Ereignisses geändert hat, rufen Sie das Schema über die REST-API ab. Nutzen Sie die Schema-ID zum Anwenden einer GET-Anforderung auf diese REST-API-Ressource: /vXX.X/event/eventSchema/Schema_ID. Alternativ können Sie das Ereignisschema abrufen, indem Sie für diesen Endpunkt den Ereignisnamen angeben: /vXX.X/sobjects/Platform_Event_Name__e/eventSchema. Weitere Informationen finden Sie im REST API Developer Guide.

Hinweis

Hinweis

Im Gegensatz zu PushTopic- und allgemeinen Ereignissen unterstützen Plattformereignisse keine gefilterten Abonnements. Beispielsweise wird das Abonnieren von /event/Cloud_News__e?Location__c='San Francisco' zum Filtern nach dem Ort nicht unterstützt.

Nachdem Sie erfahren haben, wie Plattformereignisse auf der Salesforce-Plattform und in externen Anwendungen verwendet werden, sind Ihre Möglichkeiten endlos! Nutzen Sie Plattformereignisse für eine beliebige Anzahl von Anwendungen und Integrationen, wie z.B. Geschäftstransaktionen oder Engagement in einem proaktiven Kundenservice. Mithilfe von Plattformereignissen können Sie ein ereignisbasiertes Programmierungsmodell übernehmen und in den Genuss der Vorteile einer ereignisbasierten Softwarearchitektur kommen.