12.1. WebAPIの使用
ここでは、WebAPI の使用方法と、使用する際の注意点について記します。
12.1.1. WebAPI の用途について
NEX の WebAPI はゲームサーバー上のデータ管理に使用することができます。WebAPI を使用することで、データの集計や定期的なデータのポスト、削除等を行うことができます。また、管理目的で提供しているため、アクセス回数はタイトル毎に 1 分 1 リクエストとしてください。WebAPI をクライアントからの要求によるリクエストとして実行したり、高頻度での更新するような目的では使用できません。
- 以下のような用途に使用できます。
- データストアの評価値を 1 日 1 回集計して Web ページに表示させる
- データストアに投稿されたデータを 1 日 1 回管理用サーバーに移動させる
- 一定の期間より古い評価データを削除する
- 以下のような用途には使用できません。
- クライアントが独自サーバーに特定のデーターを取得するための要求を行い、独自サーバがそれを受けて WebAPI を発行してリクエストを行う
- 特定の時刻にデータストアのデータを一斉に入れ替える( 1 分間に 1 回を超えるアクセスが必要)
- Webサービスで、ユーザーのリクエストに応じて WebAPI のリクエストを発行させる。
アプリケーションがどちらのケースに該当するか不明な場合はお問い合わせください。
12.1.2. WebAPI へのアクセスについて
WebAPI を使用するためには、OMAS への Web サービス使用申請が必要です。サービスの使用が承認されると、WebAPI を使用するために必要な OAuth 2.0 用のアクセストークンを生成できるようになります。詳しい手続きは OMAS の「使い方」を参照してください。
12.1.3. リソース URL パス
通常、API のリソース URL パスは以下のように構成されます。
/nex/{moduleName}/v{version}/{apiPath}
要素名 内容 moduleName モジュール名 version APIバージョン apiPath 各APIのパス
例えば、バージョン 2 のデータストア API で検索をする場合は、以下のようになります。
/nex/datastore/v2/search
ただし、バージョンを取得する API など、一部にはバージョン指定はありません。
/nex/datastore/version
12.1.4. リクエスト
12.1.4.1. リクエストメソッド
リクエストメソッドには、GET, POST, PUT, DELETE を使用します。 使用するメソッドは API 毎に異なり、リクエストパラメーターの渡し方やフォーマットもそれぞれ異なります。
12.1.4.2. パラメーター・リクエストボディ
パラメーターを渡すには、通常、GETの場合はクエリ文字列を、POST, PUT の場合はXMLフォーマットでリクエストボディを使用します。 XML フォーマットでリクエストを行うときは、ヘッダに “Content-type: text/xml” を指定してください。 DELETE の場合はこれらを使用しません。
リクエスト例:
データストアで、データ ID 10 のメタ情報をタグ付きで取得する (GET)
GET /nex/datastore/v2/metainfo/10?response=tag HTTP/1.1
データストアで、データID 10 の名前を”new name”に変更する (PUT)
PUT /nex/datastore/v2/metainfo/10 HTTP/1.1 <change> <name>new name</name> </change>
12.1.4.2.1. 複数値
APIの中には、複数の値を指定出来るものがあります。 複数の値を指定するには、通常、GET の場合は,(カンマ)区切り、POST, PUT の場合はXMLで要素を複数使用します。
リクエスト例:
データストアで、データID 10, 20, 30 のメタ情報を取得する (GET)
GET /nex/datastore/v2/metainfo?data_ids=10,20,30 HTTP/1.1
データストアで、データID 10 のタグを”tag1”, “tag2”に変更する (PUT)
PUT /nex/datastore/v2/metainfo/10 HTTP/1.1 <change> <tags> <tag>dGFnMQ==</tag> <tag>dGFnMg==</tag> </tags> <param> <data_id>10</data_id> </param> </change>
12.1.5. レスポンス
12.1.5.1. ステータスコード
リクエストの実行結果には、主に以下のステータスコードが使用されます。
ステータスコード | 内容 |
---|---|
200 | 正常終了 |
400 | リクエストしたパラメータが不正 |
404 | 指定したパスが存在しない |
500 | 内部エラー |
12.1.5.2. 内容
詳細な実行結果と内容は、XML フォーマットで返されます。 API の実行に成功すると、以下のような内容となります。
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<module>
<!-- レスポンス内容 -->
</module>
</nex>
上記の <module> はモジュール名を表しており、例えば、データストアの場合は以下の通りとなります。
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<datastore>
<!-- レスポンス内容 -->
</datastore>
</nex>
エラーとなった場合には、以下の内容が返されます。
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<errors>
<error>
<errorcode><!-- エラーコード --></errorcode>
<message><!-- エラーメッセージ --></message>
</error>
</errors>
</nex>
12.1.6. 特殊なリクエスト・レスポンスデータの取り扱い
一部の API では、データを引数として渡す際には加工して渡す必要があります。 また、結果として受け取る際も同様で、データは加工されたものが返されます。
12.1.6.1. Base64エンコード
Base64 エンコードを使用する際には、RFC 3548 に基づいてエンコードしてください。 さらに、エンコードしたデータを URL Safe な形式にする必要があります。
Base64 エンコードする際は、以下の点に注意してください。
- パディング = を使用する(必要な場合)
- 改行文字は使用しない
URL Safeとするルールは以下の通りです。
- + のかわりに - を使用
- / のかわりに _ を使用
変換例:
- 文字列 “NEX WebAPI” をエンコード
- NG: TkVYIFdlYkFQSQ (パディングがない)
- OK: TkVYIFdlYkFQSQ==
- 0x3c, 0x3d, 0x3e, 0x3f のバイト列をエンコード
- NG: PD0+Pw (URL Safeでなく、パディングがない)
- NG: PD0+Pw== (URL Safeでない)
- NG: PD0-Pw (パディングがない)
- OK: PD0-Pw==
12.1.7. WebAPI ゲートウェイ経由でのリクエストについて
WebAPI を使用するためには、WebAPI ゲートウェイ経由でのゲームサーバーへのアクセスが必要となります。WebAPI ゲートウェイ経由でのゲームサーバーへのリクエストは、以下の URL に対して行います。
https://{Environment}api.nex.mng.nintendo.net/v4_0/{GameServerId}/{ResourceURLPath}
要素名 内容 Environment 開発環境か製品環境かを指定します。開発環境の場合 “d” を、製品環境の場合は “l” を指定してください。 GameServerID OMAS で表示されるゲームサーバー ID を指定します。先頭の “0x” は不要です。 ResourceURLPath 「 12.1.3. リソース URL パス 」を参照してください。
リクエストにはアクセストークンが必要になります。アクセストークンには有効期限が無制限のものと、1 時間の制限があるものがあります。時間制限ありのトークンを使用する場合には、有効期限を確認し、必要であれば使用する前にリフレッシュトークンを使用してアクセストークンを更新してください。 セキュリティの観点から、有効期限 1 時間のものを、リフレッシュしながら使用することをお奨めします。
注意
無期限のトークンを使用する場合には、開発者のユーザーで取得したアクセストークンを使用せず、ゲームタイトル専用のアカウントを作成して、そのアカウントで取得したアクセストークンを使用してください。アクセストークンは、発行したユーザーの権限を継承するため、発行したユーザーが異動、退職するなどで、権限を失ったりした場合にアクセストークンが無効化されます。
12.1.7.1. WebAPI ゲートウェイ経由でのリクエスト例
以下の条件で、WebAPI ゲートウェイ経由の WebAPI リクエストを行う場合の例です。
要素名 | 内容 |
---|---|
GameServerID | 0x1234abcd |
Environment | d |
Access Token | abcd123456 |
Function | データ ID が 123456 のメタ情報を取得する |
この条件で リクエストを行うには以下のリクエストを実行します
GET https://dapi.nex.mng.nintendo.net/v4_0/1234abcd/nex/datastore/v2/metainfo/123456
Authorization: OAuth abcd123456
cURL を使用する場合には、以下のようにリクエストを行います
curl -H "Authorization: OAuth abcd123456" --proxy http://<proxy_address>:<proxy_port> https://dapi.nex.mng.nintendo.net/v4_0/1234abcd/nex/datastore/v2/metainfo/123456
GET リクエストに成功した場合次のような応答が返ります
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<datastore>
<metainfos length="1">
<metainfo>
<status>0</status>
<referred_time>2013-01-01T00:00:00Z</referred_time>
<referred_cnt>0</referred_cnt>
<prev_version>0</prev_version>
<data_type>0</data_type>
<refer_data_id>0</refer_data_id>
<data_id>xxxxxxx</data_id>
<cur_version>x</cur_version>
<access_permission>
<type>0</type>
<principal_ids length="0"/>
</access_permission>
<period>365</period>
<update_permission>
<type>3</type>
<principal_ids length="0"/>
</update_permission>
<name>TDSS</name>
<expire_time>2013-02-01T00:00:00Z</expire_time>
<flag>34</flag>
<read_lock_id>0</read_lock_id>
<created_time>2013-01-01T00:00:00Z</created_time>
<owner_id>xxxxxxxxxx</owner_id>
<updated_time>2013-01-01T00:00:00Z</updated_time>
<size>0</size>
</metainfo>
</metainfos>
</datastore>
</nex>
エラーが発生した場合には次のような応答が返ります
<?xml version="1.0" encoding="UTF-8"?>
<nex>
<errors>
<error>
<errorcode>-1</errorcode>
<message>qResult(0x80690004) Not found. Data Ids are [xxxxL]</message>
</error>
</errors>
</nex>
不正なアクセストークンを使用した場合など、認証に失敗した場合には次のような応答が返ります
<?xml version="1.0"?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>403</int></value>
</member>
<member>
<name>faultString</name>
<value><string>Forbidden (Proxy)</string></value>
</member>
</struct>
</value>
</fault>
</methodResponse>