Riot APIとJSON入門－JavascripとAjax使用（チュートリアル1）


Riot Games APIのフォーラムに投稿された、Riot APIの入門講座「Tutorial 1」の訳です。

Tutorial 1（Introduction to Riot API and JSON）

[Tutorial] Beginners introduction to Riot API and JSON, using Javascript and Ajax | Riot Games API



このチュートリアルの目的は、Riot APIとJSON、その基本的な呼び出し方法について、速習入門講座を提供することです。基本的なプログラミングやスクリプトを学んだことがあれば、ついてこれるはずです！これは初心者による初心者のためのチュートリアルです。

必須条件：
Riotの開発者サイトに会員登録していること

Riot APIとJSONの概要


これを読んでいる人のほとんどは、League of Legendsの何か面白いアプリを作ろうとしているからでしょう。でも、そのためにはまずRiot APIの仕組みと、思い通りのアプリにする方法を知らなければなりません。残りは、APIの活用方法とあなたの創造力次第です！

  • APIキー
    アカウントを作った時、もらったと思いますが、Dashboadで確認できます。これは、APIにアクセスするためのチケットです。後で説明しますが、アプリを作るとRiotはアクセス上限を増やしてくれるかもしれません。
  • API仕様
    もし初めてAPIを学ぶのであれば、簡単に言うと、何にアクセスできて、どのようにリクエストすればよいのかが書いてありあります。例えば、サモナーIDからそのサモナーの基本情報を知りたい時、Summoner APIを使ってカスタムURLを呼び出します。この後、API仕様の使い方を見てみましょう。
  • JSON
    JSONは、基本的には文字列で、通常のデータ送信に使われます。アプリが情報を要求した際に、Riot APIが返すデータ形式でもあります。例えば、サモナー名「Teemo」の情報を要求した場合、以下が返ってきます。
{"teemo": { "id": 35960410, "name": "Teemo", "profileIconId": 0, "revisionDate": 1347299919000, "summonerLevel": 6}}

API URL


では、API仕様を見てみましょう。前に述べたように、ヘッダー（champion、game、league、等）は、情報を取得するための様々なAPIメソッドを保持しています。「Summoner-Vx.x」APIヘッダーをクリックしてみてください。（図1）

（図1）

いくつかサブヘッダーが表示されると思います。例えば、/api/lol/{region}/vx.x/summoner/by-name/{summonerNames} や /api/lol/{region}/vx.x/summoner/{summonerIds}。

メモ：中括弧{}のエリアには、好きな値を指定できます。

例えば{region}には、APIメソッド呼出し時にサーバ名を指定できます。つまり、リクエストは指定されたサーバの情報しか取得できないということです。上記のAPIの例では、summonerNamesとsummonerIdsの中括弧があると思います。そこにはそれぞれ、具体的な値やサモナー名、サモナーIDのリストを代入できます。

最初のサブヘッダーをクリックしてみましょう。　/api/lol/{region}/vx.x/summoner/by-name/{summonerNames}　（図2）

（図2）

ここに、このAPIで取得できる情報が表示されます。このAPIは、リクエストしたサモナー名に関する項目を返します。IDと名前、プロフィールアイコン、リビジョン日付、サモナーレベル。先のTeemoに関するJSON呼び出しを覚えていたら、Teemoのidとname、profileIconId、 revisionDate、summonerLevelの正確な値を知ることができるでしょう。

{"teemo": { "id": 35960410, "name": "Teemo", "profileIconId": 0, "revisionDate": 1347299919000, "summonerLevel": 6}}

他のAPIも見て、APIがどんな情報を返してくれるのか確認してみてください。アプリに必要な情報を取得するために、API URLをどのように利用するかは、プログラマーのあなたが決めることになります。

API URLの演習


簡単な演習がないと本当のチュートリアルにはなりません！次の演習をやってみましょう。

Head to the API Documentation. Select the Summoner header, and choose the first one, which is /api/lol/{region}/v1.4/summoner/by-name/{summonerNames}

API仕様を見ましょう。Summonerヘッダーを選択し、最初のAPIメソッドを選びます。

/api/lol/{region}/v1.4/summoner/by-name/{summonerNames}

そのセクションの下に注目してください。regions(na, euw, ru, 等)のドロップダウンボックスとテキストボックスがあります。この入力欄からAPIを呼び出すと、JSONに何が入るか分かります。Request URLも表示されます。（これは、APIキーでリクエストされた情報を返却するリンクです。）

次の名前を入力してください（サーバはNAを指定してください）。入力したら、「Execute Reques」ボタンを押します。（図3）

Teemo, RiotSchmick

（図3）

下のボックスに次のデータが表示されるはずです。
Teemo
Request URL:
https://na.api.pvp.net/api/lol/na/v1.4/summoner/by-name/Teemo?api_key=YOUR_API_KEY

Response Body:
{"teemo": { "id": 35960410, "name": "Teemo", "profileIconId": 0, "revisionDate": 347299919000, "summonerLevel": 6} }
RiotSchmick
Request URL:
https://na.api.pvp.net/api/lol/na/v1.4/summoner/by-name/RiotSchmick?api_key=YOUR_API_KEY

Response Body:
{"riotschmick": { "id": 585897, "name": "RiotSchmick", "profileIconId": 682, "revisionDate": 1406832864000, "summonerLevel": 30}}

次のように、複数の情報を一度に取得することもできます。

https://na.api.pvp.net/api/lol/na/v1.4/summoner/by-name/Teemo,RiotSchmick,SmurfAccount,TSMDyrus?api_key=YOUR_API_KEY

これは、4人のユーザが含まれたResponse Bodyを返します。試してみてください！

この節の最後に、知っておいて欲しいことがあります。プログラムがこの文字列を受け取った時、どのように表示されるか注意してください。またTeemoの情報を例に出します。Request URLをコピーして、ブラウザのアドレスバーに正確に貼り付けてください。上記のようなデータが表示されると思いますが、1行にまとめられ、スペースのない文字列になっているはずです。これが、JSONのデータ形式です。JSONデータを2つのデータ形式で取得する方法を説明します。アプリを作る際、このことに注意してください。

メモ：この節では、JSFiddleというサイトを使います。JSFiddleは、JavascriptとJQuery、AJAX、のようなスクリプトの動作確認を行えます。これから、実際に動作するサンプルコードをお見せします！このチュートリアルで扱う言語であれば、API呼び出しを簡単に試せるサイトです。

Summoner Look Upを見てみてください。やってみましょう！APIキーを入力し、サモナー名を入力してください。面白いですよ。

これは、とても簡単なサモナー検索です。上左のボックスはHTML、下左はスクリプト、上右はCSS、下右は結果／実際に表示される画面です。

ヒント：JSFiddleコードをテストする時は、必ず「JSHint」をクリックしてJavascriptが正しいか確認しましょう。

HTMLを見てみましょう


ここで説明したいことは一つです。inputとspanタグに「id」が付いています。HTMLを知らない場合は、要素を区別するために「id」を付けると考えてください。

ボタンに「onclick」という属性も付いています。文字通り、クリックした時に実行されるという意味です。このサンプルでは、「onclick」が「summonerLookUp()」関数を実行します。

今度はJavascript／AJAXを見てみましょう


最初の行にsummonerLookUp関数があります。このコードはボタンが押された時に実行されます。（onclick="summonerLookUp" ）この関数は最初に、必要となるAPIキーとサモナー名のデータを取得します。ここでは、JQueryで取得しています。次に、AJAX（$.ajax）を使ってAPI URLを作り、入力された情報を中括弧{}に代入します。

ここでのポイントは、AJAXが実行されると、作ったURLへ行き、上記の例で見てきたようなデータを取得します。今はまだ、次のことは無視しても構いません。ただ、成功時とエラー時のコードであるということは知っておいてください。URLが有効であるか（success）、そうでないか（error）によって実行されます。

JSONのデコード


「success」時の動作を理解してもらうことが、この節の主旨です。summonerLevel =と、summonerID =と書かれた箇所です。実は、JSONをデコードして必要なデータを取り出しています。次のコードは、サモナーレベルを取得しています。

json[SUMMONER_NAME_NOSPACES].summonerLevel

今、サモナー名にTeemoと入力しました。サモナーレベルを取得するためのJSONは、json[teemo].summonerLevelとなります。なぜなら、SUMMONER_NAME_NOSPACESは、Teemoという値を保持した変数だからです。

同様に、サモナーIDなら、json[teemo].idとなります。

では、どのように動いたのか少し見てみましょう。API仕様に行き、Teemoのサモナー情報を取得してください。どんな構造か分かります。最初の項目は、「teemo」です。でも、次にあるのは「ネスト」されたデータや中括弧です。中にある中括弧は、その上の属性です。

このサンプルでは、「teemo」は「id」と「name」、「profileIconId」、「revisionDate」、「summonerLevel」の属性を持っています。属性は、ピリオド（.）でアクセスできます。そのため、json[teemo].idは「teemo」の属性「id」を返します。

JSONオブジェクト


では、今見ている「json」とは何でしょう？json[teemo]でしょうか。いえ、Summoner Look Upの「success」関数は、括弧内に「json」を持っています。この括弧内にあるものが、JSONオブジェクトなのです。これは、URLが返却するデータの一式です。もっと長くて複雑なURLを作ると、JSON文字列が長くなることや、属性を使ってデータが格納されていることが分かると思います。

楽しいJSON


改良したバージョンのSummoner Look Up（JSON）を見てください。ボタンを2個追加しました。自分のAPIキーとSummoner NameにTeemoを入力し、送信を押します。その後、別のボタンも押してみてください。

何が返却されましたか？片方は不明なオブジェクト、もう片方はTeemoのデータであるJSON文字列です。

今度は、AJAXコードの変更点を見てみましょう。JSON_encodedは、「json」に入るJSONデータそのもので、URLが取得したオブジェクトです。オブジェクトの全体を見てくださいと言われても、どうなっているのか全く分かりません。ただの「Object」メッセージが返却されています。でも、JSON.stringifyを使えば、文字列に変換できます。Javascriptで、ビルトインJSON関数
の一つを使ってオブジェクトをデコードしています。

もっと演習をしましょう！


同様にオブジェクトを分解していけば、値を取得できます。では次の演習です。

Summoner Look Up Practice 1を見てください。AJAXコードを変更して、サモナー名を表示するために、「sumName」にjsonの値を設定してみましょう。（変更したらUpdateを押すのを忘れずに）

答え　Summoner Look Up Practice 1 - 答え

もう少しこのコードをいじって、別の属性を取得してみてください。習うより慣れましょう！

ネストされたJSONデータ


ここまでのサンプルコードは、かなりシンプルです。なので今度は、ネストされたデータを見てみましょう。前述したように、中括弧は属性を表しています。当然ですが、サモナーは名前、ID、アイコン、等…を一つだけ持っています。そのため、APIで複数の属性を取得する場合、例えばサモナーのマスタリーページを取得する場合。

サモナーのマスタリーページを取得するAPIは、API仕様に書かれています。Summonerを選択したら、/api/lol/{region}/v1.4/summoner/{summonerIds}/masteriesを選択し、ページの下に行ってsummonerIDにRiotSchmickのIDである585897を入力します。（図4）

（図4）

ここで、このIDについて説明させてください。

まず、ID 585897を取得します。「success(json)」内の変数は、json[585897]となります。取得したいデータのページは、このID内にネストされているでしょうか？これは属性なので、json[585897].pagesでアクセスできます。

面白いでしょ！では見てみましょう。pagesの後には、中括弧のネストがある。つまり、「pages」の属性「masteries」を取得するには、どんな変数を入力すればいいでしょうか？…


クリックして答えを見る
json[585897].pages.masteries


JSON配列


今はまだ混乱するかもしれません。マスタリーはネストされたデータな上、複数のIDとランクを持っています。…どうやってデータを区別すればよいでしょうか？そこがJSONのすごいところです。基本的にJSONは、配列でできた文字列です。配列をよく知らない人は、「番号」と値からなるデータの集まりと考えてください。

最初のIDとランクを取得する場合、次のようにします。json[585897].pages.masteries[0]。[0]と書いたのは、0が配列の最初の番号だからです。二番目のIDとランク（4211、2）を取得したい場合は、json[585897].pages.masteries[1]。他の項目も同様です。（図5）

（図5）

APIのデータは、ほとんど配列です。配列がアプリを作るために必要な項目を全て持っています。

他のデモを見てみましょう。Mastery Look Up

これは、Summoner Look Upを元に2つの表示行とletsGetMasteries関数が追加されています。

この関数を一つずつ見ていきましょう。

  1. summonerLookUp() will run, and once it reaches the end of the success we have a new function, letsGetMasteries.



  2. letsGetMasteriesが括弧内にsummonerIDを持っているのは、summonerID（括弧内に入れたものは何でも）を関数内に渡すためです。summonerIDを渡す理由は、マスタリーを取得するAPI URLを確認すると分かりますが、{summonerIDs}という入力欄があるためです。{summonerName}ではありません。幸い、名前を確認した時にサモナーのIDを取得しています。
    APIの組み合わせはなんて面白いのでしょうか！

  3. 面白いと思いました？それでは、下へ行ってletsGetMasteries関数を見てみましょう。別のAJAXを呼び出し、「マスタリー」のURLを作ります。それにサモナーIDと同様に渡したAPIキーを挿入しています。
  4. この関数内では、success(resp)も呼び出しています。どういうことでしょうか？そう、respはJSONオブジェクトを保持した変数で、好きなように使えます。常にこの変数にJSONオブジェクトが保持されていることを覚えておいておいてください。
  5. 次に、HTMLページの表示行に値を設定します。.lengthを使ってマスタリーのページ数を確認します（面白いので）。.lengthは、配列のサイズを返却するJavascriptです。次の行は、resp[summonerID].pages[0].nameです。お察しの通り、これは属性の「name」です。

NestされたJSONの演習


私の名前から次の項目を取得してみてください。

  • 5ページ目の名前
  • 10ページ目の名前、ID、選択中「current」かどうか
Mastery Look Up - 答え

配列データの取得

これからのことを考えると、次のように思うかもしれません。A．自力で全データを取り出すのは辛い、B．どうしたら動的にできるか。最初の10ページを取得するプログラムがあったとします。でも、そのユーザは9ページしか持っていません。それを知ることができれば、エラーにならずに済みます。

Javascriptには、それを事前に確認することができる.lengthやforeachといった優れた関数があります。以下のサンプルコードをチェックしてください。foreachを利用してマスタリーの全ページの名前を取得しています。

Mastery Look Up V2

ほとんど同じですが、Masteries関数の下部にforeachを追加しました。注意深く見てください。foreachは先程の流れで全ての要素を精査します。なので、resp[summonerID].pages.forEach(function(item)) は、「OK、summonerID内のpages内の各要素を調べて、その各要素をitemと名付けます。」という意味です。各要素は別名「masteries」で、「pages」の属性でもあります。

そのため、item.nameは、実際にはresp[summonerID].pages.masteries.nameと同じ意味になります。これがforeachです。実際はresp[summonerID].pages.masteries[0-length].nameを行っているのです。

かなりすごいでしょ！

レート制限


チュートリアルの初めに、アプリケーションが承認されればRiotがレート制限を上げてくれるかもしれないとお話ししました。Dashboardに行くとRate Limit(s)（レート制限（秒））を確認できます。API URLの呼び出し回数は、この割り当てられた上限以内でなければなりません。

例えば、Mastery Look Upでは、2つのAPI呼び出しを使っています。一つはsummonerNameでの呼び出し、もう一つはsummonerID／masteriesでの呼び出し。これで2回呼び出したことになります。もし、何となくプログラムをループして5回実行したら（または、5人のユーザがこの関数を同時に実行したら）、10回呼び出したことになり、10秒内の呼び出し規制が発生します。つまり、10秒で10回呼び出したことが原因で、アプリケーションは10秒間ブロックされます。（図6）

（図6）

良いアプリができたら、Riotが「承認」してくれる可能性があります。そうすれば、上限の高い特別なキーをアプリ用に発行してくれます。（図7）

（図7）

それは、あなたが開発者として正しい形でレート制限を使用した証拠です。とりわけ、一度に多数のユーザが利用する可能性を秘めている場合はなおさらです。

終わりに


ここまで理解できたのであれば、他のAPIを試してみても良いと思います。JSONの学習は、トライ・アンド・エラーです。もしこの先、息詰まって挫折しそうになったら、まずAPI仕様で使っているメソッドを参照し、注意深く見てみてください。頭の中のコードを目に見える形にしましょう。パチッとうまくいくはずです。約束します！

このチュートリアルを楽しんで頂けたでしょうか。もっとチュートリアルをやってみたいと思ったら、コメントして教えて下さい。私はプロの教師ではありませんが、書いていてとても楽しかったです。:D

原文：Lord Imrhial 様（@Lord_Imrhial）

Comments

Post a Comment