你應該在開始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