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 毎に管理してください。 |
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 | Description |
---|---|---|---|---|---|
v2 | GET | supported | supported | ユーザーのプロフィール情報及び、ユーザーの友達一覧を取得する為のAPIです。 | |
v2 | POST/PUT/DELETE | supported | not supported | ユーザーごとに割り当てられた永続データ保存 API です。 | |
v2 | GET | supported | supported | ユーザーごとに割り当てられた永続データ取得 API です。 | |
v2 | GET | supported | supported | アバター画像や swf の URL を取得する API です。 | |
v2 | GET/POST/PUT/DELETE | supported | supported | ユーザーからの自由文入力を取得・保存する API です。保存されているテキストは監視対象となります。 | |
v2 | GET | supported | supported | TextData オブジェクトをグルーピングするための TextDataGroup を取得する API です。 | |
v2 | POST/DELETE | not supported | supported | TextData オブジェクトをグルーピングするための TextDataGroup を保存・削除する API です。 | |
v2 | GET | supported | supported | 指定されたテキストに不適切な言葉が含まれるかチェックする API です。 | |
v2 | GET | supported | not supported | BlackList API では、特定のユーザーがアプリケーションをインストールしているユーザーの中でブラックリストに登録しているユーザーを取得します。 | |
v2 | GET/POST/PUT/DELETE | supported | supported | チャットのチャンネルを操作する為の API です。 | |
v2 | GET/POST/DELETE | supported | supported | チャットの参加者を管理する為の API です。 | |
v2 | GET | supported | supported | チャットのメッセージを操作する API です。 | |
v2 | GET | supported | not supported | ユーザーが参加しているチャンネルとチャンネルとユーザー間で関連する情報を管理する為の API です。 | |
v2 | GET | supported | supported | リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなう API です。 | |
v2 | GET/PUT/DELETE | supported | not supported | リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなう API です。 | |
v2 | GET | supported | supported | Achievement API を用いると、Mobage Developers に設定された Achievement の オブジェクトを取得することができます。 | |
v2 | GET/PUT | supported | not supported | User Achievement API とは、定義された Achievement に対してのユーザーの達成状況を取得、更新することのできる API です。 | |
v2.02 | GET/POST/PUT | supported | not supported | ゲーム内仮想通貨でアイテム購入をおこなう API です。トランザクションの作成とキャンセルを処理します。 | |
v2.02 | GET | supported | supported | ゲームアイテム情報の取得をおこなう API です。 | |
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 とした上で指定して下さい