你应该在开始API开发之前知道的事（上）（翻译）

时间：2023-03-09 09:09:36
你应该在开始API开发之前知道的事（上）（翻译）

这篇文章的源地址：http://dev.dota2.com/showthread.php?t=58317

由于文章内容较多，英语水平有限，准备尝试着以中英混搭的形式翻译，免得曲解一些不懂内容的意思。以下开始为翻译内容：

这篇文章会持续更新, 请在suggesting missing items前查看底部的TODO List

Web开发者现在可以以JSON或者XML格式，获得匹配历史记录及详情并使用在他们自己的应用中。

首先点击这里阅读WebAPI的条款协议

获得密钥

首先登录 http://steamcommunity.com/dev/apikey ，你将获得你的API唯一密钥。

请不要在做WebAPI请求的时候泄露或被其他人查看到。

来自Zoid的说明：

当你到 http://steamcommunity.com/dev/apikey 申请API时，the "domain" field is just a note. 事实上没有任何需要用到的地方， 只是一个 helpful field 让你能够告诉我们你的网站是哪个. 你也可以暂时填入你的名字. 一旦你获得了Key, 这个Key就是当你执行API请求时我们对你的唯一标示。

API请求

提供以下API使用：

(GetMatchHistory)              https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/v001/

(GetMatchDetails)              https://api.steampowered.com/IDOTA2Match_570/GetMatchDetails/v001/

(GetHeroes)                    https://api.steampowered.com/IEconDOTA2_570/GetHeroes/v0001/

(GetPlayerSummaries)           https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v0002/

(EconomySchema)                https://api.steampowered.com/IEconItems_570/GetSchema/v0001/

(GetLeagueListing)             https://api.steampowered.com/IDOTA2Match_570/GetLeagueListing/v0001/

(GetLiveLeagueGames)           https://api.steampowered.com/IDOTA2Match_570/GetLiveLeagueGames/v0001/

(GetMatchHistoryBySequenceNum) https://api.steampowered.com/IDOTA2Match_570/GetMatchHistoryBySequenceNum/v0001/

(GetTeamInfoByTeamID)          https://api.steampowered.com/IDOTA2Match_570/GetTeamInfoByTeamID/v001/

常用选项：

注意，除非另有说明，否则默认为空或忽略

key=<key>       # Your personal API key (from above)

language=<lang> # The language to retrieve results in (default is en_us) (see http://en.wikipedia.org/wiki/ISO_639-1 for the language codes (first two characters) and http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the country codes (last two characters))

format=<form>   # The format to retrieve results in ("JSON" or "XML") (default is JSON)

GetMatchHistory
Used to get a list of matches played.

player_name=<name>             # Search matches with a player name, exact match only

hero_id=<id>                   # Search for matches with a specific hero being played (hero ID, not name, see HEROES below)

game_mode=<mode>               # Search for matches of a given mode (see below)

skill=<skill>                  # 0 for any, 1 for normal, 2 for high, 3 for very high skill (default is 0)

date_min=<date>                # date in UTC seconds since Jan 1, 1970 (unix time format)

date_max=<date>                # date in UTC seconds since Jan 1, 1970 (unix time format)

min_players=<count>            # the minimum number of players required in the match

account_id=<id>                # Search for all matches for the given user (32-bit or 64-bit steam ID)

league_id=<id>                 # matches for a particular league

start_at_match_id=<id>         # Start the search at the indicated match id, descending

matches_requested=<n>          # Maximum is 25 matches (default is 25)

tournament_games_only=<string> # set to only show tournament games

例子：

根据某人的32位ID获得其最近的25场比赛

https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/V001/?key=<key>&account_id=XXXXX

获得最近的一场比赛

https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/V001/?key=<key>&matches_requested=1

注意，为了能够到”下一页“，你需要做这么一两件事：

  • 使用查询到的最后一场match_id来作为新一次查询的start_at_match_id:
  • https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/V001/?key=<key>&start_at_match_id=<id>&<OTHER_OPTIONS>
  • 使用查询到的最后一场starttime来作为新一次查询的date_max:
  • https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/V001/?key=<key>&date_max=<id>&<OTHER_OPTIONS>

返回结果的字段格式:

  • num_results - 在返回数据中，查询到结果的数量
  • total_results - 这次particular查询到结果的总数[(total_results / num_results) = total_num_pages]
  • results_remaining - 这次查询结果剩余未返回的数量 [(results_remaining / num_results) = remaining_num_pages]
  • matches - 有num_results个数量比赛的数组:
      • match_id - 比赛的数字ID
      • match_seq_num - 比赛序号 - the order in which matches are recorded
      • start_time - date in UTC seconds since Jan 1, 1970 (unix time format)

    lobby_type

      - lobby值的对应关系
      • 5 = Team match.
      • 4 = Co-op with bots.
      • 3 = Tutorial.
      • 2 = Tournament.
      • 1 = Practice.
      • 0 = Public matchmaking.
      • -1 = Invalid.
    • players - 玩家数组:
      • account_id - 玩家的32位Steam ID - 如果玩家将自己的资料设为隐私，account_id将会是"4294967295"
      • player_slot - 8位unsigned int型: if the left-most bit is set, the player was on dire. the two right-most bits represent the player slot (0-4).
      • hero_id - 玩家所玩英雄的数字ID (见下方）

GetMatchDetails

Used to get detailed information about a specified match.

可用的选项:

match_id=<id> # the match's ID

例子：

根据ID "XXXXX"获得比赛详细记录：、

https://api.steampowered.com/IDOTA2Match_570/GetMatchDetails/V001/?key=<key>&match_id=XXXXX

返回结果的字段格式:

  • players - 玩家数组
    • account_id - 玩家的32位Steam ID - 如果玩家将自己的资料设为隐私，account_id将会是"4294967295"
    • player_slot - 8位unsigned int型: if the left-most bit is set, the player was on dire. the two right-most bits represent the player slot (0-4).
    • hero_id - 玩家所玩英雄的数字ID
    • item_0 - 比赛结束时玩家的物品栏 左上 物品ID
    • item_1 - 比赛结束时玩家的物品栏 中上 物品ID
    • item_2 - 比赛结束时玩家的物品栏 右上 物品ID
    • item_3 - 比赛结束时玩家的物品栏 左下 物品ID
    • item_4 - 比赛结束时玩家的物品栏 中下 物品ID
    • item_5 - 比赛结束时玩家的物品栏 右下 物品ID
    • kills - 杀人数
    • deaths - 死亡数
    • assists - 助攻数
    • leaver_status
      • NULL - 玩家是电脑
      • 2 - 玩家放弃比赛
      • 1 - 玩家在比赛可以安全退出后放弃比赛
      • 0 - 玩家完成了整场比赛
    • gold - 玩家在比赛结束之后剩余的金钱
    • last_hits - 正补数
    • denies - 反补数
    • gold_per_min - 玩家每秒金钱
    • xp_per_min - 玩家每秒经验
    • gold_spent - 整场比赛玩家花费的金钱
    • hero_damage - 对英雄伤害
    • tower_damage - 对塔伤害
    • hero_healing - 对其他英雄的治疗量
    • level - 最后的等级
    • ability_upgrades - 一个数组详细的记录玩家每次加点记录
      • ability - 所加技能的ID
      • time - 加点时间（/秒）从比赛开始计算
      • level - 加点等级
    • additional_units - 玩家额外控制的单位信息 (其实就是熊德的宝宝)
      • unitname - 单位名字
      • item_0 - 比赛结束时物品栏 左上 物品ID
      • item_1 - 比赛结束时物品栏 中上 物品ID
      • item_2 - 比赛结束时物品栏 右上 物品ID
      • item_3 - 比赛结束时物品栏 左下 物品ID
      • item_4 - 比赛结束时物品栏 中下 物品ID
      • item_5 - 比赛结束时物品栏 右下 物品ID
    • season - ？
    • radiant_win - radiant赢了为true，false反之
    • duration - 整场比赛的用时
    • start_time - date in UTC seconds since Jan 1, 1970 (unix time format)
    • match_id - 比赛数字ID
    • match_seq_num - 比赛序号 - the order in which matches are recorded
    • tower_status_radiant - 11位 unsinged int: 见此链接
    • tower_status_dire - 11位 unsinged int: 见此链接
    • barracks_status_radiant - 6位 unsinged int: 见此链接
    • barracks_status_radiant - 6位 unsinged int: 见此链接 （吐槽，应该是dire不是radiant吧，还有应该是unsigned不是unsinged吧）
    • cluster - 见下方的REPLAYS
    • first_blood_time - 一血诞生的时间
    • replay_salt - 见下方REPLAYS 目前已从API中移除
    • lobby_type - lobby类型 (见上方GetMatchHistory)
    • human_players - 比赛中human players的数量
    • leagueid - 比赛所属leauge的ID (见上方GetMatchHistory)
    • positive_votes - 多少人顶
    • positive_votes - 多少人踩（估计这个写错了，应该是 negative_votes -多少人踩）
    • game_mode - 比赛模式
      • '1' : 'All Pick',
      • '2' : "Captains Mode",
      • '3' : 'Random Draft',
      • '4' : 'Single Draft',
      • '5' : 'All Random',
      • '6' : '?? INTRO/DEATH ??',
      • '7' : 'The Diretide',
      • '8' : "Reverse Captains Mode",
      • '9' : 'Greeviling',
      • '10' : 'Tutorial',
      • '11' : 'Mid Only',
      • '12' : 'Least Played',
      • '13' : 'New Player Pool'
    • 接下来的字段只会在 teams applied to radiant and dire 的时候有(i.e. this is a league match in a private lobby （英文不好，话说radiant和dire分别代表天辉和夜魇么？）
      • radiant_name - radiant 队伍的名字
      • radiant_logo -  radiant 队伍的LOGO (想要获得图片, 见下方FAQ)
      • radiant_team_complete - true为所有radiant的成员都属于本队伍, false反之 (i.e. are the stand-ins {false} or not {true})
      • dire_name - dire队伍的名字
      • dire_logo - the dire 队伍的LOGO (想要获得图片, 见下方FAQ)
      • dire_team_complete - true为所有dire的成员都属于本队伍, false反之  (i.e. are the stand-ins {false} or not {true})

下篇地址：http://www.cnblogs.com/Scohura/p/3600973.html