Manuals

Deutsch

English

Deutsch

English

Appearance

SSE-Benachrichtigung ​

Der SSE (Server-Sent Events) Benachrichtigungsstrom ist der primäre Mechanismus, um einen Service-Client zu wecken, wenn neue Bestellungen oder Befehle verfügbar sind. Der Strom sendet nur leichte Benachrichtigungen. Er enthält niemals vollständige Bestell- oder Befehlspayloads. Wenn eine Benachrichtigung eingeht, sollte der Client sofort GET /orders/location für die tatsächlichen Daten abfragen.

Endpunkt ​

text
GET https://{host}/notifications/service/stream

Header:

HeaderErforderlichBeschreibung
api_keyJaAPI-Schlüssel des Service-Geräts

Query-Parameter:

ParameterTypStandardBeschreibung
orderNumberlong-1Zuletzt verarbeitete Bestellnummer für offset-basierte Wiederverbindung
commandNumberlong0Zuletzt verarbeitete Befehls-ID für offset-basierte Wiederverbindung

Antwort: text/event-stream (SSE-Stream mit SseEmitter)

Ereignisablauf ​

Nach der Verbindung sendet der Server Ereignisse in der folgenden Reihenfolge:

text
     Client                          Server
       |                               |
       |--- GET /notifications/service/stream --->|
       |                               |
       |<-- event: ready                 |
       |    data: {"subscriptionId": "...",|
       |           "locationName": "..."} |
       |                               |
       |<-- event: message              |  (bei neuen Bestellungen oder Befehlen)
       |    data: {"apiKey": "...",      |
       |           "licenseCode": "...", |
       |           "scope": "..."}      |
       |                               |
       |<-- event: keepalive            |  (alle 15 Sekunden)
       |    data: {}                   |

1. Ready-Ereignis ​

Bei erfolgreicher Verbindung sendet der Server sofort ein ready-Ereignis mit den Abonnement-Metadaten:

text
event: ready
data: {"subscriptionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","locationName":"Main Floor"}

Die subscriptionId identifiziert diese SSE-Verbindung eindeutig. Der locationName gibt an, welchen Standort der Client abonniert hat.

2. Message-Ereignisse ​

Wenn neue Bestellungen oder Befehle für den Standort verfügbar sind, sendet der Server ein message-Ereignis mit einer MessagesAvailableEvent-Payload:

text
event: message
data: {"apiKey":"abc123-def456","licenseCode":"LICENSE01","scope":"SESSION"}

Die MessagesAvailableEvent-Payload:

FeldTypBeschreibung
apiKeystringDer API-Schlüssel des Abonnements
licenseCodestringDer Lizenzcode des Mandanten
scopestringEntweder SESSION oder LICENSE, gibt den Broadcast-Bereich an

Dies ist ein Signal zum Abrufen. Es enthält keine Bestell- oder Befehlsdaten.

3. Keepalive-Ereignisse ​

Der Server sendet alle 15 Sekunden ein keepalive-Ereignis, um die Verbindung aufrechtzuerhalten:

text
event: keepalive
data: {}

Wenn 60 Sekunden lang kein Keepalive empfangen wird, sollte der Client annehmen, dass die Verbindung unterbrochen ist, und sich neu verbinden.

Verbindungs-Timeout ​

Der Dienstendpunkt konfiguriert den Emitter mit einem Zeitlimit von 60 Minuten. Der Scheduler sendet alle 15 Sekunden Keepalives. Behandeln Sie Schließen, Timeout und Netzwerkfehler durch erneutes Verbinden. Verlassen Sie sich nicht darauf, dass Keepalives den Stream unbegrenzt verlängern.

Ein Client kann nach 60 Sekunden ohne Keepalive eine Wiederverbindung starten. Das ist ein Vorschlag für die lokale Überwachung, keine Zusicherung des Servers über den Erkennungszeitpunkt eines Netzwerkfehlers.

Wiederverbindung mit Offset ​

Stellen Sie bei der Wiederverbindung nach einer Unterbrechung die zuletzt verarbeitete Bestellnummer und Befehls-ID als Query-Parameter bereit. Die Offsets bestimmen, welche ausstehenden Vorgänge eine Benachrichtigung auslösen. Sie sind kein Ereignisprotokoll und keine Verarbeitungsbestätigung:

bash
curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/notifications/service/stream?orderNumber=12345&commandNumber=42"
  • orderNumber — Die höchste bereits verarbeitete Bestell-number. Übergeben Sie -1 oder lassen Sie den Parameter weg, um keinen Offset zu verwenden (von Anfang an beginnen).
  • commandNumber — Die höchste bereits verarbeitete Befehls-ID. Übergeben Sie 0 oder lassen Sie den Parameter weg, um keinen Offset zu verwenden.

Der Server verwendet diese Offsets, um zu filtern, welche Bestellungen und Befehle Benachrichtigungen auslösen. Er verfolgt die gesendeten Offsets im Arbeitsspeicher für jedes Abonnement.

Fehlerantworten ​

Der SSE-Stream kann die folgenden HTTP-Statuscodes zurückgeben:

StatusBedeutung
401Nicht autorisiert — Ungültiger oder fehlender API-Schlüssel
503Dienst nicht verfügbar — Server vorübergehend nicht erreichbar. Client sollte mit exponentiellem Backoff wiederholen

Implementierungshinweise für Clients ​

Stream prüfen ​

Verwenden Sie einen Dienstclient, der den Header api_key senden kann. Prüfen Sie die Verbindung beispielsweise so:

bash
curl -N -H "api_key: abc123-def456-ghi789" \
  "https://{host}/notifications/service/stream?orderNumber=-1&commandNumber=0"

Prüfen Sie den vorgesehenen Standort im ready-Ereignis und anschließend die keepalive-Ereignisse. Lösen Sie einen abgestimmten Testvorgang aus, warten Sie auf message und rufen Sie die Vorgänge per Polling ab. Die message-Nutzlast enthält Zugangsdaten. Übernehmen Sie den Rohstream nicht in Protokolle oder Supportanfragen.

Ohne Verlust des Verarbeitungsstands erneut verbinden ​

  1. Schließen Sie den fehlgeschlagenen Stream vor einer neuen Verbindung.
  2. Verwenden Sie begrenzten exponentiellen Backoff, etwa 1, 2, 4, 8 Sekunden bis maximal 60 Sekunden. Untersuchen Sie wiederholte Fehler.
  3. Laden Sie Bestell- und Befehlsoffsets aus dauerhaft gespeicherten Verarbeitungsständen. Halten Sie beide Kennungsfolgen getrennt.
  4. Setzen Sie einen Offset nicht über noch offene oder zu klärende Vorgänge hinaus.
  5. Öffnen Sie den Stream und fragen Sie ausstehende Vorgänge ab. Ein ready-Ereignis darf gespeicherte Offsets nicht zurücksetzen.
  6. Prüfen Sie dauerhafte Verarbeitungsstände, bevor Sie eine externe Aktion wiederholen.

Browserbeispiele mit EventSource benötigen den Schlüssel in der URL. Bevorzugen Sie für eingesetzte Kassenintegrationen einen Dienstclient mit Headerauthentifizierung und schließen Sie Zugangsdaten aus URL- und Nutzlastprotokollen aus.

Was der Client tun muss ​

  1. Die SSE-Verbindung mit dem API-Schlüssel öffnen.
  2. Bei ready die subscriptionId und locationName aufzeichnen.
  3. Bei message sofort GET /orders/location aufrufen.
  4. Die zuletzt verarbeiteten orderNumber und commandNumber für die Wiederverbindung im Auge behalten.
  5. Wenn die Verbindung abbricht, mit exponentiellem Backoff und den Offset-Parametern erneut verbinden.

Was der SSE-Stream NICHT tut ​

  • Der SSE-Stream enthält keine Bestelldaten oder Befehlspayloads. Er ist nur ein Wecksignal.
  • Der SSE-Stream bestätigt nicht, dass Sie Bestellungen verarbeitet haben. Die Verarbeitungsbestätigung erfolgt über die Statusaktualisierungs- und Befehlsantwort-Endpunkte.

Nächste Schritte ​