RESTful API の使い方

This page is not available in English.
Please select another language.

Server-Side 実装について

ここではゲームサーバーの実装方法について説明します。主なトピックとしては以下になります。

  • Access Token と Refresh Token の管理
  • RESTful API の利用

Access Token と Refresh Token の管理

Access Token / Refresh Token とは

Access Token 及び Refresh Token の定義を以下にまとめます。

token

説明

Access Token

RESTful APIを呼び出す際に必要なトークンです。OAuth 2.0 の Bearer Token と呼ばれる形式です。 Mobage Connect では15分間有効です。

Refresh Token

Access Token を再発行する際に必要なトークンです。Refreshing an Access Token - RFC6749 に利用の仕方が定義されています。Mobage Connect では90日間有効です。

Game Server は通常、Authorization Code Grantフローや Hybrid フローで得た code 値を得た上で、 Token Endpoint に渡す事によって Access Token 及び Refresh Token を得ます。
Access Token が失効した場合は、 Refresh Token を利用して Token Request を行うことで、 新たに Access Token を発行します。

Access Token / Refresh Token は、必ず UserAgent 毎に管理してください。
UserId ごとに管理した場合は、SPWeb の処理が Shell App SDK API として動作するなどの問題が発生する可能性がございます。 

Access Token / Refresh Token の文字列長について

Access Token 及び Refresh Token の文字列長は既存の物に対してかなり長い為、例えば MySQL であれば text 型等のデータ型を採用した上で保存して下さい。

Token Endpoint と Client 認証

各環境における Token Endpoint の URI は以下に示した通りです。

また利用可能な Client 認証は以下に示した通りです。

種別

説明

client_secret_basic

Client 認証に Basic 認証を用います。

client_secret_post

Client 認証パラメータを application/x-www-form-urlencoded パラメータに含める方式です。

 

Refresh Token の利用

Access Token が失効した場合に、 Refresh Token を利用して Access Token を再発行します。
 

Access Token が失効しているか確認する

Access Token が失効しているかどうかは、下記の手順で確認します。
Access Token が失効していた場合は、Refresh Token を利用して Access Token を再発行します。
 

expires_in で Token の有効期限が切れているか確認

Access Token の有効期限は、Access Token と共に発行される expires_in 値を利用して確認します。

 

有効期限 = Game Server で Access Token を受け取った時刻 + expires_in 値

 

この有効期限を過ぎている場合は、 Access Token が失効していると判断できます。
 

実際に利用して失効しているか確認

有効期限内だが失効している Access Token を実際に利用した場合、 RESTful API からは以下のレスポンスが返って来ます。

  • HTTP status code : 401 Unauthorized

error_description : "The access token expired"
これらのレスポンスが返って来た場合は、 Access Token が失効していると判断できます。
 

Refresh Token を利用して Access Token を再発行する

Refresh Token を利用する際には Token Endpoint に対して Token Request を送る必要があります。
この際の Token Request で指定する application/x-www-form-urlencoded 形式の key, value を以下に示します。

key

value

grant_type

refresh_token を指定します

refresh_token

Refresh Token 値

例として Client 認証に client_secret_post を利用した例を以下に示します。
この際、 Access Token だけでなく Refresh Token も新しい値が返って来る場合があります。その場合は古い RefreshToken は利用出来なくなりますのでご注意下さい。

 

 

なお、 Token Response の例を以下に示します。

 

key

value

access_token

Game Server から API を実行するための access_token が返されます。

token_type

Bearer

expires_in

900

refresh_token

grant_type=refresh_token による Token Request で改めて access token を得る為に必要なトークンです。発行時から90日間有効です。

scope

現在、クライアント向けに認可されているユーザーに関する権限を全て示すスペース区切りの文字列です。

 

Client Credentials Grant 

Client Credentials Grant とは

Client Credentials Grant とは、Client 認証のみで Client 向けの API 実行権限である Access Token を得る為のフローで、 OAuth 2.0 で規定されています。
旧来の Proxy Server モデルでは Trusted モデルと呼ばれていた Using OAuth for Consumer Request に対応する概念です。
Client Credentials Grant では特にユーザーに紐づく権限を得る訳ではないので、Client 向けの secret があれば Token Endpoint にアクセスするだけで Access Token を得る事が出来ます。
サポートしている Client 認証手段に関しては以下表を参照して下さい。
 

key

value

grant_type

client_credentialsを指定します

 
Client 認証で client_secret_post を用いる場合は以下のようなリクエストになります。

 

 

Token Request が成功の場合は Token Response として以下のフィールドがJSONとして返って来ます。

key

value

access_token

Game Server から API を実行する為の access token が返されます。

token_type

Bearer

expires_in

900

Client Credentials Grant では、refresh_token は発行されません。

 

得られた Access Token は Authorization Code Grant で得られた物と違って、特定のユーザーに紐づく物ではなく Client のみに紐づく権限なので、一緒に管理はしないようにして下さい。
Token Request が失敗した場合は Token Error Response として、以下に示すパラメータが JSON として返って来ます。

key

value

error

OAuth 2.0/OpenID Connect 1.0 で定義されるエラーコードが指定されます。

error_description

error 内容を説明する文章が指定されます。

 

RESTful API の利用

ここでは JavaScript SDK または Mobage Connect を利用した場合の RESTful API について説明します。

利用可能な RESTful API とエンドポイント

各環境の RESTful API のベースエンドポイントを以下に示します。

また利用可能な Authorization Code Grant で得た Access Token と、Client Credentials Grant で得た Access Token とで異なります。詳細は以下を参照して下さい。
各 API のインターフェースについてはそれぞれのドキュメントを参照して下さい。

API

version

method

Authorization Code Grant

Client Credentials Grant

Description

People

v2

GET

supported

supported

ユーザーのプロフィール情報及び、ユーザーの友達一覧を取得する為のAPIです。

AppData

v2

POST/PUT/DELETE

supported

not supported

ユーザーごとに割り当てられた永続データ保存 API です。

AppData

v2

GET

supported

supported

ユーザーごとに割り当てられた永続データ取得 API です。

Avatar

v2

GET

supported

supported

アバター画像や swf の URL を取得する API です。

TextData

v2

GET/POST/PUT/DELETE

supported

supported

ユーザーからの自由文入力を取得・保存する API です。保存されているテキストは監視対象となります。

TextDataGroup

v2

GET

supported

supported

TextData オブジェクトをグルーピングするための TextDataGroup を取得する API です。

TextDataGroup

v2

POST/DELETE

not supported

supported

TextData オブジェクトをグルーピングするための TextDataGroup を保存・削除する API です。

Profanity

v2

GET

supported

supported

指定されたテキストに不適切な言葉が含まれるかチェックする API です。

BlackList

v2

GET

supported

not supported

BlackList API では、特定のユーザーがアプリケーションをインストールしているユーザーの中でブラックリストに登録しているユーザーを取得します。

Chat Channel

v2

GET/POST/PUT/DELETE

supported

supported

チャットのチャンネルを操作する為の API です。

Chat Member

v2

GET/POST/DELETE

supported

supported

チャットの参加者を管理する為の API です。

Chat Message

v2

GET

supported

supported

チャットのメッセージを操作する API です。

User Chat Channel

v2

GET

supported

not supported

ユーザーが参加しているチャンネルとチャンネルとユーザー間で関連する情報を管理する為の API です。

Leaderboard

v2

GET

supported

supported

リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなう API です。

LeaderboardScore

v2

GET/PUT/DELETE

supported

not supported

リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなう API です。

Achievement

v2

GET

supported

supported

Achievement API を用いると、Mobage Developers に設定された Achievement の オブジェクトを取得することができます。

User Achievement

v2

GET/PUT

supported

not supported

User Achievement API とは、定義された Achievement に対してのユーザーの達成状況を取得、更新することのできる API です。

Bank Debit

v2.02

GET/POST/PUT

supported

not supported

ゲーム内仮想通貨でアイテム購入をおこなう API です。トランザクションの作成とキャンセルを処理します。

Bank Inventory

v2.02

GET

supported

supported

ゲームアイテム情報の取得をおこなう API です。

Bank Inventory

v2.02

POST/PUT/DELETE

supported

not supported

ゲームアイテム情報の作成/更新/削除をおこなう API です。

Client Credentials Grant を使用すれば、Mobage 非会員の状態でもテキストデータの作成・更新・削除が行えますが、Mobage 非会員の状態ではテキストデータの取得以外は行わないでください。

 

Authorization

RESTful APIに対しては現状以下のAuthorizationが許可されています。

  • Authorization Code Grant または Hybrid によって得られた code を用いて得られた Access Token
    Refresh Token を利用して得られた Access Token
  • ゲームサーバーから API  サーバーへのリクエスト - Mobage Developers の Trusted モデル

Access Token は既存のモデルの Proxy モデルの代わりに利用する事が出来ます。

取得した Access Token は以下のように Authorization ヘッダ中に Auth Schema を Bearer とした上で指定して下さい

 



 

PREVIOUS

RESTful API

NEXT

People