Verbindung zu einem Datenstrom herstellen und Daten konsumieren

Führen Sie die folgenden Schritte aus, um eine Verbindung zu einem Datenstream herzustellen und Daten zu konsumieren:

Schritt 1: WebSocket-URL erstellen

Lesen Sie die folgenden Werte aus der generierten AsyncAPI YAML:

servers.<name>.protocol: ws oder wss.
servers.<name>.host: Hostname und, sofern vorhanden, Port.
channels.<name>.address: Füllen Sie den Pfad WebSocket für den Datenstream aus.

wss://<server-host><channel-address>?begin=<percent-encoded-begin-value>

Codeieren Sie den Pfad nicht per Hardcode: OCI GoldenGate, ein On-Premise-Deployment und ein Reverse Proxy können verschiedene Routingpräfixe angeben. Kopieren Sie die Host- und Kanaladresse aus der generierten YAML oder den kanonischen Links, die von der REST-API zurückgegeben werden.

Schritt 2: Wählen Sie den Anfangswert aus

Geben Sie den Wert BEGIN basierend auf den Richtlinien in der folgenden Tabelle an:

Wert	Verwendung	Richtlinien
`now`	Mit neuer Aktivität beginnen	In den aktuellen Zeitstempel konvertiert und anhand des verfügbaren Trails aufgelöst. Änderungen vor dem Lösungspunkt werden nicht zugestellt.
`earliest`	Ursprüngliches Back-Fill aus verfügbarem Trail	In Zeitstempel Null konvertiert. Die Auslieferung beginnt mit dem frühesten Datensatz, der im konfigurierten Trail noch verfügbar ist, und nicht unbedingt mit dem Beginn der Quellhistorie.
[ISO 8601-Zeitstempel]	In der Nähe einer Geschäftszeitgrenze beginnen	Der Service führt eine zeitstempelbasierte Suche durch. Verwenden Sie eine explizite Zeitzone. Beispiel: `2026-07-13T04:00:00Z`.
Gespeichert `pos`	Recovery nach vorheriger erfolgreicher Ausführung	Der Service führt eine positionsbasierte Suche aus. Das Ergebnis, wenn die Position nicht verfügbar ist, hängt von der Servicequalität ab.

Anfangswert in Prozent codieren

Ein pos-Token kann Zeichen wie +, / und = enthalten, die eine besondere Bedeutung in einer URL haben. Codieren Sie das vollständige Token in Prozent, bevor Sie es zur Abfragezeichenfolge hinzufügen. Ändern oder entschlüsseln Sie das Token nicht in der Anwendungslogik.

Schritt 3: Authentifizierung und TLS

Wählen Sie die Authentifizierungsmethode aus. Verwenden Sie die folgende Tabelle, um die am besten geeignete Methode zu bestimmen:

Modus	Anwendungsfall	Clientantwort
Basisauthentifizierung	Häufig mit einem direkt bereitgestellten Dienst oder Reverse Proxy	Senden Sie einen `Authorization: Basic ...`-Header. Behalten Sie Zugangsdaten in einem Secret Store oder in einer Umgebung bei, nicht in der URL oder dem Quellcode.
Digestauthentifizierung	Bei Bedarf vom Reverse Proxy	Verwenden Sie einen Client oder eine generierte Vorlage, mit der die HTTP-Digest-Challenge während des WebSocket-Handshakes implementiert wird.
Clientzertifikat	Gegenseitige TLS- oder zertifikatbasierte Serviceauthentifizierung	Laden Sie das Clientzertifikat und den Private Key in den TLS-Kontext, und validieren Sie den Server anhand der konfigurierten CA.
Sicherer Reverse Proxy	Gateway beendet oder leitet TLS weiter	Folgen Sie dem Proxy-Authentifizierungsmodus. Ein sicherer Proxy kann sowohl grundlegende/digest-Berechtigungsnachweise als auch ein Clientzertifikat erfordern.

Schritt 4: Generieren Sie einen Client aus AsyncAPI

Oracle stellt eine WebSocket-Clientvorlage für den AsyncAPI-Generator bereit. Es kann JavaScript, Python, Java, Go oder alle unterstützten Clients generieren. Der Generator benötigt Node.js 18.12 oder höher und npm 8.19 oder höher.

npm install -g @asyncapi/generator

git clone https://github.com/oracle-samples/websocket-client-template.git
cd websocket-client-template

ag /path/to/sales-orders.yaml .
  -o output
  -p server=production
  -p language=python
  -p authorization=basic

cd output
python -m pip install -r requirements.txt
export ASYNCAPI_WS_CLIENT_USERNAME="$OGG_USER"
export ASYNCAPI_WS_CLIENT_PASSWORD="$OGG_PASSWORD"
python client.py

Die Vorlage unterstützt auch die Zertifikatsvariablen ASYNCAPI_WS_CLIENT_CERT, ASYNCAPI_WS_CLIENT_KEY und ASYNCAPI_WS_CA_CERT. Überprüfen Sie generierten Code und Abhängigkeitsversionen unter dem üblichen sicheren Softwareentwicklungsprozess Ihres Unternehmens.

Schritt 5: WebSocket-Nachrichten verstehen

Die übliche Nachrichten-Payload ist ein JSON-Array. Ein Frame kann einen oder mehrere Schema-, Metadaten-, DML- oder DDL-Datensätze enthalten. Der Client muss das Array iterieren und jedes Objekt unabhängig klassifizieren.

Backpressure: Der Service überträgt Datensätze ohne eine Clientbestätigung pro Datensatz. Halten Sie die Empfangsschleife leicht. Setzen Sie langsame Geschäftsprozesse hinter eine begrenzte interne Queue oder eine dauerhafte Staging-Schicht, überwachen Sie die Queuetiefe und stoppen oder skalieren Sie den Consumer, bevor der Speicher erschöpft ist.

Schritt 6: Consumer-Verarbeitungsschleife

Erhalten Sie eine vollständige WebSocket-Nachricht.
Parsen Sie das JSON-Array. Wenn CloudEvents aktiviert ist, entpacken Sie das Element data.
Klassifizieren Sie Schema-, Stream-Metadaten, Objektmetadaten, DML- und DDL-Datensätze.
Validieren Sie Datensätze anhand des zuletzt gecachten Schemas, wenn eine Validierung erforderlich ist.
Wenden Sie den Geschäftsvorgang an, oder veröffentlichen Sie ihn in einem dauerhaften Downstream-System.
Nachdem der Vorgang erfolgreich war, speichern Sie den Datensatz pos mit dem ausgewählten atomaren oder idempotenten Checkpoint-Design.
Bei Verbindungsverlust stellen Sie die Verbindung mit dem letzten dauerhaften pos und dem exponentiellen Backoff wieder her.