Steamworks 文獻庫
Web API 總覽

簡介

Steam 有以 HTTP 為基礎的公開 Web API,可以用來存取多項 Steamworks 功能。 任何能夠發出 HTTP 請求的應用程式,如遊戲用戶端或伺服器,都可以使用 API 中的公開方法(Method)。 另外,API 中也有受保護的方法,使用時需要認證,也必須從受信任的後端應用程式存取。

比方說,受保護的開發商伺服器經常會使用 Web API 方法來:
  • 向伺服器確認 Steam 使用者的憑證
  • 檢查使用者是否擁有某款應用程式
  • 設定或取得使用者的統計、成就,或排行榜分數
  • 進行遊戲內購買

如想查閱 Steamworks Web API 的完整功能列表,請見 Steamworks Web API 索引

請求格式

以 HTTP(Port 80)或 HTTPS(Port 443)將請求傳送至 api.steampowered.com 便可使用 Steamworks 的公開 Web API。
若為發行商,Steam 也有在 https://partner.steam-api.com 提供合作夥伴專用的 Web API 伺服器, 以在公開伺服器之外供應更多可利用的服務。所有從受保護的伺服器發出的請求,都應利用此服務。 詳情請見 有關 Web API 主機位址和防火牆的考量

和 Steamworks C++ API 類似,Web API 分為多個介面,當中包含相關的方法。 API 請求的 URI 格式如下:
https://api.steampowered.com/<介面>/<方法>/v<版本>/

大部分的方法皆支援一些必要或非必要的參數。 根據各個方法的不同,發出請求時參數須以 GET 或 POST 的方式傳入。

所有請求都必須透過 HTTP 1.1 傳送,並在可能的情況下盡量使用安全的 TLS 連線。 Content-Type 必須為 application/x-www-form-urlencoded,而 POST 參數必須以標準 URL 編碼格式加入請求主體之中。 文字傳輸應使用 UTF-8。

驗證

許多 Web API 方法皆需唯一金鑰才能取得存取權,詳情請見Authentication using Web API Keys

陣列參數

有些方法預期接收的是參數陣列, 這通常會以在參數名尾加上 [0] 來表示。 傳入陣列時,當中一定會有 count 參數,用來表示陣列中的參數數量。 例如:
?count=2&name[0]=[一個名稱]&name[1]=[另一個名稱]

服務介面

除了一般的 Web API 呼叫以外,另外也有服務介面。 這些介面的運作方式與一般的介面非常相像,最大的不同在於接收引數時,服務介面 API 除了 GET 或 POST 參數以外,另外也接受單獨的一個 JSON Blob。 要使用 JSON 傳入資料,須先叫用 Web API 方法,並將 input_json 參數設為:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

請注意,JSON 須使用 URL 編碼。 像之前一樣,當中的「key」和「format」欄位須做為不同的參數傳入。 另外,POST 類型的請求也是支援的。

Web API 是否為「服務」可以從介面名稱來判斷。如果名稱是以「Service」結尾,例如 IPlayerService,那麼便會額外支援這種傳入參數資料的方法。 有些服務方法的參數結構更為複雜,便需要另外的輸入格式。

查詢範例

下方的範例將取得《絕地要塞 2》最新的三篇新聞。
請求中指定要以 JSON 格式回應,並包含:必要的 AppID 參數(《絕地要塞 2》的 AppID 為 440),以及一個非必要的 count 參數,用來限制傳回的結果數量。

GET /ISteamNews/GetNewsForApp/v2/?appid=440&count=3\r\n Host: api.steampowered.com/r/n Content-Length: 0\r\n\r\n

點擊此連結即可執行並檢視上述的查詢結果:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

更多有關此呼叫的資訊,請見 ISteamNews/GetNewsForApp

取得使用者的 SteamID

Steamworks Web API 使用的是 64 位元的唯一 Steam ID 來辨識每位使用者。 若想了解如何安全地取得使用者的 Steam ID,請見使用者驗證與所有權

有關 Web API 主機位址和防火牆的考量

公開的 Web API(api.steampowered.com)位於 Akamai 的邊緣快取之後,所以您透過名稱實際查到的 IP 位址會根據您所在的地區,以及伺服器進行中的變更而有所不同。 IP 的變換快速且流暢,所以如果您向外傳出的 Web API 呼叫須穿過防火牆,請繼續往下讀。

所有從受保護的伺服器傳出的請求應使用合作夥伴專用的節點(https://partner.steam-api.com)。 此主機與公開主機的屬性有些不同:
  • 此主機只能透過 HTTPS 存取
  • 此主機並非位於 Akamai 的邊緣快取之後
  • 所有傳至此主機的請求須以您的發行商 Web API 金鑰傳送,就算是原本不需要金鑰的請求也是如此。 如請求中沒有有效的發行商金鑰,便會傳回錯誤代碼 403
  • 若有請求不斷產生狀態代碼 403,進行連線的 IP 將被施予嚴格的速率限制,這通常會在使用一般 Web API 金鑰而不是發行商金鑰時發生。 這麼做是為了確保高度的可用性
  • 如果向此 API 服務送出請求的主機對傳出的請求施有防火牆篩選,請將 DNS 名稱「partner.steam-api.com」加入您的允許清單中。 如果您的防火牆僅支援數字位址,請將後方的 CIDR 區塊加入允許清單:208.64.202.0/24
    備註:您不應使用 IP 連線至 Web API 伺服器;請用 DNS 名稱。 這些位址僅供用戶端用來加入防火牆的白名單中

將 IP 位址加入白名單

我們允許針對 Web API 呼叫將 IP 位址加入白名單。 這是為了預防 Web API 金鑰遭竊的額外保護措施,因為這樣能確保只有來自 IP 位址白名單的 Web API 呼叫會成功。 一旦加入任何 IP 並建立了白名單,其餘非白名單中的位址提出的請求將被阻擋,並回傳「403 - 禁止」回應。

將 IP 位址加入白名單相當容易。 從任何有 Web API 金鑰的群組頁面,點擊「管理 Web API 金鑰」按鈕,然後按照指示進行即可。

每個 Web API 金鑰都有自己的白名單,而將 IP 位址加入白名單並非必要事項。

備註:白名單無法保障 Web API 金鑰的安全。 請保護自己的金鑰,切勿分享,如遭竊應立即更改。