無所屬單位

首頁 文獻與幫助
Steamworks 文獻庫
Web API 總覽

英文原文已更新

本頁原文在翻譯完成後已再次更新。\r
點擊這裡檢視最新的英文版本。

簡介

Steam 開放了以 HTTP 為基礎、可用來存取 Steamworks 一系列功能的 Web API 供人使用。任何應用程式,例如遊戲用戶端或伺服器,皆可透過 HTTP 使用 API 中的公開方法。另外,API 中也有受保護的方法,使用時需要認證,也必須從受信任的後端應用程式存取。

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

如想查閱 Steamworks Web API 所提供的功能的完整列表,請參閱Steamworks Web API Reference

要求格式

以 HTTP(Port 80)或 HTTPS(Port 443)將要求傳送至 api.steampowered.com 便可使用 Steamworks 的公開 Web API。
Steam 另外也為開發商提供了位於 https://partner.steam-api.com 的夥伴專用 Web API 伺服器,以在公開伺服器之外供應更多可利用的服務。所有從受保護的伺服器發出的要求,都應利用此服務。如需更多資訊,請參閱https://partner.steam-api.com段落。

和 Steamworks C++ API 一樣,Web API 被分為多個介面,當中包含類似的方法。而 URI 格式的 API 要求則是:
https://api.steampowered.com/<interface>/<method>/v<version>/

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

所有要求都必須透過 HTTP 1.1 傳送,並盡量使用 SSL v3,128 位元加密。Content-Type 應為 application/x-www-form-urlencoded,而 POST 參數應以標準 URL 格式編入要求本身之中。文字傳輸應使用 UTF-8。

驗證

許多 Web API 方法皆需唯一金鑰才能取得存取權,更多資訊請參閱 以 Web API 金鑰進行認證

陣列參數

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

服務介面

除了一般的 Web API 呼叫以外,另外也有服務介面。這些介面的運作方式與一般的介面非常相像,最大的不同在於接收引數時,服務介面 API 除了 GET 或 POST 參數以外,另外會收到單獨的一個 JSON Blob。要使用 JSON 傳入資料,須先叫用 webapi 方法,並將 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 Host: api.steampowered.com\r Content-Length: 0\r \r

您可點擊此連結,執行並閱覽此查詢的結果:
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 的變換快速且流暢,所以如果您發出要求時須穿過防火牆,請繼續往下讀。

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