Achievement API
概要
Achievement API を用いると、Mobage Developers に設定された Achievement の オブジェクトを取得することができます。
Achievement には、Achievement ID を指定しないで取得する方法と、Achievement ID を指定して取得する方法の 2 通りがあり、それぞれリクエスト方法が異なります。
Achievement API の使い方
Achievement API の詳細な使い方について、下記の各ページをご参照下さい。
ngCore SDK | Native SDK | Unity SDK
Achievement オブジェクトフィールド
Achievement を表すオブジェクトになります。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| appId | アプリケーション識別子 | string | ||
| id | アチーブメント識別子 | string | ||
| name | 名称 | string | ||
| revealedDescription | REVEALED の際の説明文 | string | ||
| unlockedDescription | UNLOCKED の際の説明文 | string | ||
| type | アチーブメント種別 | string | ||
| totalSteps | 達成までのステップ数 | integer | ||
| stepFormat | ステップの表示上の単位 | string | ||
| point | 獲得ポイント | integer | ||
| repeatable | 反復可能フラグ | boolean | ||
| disclosed | 公開状態フラグ | boolean | ||
| defaultState | 初期ステート値 | string | ||
| revealedIconUrls | REVEALED の際の画像 url リスト | array | ||
| revealedIconUrls[].type | REVEALED の際の画像タイプ | string | ||
| revealedIconUrls[].value | REVEALED の際の画像 url | string | ||
| revealedIconUrls[].primary | REVEALED の際の画像の優先度 | boolean | ||
| unlockedIconUrls | UNLOCKED の際の画像 url リスト | array | ||
| unlockedIconUrls[].type | UNLOCKED の際の画像タイプ | string | ||
| unlockedIconUrls[].value | UNLOCKED の際の画像 url | string | ||
| unlockedIconUrls[].primary | UNLOCKED の際の画像の優先度 | boolean | ||
| published | 作成日時 | string | ||
| updated | 更新日時 | string |
Achievement を指定しないで取得する方法
API リクエスト
HTTP メソッド
Trusted モデル (2-legged)
- GET
- Achievement を指定しないで取得する
Proxy モデル (3-legged)
- GET
- Achievement を指定しないで取得する
エンドポイント
-
Sandbox 環境
http://sb.sp.app.mbga.jp/social/api/restful/v2/achievements{/appId}{?format,startIndex,count,sortBy,sortOrder,fields} -
本番環境
http://sp.app.mbga.jp/social/api/restful/v2/achievements{/appId}{?format,startIndex,count,sortBy,sortOrder,fields}
エンドポイント
-
Sandbox 環境
http://sb.sp.mbga-platform.jp/social/api/restful/v2/achievements{/appId}{?format,startIndex,count,sortBy,sortOrder,fields} -
本番環境
http://sp.mbga-platform.jp/social/api/restful/v2/achievements{/appId}{?format,startIndex,count,sortBy,sortOrder,fields}
URI Template パラメータ
appId
appId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @app | 現在実行中のアプリケーション ID | 必須 |
| {appId} | 個々に割り振られたアプリケーション ID | 必須 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。json のみ指定可能です。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
fields
取得したいプロフィール属性情報を指定する事が出来ます。指定可能なフィールド名については Achievement オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fields パラメータを省略した場合、下記の属性情報全てを取得します。
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。何も指定しない場合に取得できるデフォルトフィールドは以下になります。
["id", "type", "point"]
count
コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。selector に @friends, @all を指定した場合に指定出来ます。
デフォルト値は 50 件で、最大 1000 件まで指定出来ます。
startIndex
コレクションリソースの開始値を指定します。省略時は 1 が指定されます。例えば、全体で 100 件ある友達情報のページ送りで 1 ページ辺り 8 件表示し、2 ページ目の情報を取得したい場合、count 値に 8 を指定し、startIndex 値に 9 を指定します。
sortBy
sortBy と sortOrder を指定すると、レスポンスとして返って来る Achievement オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。
指定可能な sortBy 値は以下の表になります。
| sortBy | 説明 |
|---|---|
| id | アチーブメント識別子 |
| point | 獲得ポイント |
sortBy を指定する場合、sortOrder も指定されている必要があります。
sortOrder
sortBy と sortOrder を指定すると、レスポンスとして返って来る Achievement オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソート時の昇順、降順を指定する事が出来ます。
指定可能な sortOrder 値は以下の表になります。
| sortOrder | 説明 |
|---|---|
| ascending | 昇順 |
| descending | 降順 |
sortOrder を指定する場合、sortBy も指定されている必要があります。
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | 正常にデータ取得が完了しました |
| GET | 400 | Bad Request | リクエストデータが不正です |
| GET | 401 | Unauthorized | OAuth による認可が失敗しています |
| GET | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| GET | 405 | Method Not Allowed | メソッドが許可されていません |
| GET | 500 | Internal Server Error | API 側の問題による失敗です |
| GET | 503 | Service Unavailable | API 側の一時的なエラーです |
レスポンスのデータ構造
API のレスポンスの payload として返されるデータ構造です。
| property | title | type | description |
|---|---|---|---|
| entry | Achievement リソースのリスト | array | |
| entry[].appId | アプリケーション識別子 | string | |
| entry[].id | アチーブメント識別子 | string | |
| entry[].name | 名称 | string | |
| entry[].revealedDescription | REVEALED の際の説明文 | string | |
| entry[].unlockedDescription | UNLOCKED の際の説明文 | string | |
| entry[].type | アチーブメント種別 | string | |
| entry[].totalSteps | 達成までのステップ数 | integer | |
| entry[].stepFormat | ステップの表示上の単位 | string | |
| entry[].point | 獲得ポイント | integer | |
| entry[].repeatable | 反復可能フラグ | boolean | |
| entry[].disclosed | 公開状態フラグ | boolean | |
| entry[].defaultState | 初期ステート値 | string | |
| entry[].revealedIconUrls | REVEALED の際の画像 url リスト | array | |
| entry[].revealedIconUrls[].type | REVEALED の際の画像タイプ | string | |
| entry[].revealedIconUrls[].value | REVEALED の際の画像 url | string | |
| entry[].revealedIconUrls[].primary | REVEALED の際の画像の優先度 | boolean | |
| entry[].unlockedIconUrls[] | UNLOCKED の際の画像 url リスト | array | |
| entry[].unlockedIconUrls[].type | UNLOCKED の際の画像タイプ | string | |
| entry[].unlockedIconUrls[].value | UNLOCKED の際の画像 url | string | |
| entry[].unlockedIconUrls[].primary | UNLOCKED の際の画像の優先度 | boolean | |
| entry[].published | 作成日時 | string | |
| entry[].updated | 更新日時 | string | |
| startIndex | 開始インデックス | integer | |
| itemsPerPage | ページごとのエントリ数 | integer | |
| totalResults | 総エントリ数 | integer | |
| sorted | ソート適用フラグ | boolean | ソートが適用された場合に true になります。(Default では id でソートされるため、常に true になります) |
サンプル
count パラメータを指定した場合
リクエスト形式
GET /achievements/@app?count=5
Authorization: OAuth oauth_parameters
レスポンス形式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"entry": [
{ "id": 1, "type": "INCREMENTAL", "point": 1000 },
{ "id": 2, "type": "STANDARD", "point": 250 },
{ "id": 3, "type": "INCREMENTAL", "point": 370 },
{ "id": 4, "type": "INCREMENTAL", "point": 120 },
{ "id": 5, "type": "STANDARD", "point": 110 }
],
"startIndex": 1,
"itemsPerPage": 5,
"totalResults": 12
}
sortBy, sortOrder を指定した場合
リクエスト形式
GET /achievements/@app?sortBy=point&sortOrder=descending&count=5
Authorization: OAuth oauth_parameters
レスポンス形式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"entry": [
{ "id": 1, "type": "INCREMENTAL", "point": 1000 },
{ "id": 3, "type": "INCREMENTAL", "point": 370 },
{ "id": 2, "type": "STANDARD", "point": 250 },
{ "id": 4, "type": "INCREMENTAL", "point": 120 },
{ "id": 5, "type": "STANDARD", "point": 110 }
],
"startIndex": 1,
"itemsPerPage": 5,
"totalResults": 12
}
Achievement を指定して取得する方法
API リクエスト
HTTP メソッド
Trusted モデル (3-legged)
- GET
- Achievement を指定して取得する
Proxy モデル (2-legged)
- GET
- Achievement を指定して取得する
エンドポイント
-
Sandbox 環境
http://sb.sp.app.mbga.jp/social/api/restful/v2/achievements{/appId,id}{?format,fields} -
本番環境
http://sp.app.mbga.jp/social/api/restful/v2/achievements{/appId,id}{?format,fields}
エンドポイント
-
Sandbox 環境
http://sb.sp.mbga-platform.jp/social/api/restful/v2/achievements{/appId,id}{?format,fields} -
本番環境
http://sp.mbga-platform.jp/social/api/restful/v2/achievements{/appId,id}{?format,fields}
URI Template パラメータ
appId
appId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @app | 現在実行中のアプリケーション ID | 必須 |
| {appId} | 個々に割り振られたアプリケーション ID | 必須 |
アチーブメント識別子
アチーブメントリソースの識別子です。
| 値 | 説明 | 備考 |
|---|---|---|
| id | string, array[string] | 必須 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。json のみ指定可能です。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
fields
取得したいプロフィール属性情報を指定する事が出来ます。指定可能なフィールド名については Achievement オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fields パラメータを省略した場合、下記の属性情報全てを取得します。
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。何も指定しない場合に取得できるデフォルトフィールドは以下になります。
["id", "type", "point"]
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | 正常にデータ取得が完了しました |
| GET | 400 | Bad Request | リクエストデータが不正です |
| GET | 401 | Unauthorized | OAuth による認可が失敗しています |
| GET | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| GET | 405 | Method Not Allowed | メソッドが許可されていません |
| GET | 500 | Internal Server Error | API 側の問題による失敗です |
| GET | 503 | Service Unavailable | API 側の一時的なエラーです |
レスポンスのデータ構造
API のレスポンスの payload として返されるデータ構造です。
| property | title | type | description |
|---|---|---|---|
| entry | Achievement リソースのリスト | array | |
| entry[].appId | アプリケーション識別子 | string | |
| entry[].id | アチーブメント識別子 | string | |
| entry[].name | 名称 | string | |
| entry[].revealedDescription | REVEALED の際の説明文 | string | |
| entry[].unlockedDescription | UNLOCKED の際の説明文 | string | |
| entry[].type | アチーブメント種別 | string | |
| entry[].totalSteps | 達成までのステップ数 | integer | |
| entry[].stepFormat | ステップの表示上の単位 | string | |
| entry[].point | 獲得ポイント | integer | |
| entry[].repeatable | 反復可能フラグ | boolean | |
| entry[].disclosed | 公開状態フラグ | boolean | |
| entry[].defaultState | 初期ステート値 | string | |
| entry[].revealedIconUrls | REVEALED の際の画像 url リスト | array | |
| entry[].revealedIconUrls[].type | REVEALED の際の画像タイプ | string | |
| entry[].revealedIconUrls[].value | REVEALED の際の画像 url | string | |
| entry[].revealedIconUrls[].primary | REVEALED の際の画像の優先度 | boolean | |
| entry[].unlockedIconUrls[] | UNLOCKED の際の画像 url リスト | array | |
| entry[].unlockedIconUrls[].type | UNLOCKED の際の画像タイプ | string | |
| entry[].unlockedIconUrls[].value | UNLOCKED の際の画像 url | string | |
| entry[].unlockedIconUrls[].primary | UNLOCKED の際の画像の優先度 | boolean | |
| entry[].published | 作成日時 | string | |
| entry[].updated | 更新日時 | string | |
| startIndex | 開始インデックス | integer | |
| itemsPerPage | ページごとのエントリ数 | integer | |
| totalResults | 総エントリ数 | integer | |
| sorted | ソート適用フラグ。 | boolean | ソートが適用された場合に true になります。(ソートを指定することができないので常に false となります) |
サンプル
fields パラメータを指定した場合
リクエスト形式
GET /achievements/@app/largest_army?fields=id,name,type,point,totalSteps,stepFormat
Authorization: OAuth oauth_parameters
レスポンス形式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"id": "largest_army",
"name": "最大騎士力",
"type": "INCREMEMTAL",
"point": 100,
"totalSteps": 10,
"stepFormat": "撃破"
}
idパラメータのみを指定した場合
リクエスト形式
GET /achievements/@app/largest_army,longest_road?fields=id,name,type,point,totalSteps,stepFormat
Authorization: OAuth oauth_parameters
レスポンス形式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"entry": [
{
"id": "largest_army",
"name": "最大騎士力",
"type": "INCREMEMTAL",
"point": 100,
"totalSteps": 10,
"stepFormat": "撃破"
},
{
"id": "longest_road",
"name": "最長交易路",
"type": "STANDARD",
"point": 120,
"totalSteps": 1,
"stepFormat": ""
}
],
"startIndex": 1,
"itemsPerPage": 2,
"totalResults": 2
}
更新履歴
- 2013/10/03
- 新規作成