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 開発環境か製品環境かを指定します。開発環境の場合 “dd1” を、製品環境の場合は “lp1” を指定してください。
GameServerID OMAS で表示されるゲームサーバ ID を指定します。先頭の “0x” は不要です。
ResourceURLPath 12.1.3. リソース URL パス 」を参照してください。

リクエストにはアクセストークンが必要になります。アクセストークンには有効期限が無制限のものと、1 時間の制限があるものがあります。時間制限ありのトークンを使用する場合には、有効期限を確認し、必要であれば使用する前にリフレッシュトークンを使用してアクセストークンを更新してください。 セキュリティの観点から、有効期限 1 時間のものを、リフレッシュしながら使用することをお奨めします。

注意

無期限のトークンを使用する場合には、開発者のユーザーで取得したアクセストークンを使用せず、ゲームタイトル専用のアカウントを作成して、そのアカウントで取得したアクセストークンを使用してください。アクセストークンは、発行したユーザーの権限を継承するため、発行したユーザーが異動、退職するなどで、権限を失ったりした場合にアクセストークンが無効化されます。

12.1.7.1. WebAPI ゲートウェイ経由でのリクエスト例

以下の条件で、WebAPI ゲートウェイ経由の WebAPI リクエストを行う場合の例です。

要素名 内容
GameServerID 0x1234abcd
Environment dd1
Access Token abcd123456
Function データ ID が 123456 のメタ情報を取得する

この条件で リクエストを行うには以下のリクエストを実行します

GET https://dd1api.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://dd1api.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>