直接答案
先對分片賬號,取可用比賽,沿關係讀 telemetry asset URL。按類型和 ID 建 included 索引,不全算玩家;比賽元數據和遙測分存,下載失敗只重試該步。

對上賬號與平臺分片
從官方支持的平臺分片和目標賬號開始。顯示名可用於查詢,不適合作永久主鍵;保存賬號 ID 時保留平臺。查不到先核對拼寫和平臺。Bearer Token 留在本地或服務器私有環境,不能放進公開 HTML 和 JavaScript。
按關係連接資源
不要把 included 中每個對象都算玩家。Roster 組織參賽者,participant 表示玩家在本局的參賽記錄。先按資源類型和 ID 建索引,再讀取 relationships。Asset、roster 與 participant 即使在同一響應中,也是不同資源;測試關聯時保留原始響應。

使用返回的遙測地址
找到關聯的 telemetry asset,使用它給出的 URL,不拿日期和比賽 ID 自拼路徑。官方說明該下載不需要 API 授權頭。比賽響應與遙測文檔分開保存,下載失敗時不應丟掉已經獲取的比賽資料。
按失敗階段處理
玩家查詢失敗,不必重試遙測;比賽成功、asset 失敗時,只對失敗步驟有限重試。限流按響應頭與當前官方文檔處理,不照抄固定配額。日誌區分空結果、HTTP 錯誤與無效 JSON,讓排查從正確階段開始。
關聯前驗證資源身份
檢查響應的頂級類型、ID 和關係。為參與者、隊伍和資源建立獨立索引。在將玩家分配到團隊之前,先跟隨比賽的隊伍關係以及每個隊伍的參與者關係。缺失的引用資源應產生明確的驗證結果,而不是默默變為空團隊。在派生表旁邊存儲原始 ID。如果後續聚合導致玩家重複,請在責怪遙測之前,先將連接路徑與源響應進行比較。比賽資源和遙測事件文檔是不同的輸入,需要不同的解析器。
只重試失敗階段
記錄請求階段、HTTP 狀態和資源 ID,但不記錄承載令牌。區分不可用比賽、限流請求、資源傳輸失敗和無效 JSON。使用文檔化的響應信息進行有限次重試。官方遙測概述說明,資源下載不需要 API 授權頭;避免將令牌發送給任意資源主機。成功的 HTTP 響應仍需驗證其預期格式。緩存比賽元數據,這樣重試遙測時無需重新解析玩家。絕不要求訪問者將 API 密鑰粘貼到公共靜態頁面。
具體決策示例
示例:玩家和比賽成功、遙測傳輸失敗,保存前兩步,只有限重試 asset;解析成功仍核對應比賽再計算。
適用範圍與依據
先核已安裝構建、平臺和已開放功能。歷史公告只說明對應版本,操作示例不冒稱實測。
下次遊玩時
- 密鑰不進入網站。
- 按類型和 ID 關聯。
- 使用返回的遙測地址。
本文官方參考資料
- Matches endpoint ↗資料採集日期:2026 年 11 月 16 日
- Players endpoint ↗資料採集日期:2026 年 11 月 16 日
- Telemetry overview ↗資料採集日期:2026 年 11 月 16 日
- API rate limits ↗資料採集日期:2026 年 11 月 16 日
- Making requests ↗資料採集日期:2026 年 11 月 16 日
引用來源不保證舊功能始終不變;遇到差異,以當前遊戲內說明為準。