无所属单位

主页 文献与帮助
Steamworks 文献库
网页 API 概览

原文内容有作更新

此页原文在翻译版发布之后作了更新。
点击此处查看此页更新后的英文版本。

简介

Steam 公开了基于 HTTP 的网页 API,用于访问多个 Steamworks 功能。从任何可进行 HTTP 请求的应用程序,如游戏客户端或服务器,均可访问该 API 所包含的公开方法。该 API 还包含需要验证的受保护方法,可从受信任的后端应用程序访问。

比如说,安全的发行商服务器通常将网页 API 方法用于:
  • 向该服务器验证 Steam 用户的凭据。
  • 检查用户是否拥有特定的应用程序。
  • 设置或检索用户统计、成就或排行榜分数。
  • 进行游戏内购买。

您可在 Steamworks Web API 参考资料 找到 Steamworks 网页 API 完整列表。

请求格式

可向 api.steampowered.com 发出 HTTP (80 端口)或 HTTPS (443 端口)请求以访问公开的 Steamworks 网页 API。
如您为发行商,则 Steam 也提供托管在 https://partner.steam-api.com 只面向合作伙伴的网页 API 服务器。此举意在提供比公共主机更好的可用性。您应用此来处理从您的安全服务器发出的所有请求。更多信息请参见 网页 API 主机地址、防火墙注意事项 部分。

网页 API 与 Steamworks C++ API 相似,已划分为包含相关方法的多个接口。每个 API 请求的 URI 格式为:
https://api.steampowered.com/<interface>/<method>/v<version>/

大部分方法支持必须和可选参数列表。根据方法不同,这些参数在请求中须以 GET 或 POST 参数传递。

如可能,所有请求应用 HTTP 1.1 发送并使用 SSL v3 版本 128 位加密。“内容类型”必须为 application/x-www-form-urlencoded,且 POST 参数必须以标准 URL 编码格式呈现在请求正文中。文本必须以 UTF-8 传送。

验证

许多网页 API 方法有访问限制,如想访问需有专门密钥,更多信息请参见 使用网页 API 密钥进行授权

数组参数

有些方法需要参数数组。这可通过参数名称中的后缀 [0] 来指定。传递数组时总是会有 count 参数来指定数组中参数的数量。如:
?count=2&name[0]=SomeNameHere&name[1]=SomeOtherName

服务接口

除常规网页 API 调用之外还有服务接口。这些接口功能与常规接口非常相似,主要区别在于所有的服务 API 除把其自变量作为 GET 或 POST 参数接收之外也作为单一 JSON blob接收。如需将数据以 JSON 传入,调用网页 API 方法,将 input_json 参数设为:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

请注意 JSON 需进行 URL 编码。“key” 字段及 “format” 字段仍应如前作为单独参数传递。POST 请求也同样支持。

可从接口名称判断网页 API 是否是“服务”接口。如名称以 “service” 结尾,如 IPlayerService,则该接口支持该传递参数数据的额外方法。某些“服务”方法具有结构更为复杂的参数并要求另外的输入格式。

查询示例

以下示例检索了《军团要塞 2》三条最新的新闻。
检索请求指明结果应以 JSON 返回,请求还包括:必需的 AppID 参数(《军团要塞 2》的 AppID 为440),及可选的计数参数,以限制所返回结果的数量。

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

获取用户 Steam ID

Steamworks 网页 API 通过使用用户独有的 64 位 Steam ID 来识别每位用户。如想了解如何安全获取用户 Steam ID,请参见 用户验证与所有权

网页 API 主机地址、防火墙注意事项

公开的网页 API (api.steampowered.com)位于 Akamai 的边缘缓存之后,因此您所看到的名称的实际 IP 地址会随您所在位置及所提供服务的变化而变化。IP 地址可以迅速而流畅地更改,因此如果您的网页 API 调用是穿越防火墙进行的出站请求,请继续往下阅读。

对于从您的安全服务器所发出的所有请求,您应使用只面向合作伙伴的节点 (https://partner.steam-api.com)。该主机与公共主机有以下不同的属性:
  • 该主机只可通过 HTTPS 访问。
  • 该主机并非位于 Akamai 的边缘缓存之后。
  • 向该主机发出任何请求必须使用您的发行商网页 API 密钥,即便这些请求一般不需要任何密钥。无有效发行商密钥的请求会被返回错误代码 403。
  • 产生 403 状态代码的请求会针对所连接的 IP 产生严格的速率限制。此举是为了确保高可用性。如您在一定的时间间隔内发出了相当数量的请求并返回了状态代码 403——无论是进行测试时或是因为使用了常规网页 API 而非您的发行商密钥——主机将把您的 IP 地址放入拒绝列表一段时间。
  • 如您发出 API 服务请求的主机有针对传出请求的防火墙筛选器,您应在允许列表中添加 DNS 名称 “partner.steam-api.com”。如您的防火墙只支持数字地址,则在允许列表中添加以下 CIDR 块:208.64.202.0/24
    备注:您不应通过 IP 地址连接至网页 API 服务器。请使用 DNS 名称。这些地址只提供给那些需要在其防火墙中将这些地址列入白名单的客户端。