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
  

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

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 Platform abonnieren Sie Ereignisse mit Apex-Auslösern, Prozessen, Flows und der Lightning-Komponente empApi. In einer externen Anwendung abonnieren Sie Ereignisse über die Pub/Sub-API.

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.

Ehe Sie dieses Beispiel ausführen, erstellen Sie eine Warteschlange mit der Bezeichnung "Regional Dispatch". Informationen zum Einrichten einer Warteschlange finden Sie unter Einrichten von Warteschlangen in der Salesforce-Hilfe. Weitere Informationen zum Objekt "Gruppe", das eine Warteschlange darstellt, finden Sie unter Gruppe in der Objektreferenz für Salesforce und die Lightning-Plattform. In diesem Beispiel werden Kundenvorgänge einer Warteschlange zugewiesen. Warteschlangen sind nicht Teil von Plattformereignissen und zu deren Nutzung nicht erforderlich. Durch das Zuweisen von Kundenvorgängen zu einer Warteschlange wird deren Verteilung an ein Team von Support-Agenten ermöglicht, die Mitglieder der Warteschlange sind.

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

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 Ereignisproduzenten 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". Gleichermaßen gilt, dass die Apex-Anweisung UserInfo.getUserId() die Einheit "Automatisierter Prozess" zurückgibt.

Sie können den ausführenden Benutzer eines Auslösers für Plattformereignisse überschreiben, sodass der Auslöser unter diesem Benutzer anstelle von "Automatisierter Prozess" ausgeführt wird. Konfigurieren Sie den Auslöser mithilfe von PlatformEventSubscriberConfig in der Metadaten- oder Tooling-API. Weitere Informationen finden Sie im Platform Events Developer Guide unter Configure the User and Batch Size for Your Platform Event Trigger.

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 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 ändern. Weitere Informationen finden Sie im Platform Events Developer Guide unter Configure the User and Batch Size for Your Platform Event Trigger.

Themenliste "Abonnements" auf der Seite "Ereignisdefinition"

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"

• 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 die Pub/Sub-API 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 Suspend (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.

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 einen Flow zu starten, sobald eine Plattformereignisnachricht empfangen wird, erstellen Sie einen durch ein Plattformereignis ausgelösten Flow. Wählen Sie im Element "Start" ein Plattformereignis aus, dessen Ereignisnachrichten die Ausführung des Flows auslösen.

Beim Erstellen des Flows können Sie die Feldwerte aus der Plattformereignisnachricht verwenden, indem Sie auf die globale Variable $Record verweisen.

Alternativ können Sie ein Plattformereignis in Flows abonnieren, indem Sie ein Element des Typs "Anhalten" verwenden. Anstatt einen Flow zu starten, wenn eine Plattformereignisnachricht empfangen wird, bewirkt diese Ereignisnachricht, dass ein angehaltenes Flow-Interview fortgesetzt wird. Hier sehen Sie beispielsweise ein Element "Anhalten", das den Flow solange anhält, bis Salesforce eine Cloud News-Ereignisnachricht erhält. Der Flow wird nur fortgesetzt, wenn der Standort des Ereignisses mit {!contact.MailingCity} übereinstimmt. In der Datensatzvariablen {!contact} werden Werte für einen Kontaktdatensatz speichert.

Abonnieren von Benachrichtigungen zu Plattformereignissen mithilfe der Pub/Sub-API

Die Pub/Sub-API bietet eine zentrale Schnittstelle zum Veröffentlichen und Abonnieren von Plattformereignissen. Basierend auf der gRPC-API und HTTP/2 veröffentlicht und übermittelt die Pub/Sub-API binäre Ereignisnachrichten effizient im Apache Avro-Format. gRPC ist ein Open Source Remote Procedure Call-Framework (RPC), das das Verbinden von Geräten, mobilen Anwendungen und Browsern mit Back-End-Services ermöglicht. Weitere Informationen finden Sie in der Dokumentation zu gRPC. Apache Avro ist ein System zur Serialisierung von Daten. Weitere Informationen finden Sie unter Apache Avro.

Die Pub/Sub-API verwendet ein Pull-Abonnement-Modell, bei dem der Client eine Anzahl von Ereignissen vom Server anfordert, die seiner Verarbeitungskapazität entspricht. Im Gegensatz zu Push-Abonnements, bei denen ein Client auf den Empfang neuer Ereignisse wartet, die vom Server gepusht werden, fordert ein Client bei einem Pull-Abonnement proaktiv Ereignisse vom Server an. Diese Steuerung des Ereignisflusses stellt sicher, dass der Client nicht mit mehr Ereignissen überlastet wird, als er verarbeiten kann, wenn es zu einer Spitze bei der Veröffentlichung von Ereignissen kommt.

Es folgen einige der Vorteile der Pub/Sub-API:

• Veröffentlichen, Abonnieren und Abrufen von Ereignisschemas in einer einzigen API
  
• Endgültige Veröffentlichungsergebnisse von Veröffentlichungsvorgängen und keine Zwischenergebnisse in der Warteschlange
  
• Flusskontrolle, mit der Sie festlegen können, wie viele Ereignisse in einem Abonnentenaufruf empfangen werden sollen, basierend auf der Geschwindigkeit der Ereignisverarbeitung im Client
  
• Leistungsstarkes Datenstreaming in Echtzeit mit Komprimierung durch HTTP/2
  
• Unterstützung von 11 Programmiersprachen im Client, die von der gRPC-API angeboten werden, z. B. Python, Java, Node und C++ Alle unterstützten Sprachen finden Sie unter https://grpc.io/docs/languages/.
  

Ein Pub/Sub-API-Client kann das Schema, die Wiedergabe-ID und die Payload separat aus dem empfangenen Ereignis abrufen und die Payload decodieren. Die Payload des empfangenen Cloud News-Ereignisses sieht beispielsweise so ähnlich aus wie diese Nachricht.

{
  "CreatedDate": 1652978695951,
  "CreatedById": "005SM000000146PYAQ",
  "Location__c": "San Francisco",
  "Urgent__c": true,
  "Ink_Percentage__c": "Large highway is closed due to asteroid collision."
}

Weitere Informationen finden Sie in Dokumentation zur Pub/Sub-API.

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.

Ressourcen

• Dokumentation zur Pub/Sub-API: Java-Schnelleinstieg für Pub/Sub API (in englischer Sprache)
  
• Plattformereignisse – Entwicklerhandbuch: Plattformereignisse – Zuordnungen
  
• Plattformereignisse – Entwicklerhandbuch: Retry Event Triggers with EventBus.RetryableException
  
• Trailhead: Erstellen einer Anwendung für Sofortbenachrichtigungen
  
• Salesforce-Hilfe: Zuweisungsregeln