05 - Steam Web API 使用笔记

基本信息

• 文档地址：https://steamcommunity.com/dev
• Steamworks 完整文档：https://partner.steamgames.com/doc/webapi
• API 基地址：https://api.steampowered.com/
• 请求格式：GET https://api.steampowered.com/{interface}/{method}/{version}/?key={api_key}&{params}
• 返回格式：默认 JSON，可通过 &format=json/xml/vdf 指定

认证信息

• API Key 申请地址：https://steamcommunity.com/dev/apikey
• SteamID 查询工具：https://steamid.io（输入个人主页 URL 即可）
• 当前用户 SteamID：76561198141733567
• 当前用户主页：https://steamcommunity.com/id/KevinXue/

用户信息相关接口全览

接口分类

各接口详情

ISteamUser 接口

1. GetPlayerSummaries（玩家基本资料）

GET https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v2/
参数: key, steamids（逗号分隔，最多100个）

响应字段说明：

personastate 枚举：

示例 curl：

curl "https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v2/?key=YOUR_KEY&steamids=76561198141733567"

2. GetFriendList（好友列表）

GET https://api.steampowered.com/ISteamUser/GetFriendList/v1/
参数: key, steamid, relationship（可选，填 "friend" 只返回好友）

注意：若用户将好友列表设为私密，返回 HTTP 401（不是空列表）。

响应字段：

3. GetPlayerBans（封禁记录）

GET https://api.steampowered.com/ISteamUser/GetPlayerBans/v1/
参数: key, steamids（逗号分隔）

响应字段：

4. GetUserGroupList（加入的群组）

GET https://api.steampowered.com/ISteamUser/GetUserGroupList/v1/
参数: key, steamid

返回用户加入的所有 Steam 群组 GID 列表，需配合群组接口进一步查询名称。

5. ResolveVanityURL（自定义 URL → SteamID）

GET https://api.steampowered.com/ISteamUser/ResolveVanityURL/v1/
参数: key, vanityurl（如 "KevinXue"），url_type（1=个人, 2=群组）

返回 { "response": { "steamid": "76561198141733567", "success": 1 } }，用于将个性化主页地址转换为 64 位 SteamID。

IPlayerService 接口

6. GetRecentlyPlayedGames（近期游戏）

GET https://api.steampowered.com/IPlayerService/GetRecentlyPlayedGames/v1/
参数: key, steamid, count（返回数量，0=全部）

响应字段说明：

游戏图片 URL 拼装：

⚠️ 重要：Steam CDN 新旧格式并存

老游戏使用无 hash 的旧格式；2024 年后上架的新游戏改用带 hash 的新格式，旧格式对新游戏返回 404。
推荐统一通过 IStoreBrowseService/GetItems 获取真实 URL（见下文）。

// 旧格式（老游戏有效，新游戏 404）
https://steamcdn-a.akamaihd.net/steam/apps/{appid}/header.jpg

// 新格式（含 hash，需通过 API 获取，不可自行构造）
https://shared.akamai.steamstatic.com/store_item_assets/steam/apps/{appid}/{hash}/header.jpg?t={timestamp}

// 小图标（32×32）
https://media.steampowered.com/steamcommunity/public/images/apps/{appid}/{img_icon_url}.jpg

示例 curl：

curl "https://api.steampowered.com/IPlayerService/GetRecentlyPlayedGames/v1/?key=YOUR_KEY&steamid=76561198141733567&count=5"

实测返回示例（2025-04）：

{
  "response": {
    "total_count": 2,
    "games": [
      {
        "appid": 435150,
        "name": "Divinity: Original Sin 2",
        "playtime_2weeks": 518,
        "playtime_forever": 2541,
        "img_icon_url": "519a99caef7c5e2b4625c8c2fa0620fb66a752f3"
      },
      {
        "appid": 4126220,
        "name": "Crusaders Quest : Hero Town",
        "playtime_2weeks": 168,
        "playtime_forever": 168,
        "img_icon_url": "cea5c54b60cb10fadf8cad9130ba1c2227e9aa5e"
      }
    ]
  }
}

7. GetOwnedGames（完整游戏库）

GET https://api.steampowered.com/IPlayerService/GetOwnedGames/v1/
参数: key, steamid, include_appinfo=true（含游戏名称和图标）

返回用户完整游戏库 + 各游戏累计时长，数据量较大，按需使用。

8. GetSteamLevel（Steam 等级）

GET https://api.steampowered.com/IPlayerService/GetSteamLevel/v1/
参数: key, steamid

返回 { "response": { "player_level": 42 } }

9. GetBadges（徽章列表）

GET https://api.steampowered.com/IPlayerService/GetBadges/v1/
参数: key, steamid

响应字段：

注：同时返回 player_level，可代替 GetSteamLevel 一次性获取。

10. GetCommunityBadgeProgress（徽章任务进度）

GET https://api.steampowered.com/IPlayerService/GetCommunityBadgeProgress/v1/
参数: key, steamid, badgeid

返回指定徽章所有子任务（quest）的完成状态，适合展示"集换式卡牌"徽章进度等。

ISteamUserStats 接口

11. GetPlayerAchievements（游戏成就）

GET https://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v1/
参数: key, steamid, appid, l（语言，如 "schinese"）

响应字段：

限制：需指定 appid，适合为特定游戏展示成就墙。

12. GetUserStatsForGame（游戏统计数据）

GET https://api.steampowered.com/ISteamUserStats/GetUserStatsForGame/v2/
参数: key, steamid, appid

返回游戏内各类数值型统计（击杀数、通关次数等），字段因游戏而异，适合深度展示某款游戏数据。

IStoreBrowseService 接口

13. GetItems（批量获取商店信息，含封面 URL）⭐

GET https://api.steampowered.com/IStoreBrowseService/GetItems/v1/
参数: key, input_json（JSON 字符串，含 ids / context / data_request）

用途：批量获取游戏商店页面资产，包括真实封面 URL（支持新旧格式）。
关键优势：在 api.steampowered.com 上（不是 store.steampowered.com），服务器可达。

请求示例：

INPUT='{"ids":[{"appid":730},{"appid":4126220}],"context":{"language":"english","country_code":"US","steam_realm":1},"data_request":{"include_basic_info":true,"include_assets":true}}'
curl "https://api.steampowered.com/IStoreBrowseService/GetItems/v1/?key=YOUR_KEY&input_json=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.stdin.read().strip()))" <<< "$INPUT")"

注意：include_basic_info: true 是必须的，单独 include_assets: true 会返回空。

响应字段（assets 部分）：

封面 URL 构造方式：

CDN = "https://shared.akamai.steamstatic.com/store_item_assets/"
URL = CDN + asset_url_format.replace("${FILENAME}", header)

PHP 实现（activity-functions.php 中的 fetchSteamGameCovers）：

$cdn = 'https://shared.akamai.steamstatic.com/store_item_assets/';
$url = $cdn . str_replace('${FILENAME}', $assets['header'], $assets['asset_url_format']);

实测（2026-04-29）：

隐私设置路径：Steam → 个人资料 → 编辑个人资料 → 隐私设置 → 游戏详情设为"公开"

在 my-activity.php 中的使用

相关缓存文件：{TYPECHO_ROOT}/usr/cache/steam_activity.json（TTL 6小时）

Steam 模块相关 PHP 常量（定义在 config.inc.php）：

define('STEAM_API_KEY', 'YOUR_STEAM_API_KEY');
define('STEAM_ID', 'YOUR_STEAM_64BIT_ID');

相关文件

• 模板文件：usr/themes/classic-22/my-activity.php
• 配置文件：config.inc.php（含 API Key，已加入 .gitignore）
• 缓存目录：usr/cache/（已加入 .gitignore）
• 活动页文档：.maintenance/06-activity-page-notes.md