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

1. Geben Sie unter Setup im Feld "Schnellsuche" den Text "Plattformereignisse" ein und wählen Sie dann Plattformereignisse aus.
2. Klicken Sie auf der Seite "Plattformereignisse" auf Neues Plattformereignis.
3. Geben Sie "Cloud News" in "Bezeichnung" ein.
4. Geben Sie "Cloud News" in "Bezeichnung - Plural" ein.
5. Geben Sie "Cloud news events deliver news at your fingertips" in "Beschreibung" ein.
6. Behalten Sie für "Veröffentlichungsverhalten" die Standardeinstellung Nach Commit veröffentlichen bei.
7. Klicken Sie auf Speichern.
8. Klicken Sie in der Themenliste "Benutzerdefinierte Felder & Beziehungen" auf Neu.
9. Wählen Sie Text und klicken Sie auf Weiter.
10. Geben Sie "Location" in "Feldbezeichnung/-name" ein.
11. 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.
12. 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 CometD- oder Pub/Sub-API-Clients 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. Sie können vorherige Ereignisse nur abrufen, wenn Sie sie in CometD abonnieren und eine "ReplayId"-Option verwenden. Das Abonnieren von Ereignissen erklären wir Ihnen in der nächsten Lektion.

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.

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.

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.

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.

1. Wählen Sie im Schnellzugriffsmenü () Developer Console aus.
2. Klicken Sie auf Debug | Open Execute Anonymous Window (Debuggen | Fenster für die anonyme Ausführung öffnen).
3. 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());
        }
    }
}

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

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

Externe Anwendungen nutzen eine API zum Veröffentlichen von Plattformereignisnachrichten. Sie veröffentlichen Ereignisse, indem Sie Datensätze Ihres Ereignisses auf dieselbe Weise erstellen, in der Sie sObjects einfügen. Mithilfe von Salesforce-APIs wie SOAP-API, REST-API oder Bulk-API können Sie Plattformereignisnachrichten erstellen. 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.

1. Melden Sie sich bei Ihrer Trailhead Developer Edition-Organisation an.
2. Öffnen Sie die Anwendung Postman, wählen Sie einen Arbeitsbereich aus und navigieren Sie zu Ihrem Fork der Salesforce-API-Sammlung.
3. Blättern Sie auf der Registerkarte "Authorization" (Autorisierung) ganz nach unten und klicken Sie auf Get New Access Token (Neues Zugriffstoken beziehen).
4. Klicken Sie auf Allow (Zulassen).
5. Kopieren Sie im Dialog "Manage Access Tokens" (Zugriffstoken verwalten) den Instanz-URL in die Zwischenablage.
6. Klicken Sie auf Use Token (Token verwenden).
7. 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.
8. Testen Sie, ob Ihre Verbindung funktioniert.
   1. Wählen Sie in "Collections" (Sammlungen) Ihren Fork der Salesforce-API-Sammlung aus.
   2. Wählen Sie REST aus, um die REST-APIs aufzuklappen.
   3. Wählen Sie GET Limits aus und klicken Sie dann auf Send (Senden).
   4. 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.

1. Klicken Sie in Ihrem Fork der Salesforce-API-Sammlung auf REST.
2. Klicken Sie auf SObjects, um die Option aufzuklappen.
3. Klicken Sie auf POST SObject Create.
4. Geben Sie auf der Registerkarte "Params" (Parameter) unter "Path Variables" (Pfadvariablen) für SOBJECT_API_NAME die Angabe Cloud_News__e ein.
5. 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."
   }

6. 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": []
          }
      ]
   }

Alternativ können Sie ein Ereignis in der SOAP-API über einen Aufruf von create() oder in der Bulk-API mithilfe von Batchaufträgen veröffentlichen. Sie können aber auch mit der Pub/Sub-API Ereignisnachrichten veröffentlichen, was praktisch ist, wenn Sie die Pub/Sub-API auch zum Abonnieren von Ereignisnachrichten nutzen. Weitere Informationen finden Sie in Dokumentation zur Pub/Sub-API.

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

• Streaming API Developer Guide: Dauerhaftigkeit von Nachrichten
• Plattformereignisse – Entwicklerhandbuch: Plattformereignisse – Zuordnungen
• Apex Developer Guide: Execution Governors and Limits
• Salesforce-Hilfe: Flows
• Trailhead: Schnelleinstieg: Verbinden von Postman mit Salesforce.
• Externe Hilfe: Schulungscenter für Postman
• Dokumentation zur Pub/Sub-API
• REST API Developer Guide
• SOAP API Developer Guide
• Bulk API Developer Guide