資料源介面 GFI

GFI（Game Feed Interface）v1 是本平台唯一接受的牌局資料格式，也是對外開放的標準資料源入口。任何能提供真人百家樂、龍虎或牛牛牌局的系統，例如官方供應商、自營現場的荷官或資料員系統、中繼站、影像辨識系統，都以 GFI 把「開局、停止下注、發牌、結果、修正、作廢」等事件推送給本平台。

這一章寫給誰

這一章給資料源開發者。如果你是營運商、要把遊戲串到自己的網站，請看快速開始。

來源（source）：在本平台註冊、持有憑證的一個資料提供者，以 sourceId 識別（以小寫英文字母開頭，2–32 個小寫英數字、_ 或 -，例如 acme-live）。來源代號與金鑰由平台建立，請向平台申請。
來源桌：來源自己命名空間中的桌號，例如 B001（[A-Za-z0-9_.:-]，最多 64 個字元），由平台綁定到公開桌號。
串流（stream）：一個 (sourceId, 來源桌) 的事件序列。順序、去重、續傳都以串流為單位。
規格的單一真相：JSON Schema（2020-12）與本章；可以用 GFI 事件驗證器在瀏覽器中檢查事件。

傳輸

三種傳輸方式的事件格式完全相同：

方式	端點	適用
WebSocket（建議）	`wss://{ingest-host}/ingest/v1/stream`	長時間在線的來源，延遲最低
HTTPS 批次	`POST https://{ingest-host}/ingest/v1/events`	無法維持長連線、或需要補送時
Service Binding	平台內部	只供與本平台同一個 Cloudflare 帳號的 Worker

{ingest-host} 使用獨立的主機名稱：

環境	主機
正式	`elite-ingest.ewin888.com`
測試	`elite-dev-ingest.ewin888.com`

其他 HTTPS 端點：

方法與路徑	用途	回應
`POST /ingest/v1/events`	送出一批事件，本文 `{"events": [...]}`	`{"acks": {...}, "nacks": [...], "resync": [...]}`
`POST /ingest/v1/validate`	乾跑：與 `events` 相同的檢查，但不寫入、不套用	同上
`GET /ingest/v1/resume?tables=B001,B002`	查詢每條串流已確認的最後 `seq`	`{"resume": {"B001": 1530, "B002": 0}}`
`POST /ingest/v1/heartbeat`	心跳（HTTPS 來源），本文 `{"ts": "…", "tables": {"B001": "ok"}}`	`{"ok": true, "serverTime": "…"}`

每個來源可以使用哪些傳輸方式由平台設定；使用未開放的方式會回 403。

認證

所有 HTTPS 請求與 WebSocket 握手都帶下列標頭，簽章規則與租戶 API 相同：

text

X-Source-Id:  <sourceId>
X-Timestamp:  <Unix 秒>                 與本平台時間差 ≤ 300 秒
X-Nonce:      <16–64 個英數字>           10 分鐘內不可重複
X-Signature:  hex( HMAC-SHA256( secret,
                METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + hex(SHA-256(body)) ) )

PATH 是路徑加上查詢字串，例如 /ingest/v1/resume?tables=B001,B002。
WebSocket 握手的 METHOD 是 GET，本文是空字串。
可選的加強：IP 白名單（依來源 IP 判斷）。
錯誤回應的格式是 {"code": "…", "message": "…"}：

HTTP	`code`	原因
401	`UNAUTHORIZED`	缺少或格式錯誤的認證標頭、來源不存在、簽章錯誤、時間窗外、nonce 重複
403	`SOURCE_DISABLED`	來源已停用
403	`UNAUTHORIZED`	未開放這種傳輸方式，或來源 IP 不在白名單
400	`INVALID_EVENT`	本文不是 JSON
404	`NOT_FOUND`	端點不存在
405	`METHOD_NOT_ALLOWED`	方法錯誤（例如以 GET 呼叫 `events`）
413	`LIMIT_EXCEEDED`	超過批次限制
426	`UPGRADE_REQUIRED`	`/ingest/v1/stream` 沒有以 WebSocket 升級

限制

項目	值
單批事件數	≤ 500 筆，且 ≤ 1 MiB
單一事件	≤ 64 KiB
單一串流未確認事件（in-flight）	≤ 2,000 筆，超過就必須等待 ack
心跳間隔	5 秒
判定失聯	15 秒內沒有心跳也沒有事件
簽章時間窗	±300 秒
nonce 不可重複期間	10 分鐘

WebSocket 上超過批次限制時，連線以關閉碼 4008 結束；HTTPS 回 413。

接下來

事件與資料模型：事件信封、事件目錄、百家樂、龍虎與牛牛的結果格式（牛牛的暗發與逐家開牌）、時間與下注時窗。
可靠性、健康與錯誤：ack、去重、缺口與 resync、續傳、心跳、錯誤碼、信任等級與 WebSocket 對話範例。
GFI 事件驗證器：在瀏覽器中檢查一批事件。

資料源介面 GFI ​

傳輸 ​

認證 ​

限制 ​

接下來 ​

資料源介面 GFI

傳輸

認證

限制

接下來