你应该在开始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/

• 如果想要了解所有可用的API，请看 http://wiki.teamfortress.com/wiki/WebAPI

常用选项：

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

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