連線至資料流及使用資料

使用下列步驟連線至資料流及使用資料：

步驟 1：建立 WebSocket URL

從產生的 AsyncAPI YAML 讀取下列值：

servers.<name>.protocol：ws 或 wss。
servers.<name>.host：主機名稱和連接埠 (若有的話)。
channels.<name>.address：資料流的完整 WebSocket 路徑。

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

請勿對路徑進行硬式編碼： OCI GoldenGate、內部部署和反向代理主機可能會顯示不同的路由前置碼。從產生的 YAML 或 REST API 傳回的正規連結複製主機和通道位址。

步驟 2：選取開始值

根據下表提供的準則指定 BEGIN 值：

值	使用	準則
`now`	從新活動開始	轉換為目前的時間戳記，並依據可用的歷程檔解析。未提供解析點之前的變更。
`earliest`	從可用歷程檔起始回填	已轉換為時間戳記零。交貨開始於已設定軌跡中仍可使用的最早記錄，不一定是來源歷史記錄的開始。
ISO 8601 時間戳記	從接近業務時間界限開始	服務會執行以時間戳記為基礎的查尋。使用明確的時區，例如 `2026-07-13T04:00:00Z`。
已儲存 `pos`	先前成功執行後復原	服務會執行以職位為基礎的查尋。無法取得職位的結果取決於服務品質。

百分比編碼開始值

pos 記號可包含 +、/ 和 = 等字元，這些字元在 URL 中具有特殊意義。將完整權杖新增至查詢字串之前，請先進行百分比編碼。請勿修改或解碼應用程式邏輯中的記號。

步驟 3：認證和 TLS

選取認證方法。使用下表決定最合適的方法：

模式	使用時機	從屬端回應
基本驗證	通用於直接公開的服務或反向代理	傳送 `Authorization: Basic ...` 標頭。請將證明資料保留在加密密碼存放區或插入環境中，不在 URL 或原始程式碼中。
摘要驗證	反向代理主機需要時	使用在 WebSocket 交握式確認期間實行 HTTP 摘要查問的從屬端或產生的樣板。
從屬端憑證	雙向 TLS 或憑證式服務認證	將從屬端憑證和私密金鑰載入 TLS 相關資訊環境，然後根據設定的 CA 驗證伺服器。
安全反向代理主機	閘道終止或轉寄 TLS	遵循代理主機認證模式。安全代理可以同時要求基本 / 摘要憑證和用戶端憑證。

步驟 4：從 AsyncAPI 產生從屬端

Oracle 提供 AsyncAPI Generator 的 WebSocket 從屬端樣板。它可以產生 JavaScript、Python、Java、Go 或所有支援的用戶端。產生器需要 Node.js 18.12 或更新版本，以及 npm 8.19 或更新版本。

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

此樣板也支援憑證變數 ASYNCAPI_WS_CLIENT_CERT、ASYNCAPI_WS_CLIENT_KEY 和 ASYNCAPI_WS_CA_CERT。檢閱組織常用的安全軟體開發流程中產生的程式碼和相依性版本。

步驟 5：瞭解 WebSocket 訊息

一般訊息有效負載是一個 JSON 陣列。框架可以包含一或多個綱要、描述資料、DML 或 DDL 記錄。用戶端必須重複陣列，並獨立分類每個物件。

背壓：服務會在沒有記錄用戶端確認的情況下推送記錄。使接收迴圈保持輕量。將緩慢的業務處理放在有界限的內部佇列或持久暫存層後，監控佇列深度，並在耗盡記憶體之前停止或擴展用戶。

步驟 6：消費者處理迴圈

接收完整的 WebSocket 訊息。
剖析 JSON 陣列。啟用 CloudEvents 時，取消包裝 data 成員。
將綱要、串流描述資料、物件描述資料、DML 以及 DDL 記錄分類。
在需要驗證時，根據最新的快取結構驗證記錄。
套用業務作業或將其發布至持久的下游系統。
作業成功之後，請使用選取的單元或冪等檢查點設計來儲存記錄 pos。
連線中斷時，請重新連線最後一個持久的 pos 和指數後端。