RESTful API の使い方

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 は以下に示した通りです。

環境

URI

sandbox

https://sb-connect.mobage.jp/connect/1.0/api/token

service

https://connect.mobage.jp/connect/1.0/api/token

また利用可能な 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 のベースエンドポイントを以下に示します。

環境

Base Endpoint

sandbox

https://sb-app.mobage.jp/social/api/restful/version

service

https://app.mobage.jp/social/api/restful/version

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

API

version

method

Authorization Code Grant

Client Credentials Grant

People

v2

GET

supported

supported

AppData

v2

POST/PUT/DELETE

supported

not supported

AppData

v2

GET

supported

supported

Avatar

v2

GET

supported

supported

TextData

v2

GET/POST/PUT/DELETE

supported

supported

TextDataGroup

v2

GET

supported

supported

TextDataGroup

v2

POST/DELETE

not supported

supported

Profanity

v2

GET

supported

supported

BlackList

v2

GET

supported

not supported

Chat Channel

v2

GET/POST/PUT/DELETE

supported

supported

Chat Member

v2

GET/POST/DELETE

supported

supported

Chat Message

v2

GET

supported

supported

User Chat Channel

v2

GET

supported

not supported

Leaderboard

v2

GET

supported

supported

LeaderboardScore

v2

GET/PUT/DELETE

supported

not supported

Achievement

v2

GET

supported

supported

User Achievement

v2

GET/PUT

supported

not supported

Bank Debit

v2.02

GET/POST/PUT

supported

not supported

Bank Inventory

v2.02

GET

supported

supported

Bank Inventory

v2.02

POST/PUT/DELETE

supported

not supported

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