User Achievement
This page is not available in English.
Please select another language.
概要
User Achievement API とは、定義された Achievement に対してのユーザーの達成状況を取得、更新することのできる API です。
User Achievement API では、以下の操作が可能となります。
- User Achievement を取得する
- User Achievement を更新する
User Achievement オブジェクトフィールド
User Achievement を表すオブジェクトになります。
値 |
説明 |
型 |
書き込み不可 |
補足 |
---|---|---|---|---|
userId |
ユーザー ID |
integer |
TRUE |
|
appId |
アプリケーション ID |
string |
TRUE |
|
achievementId |
Achievement ID |
string |
TRUE |
|
state |
状態 |
string |
FALSE |
|
steps |
進捗度 |
integer |
FALSE |
|
numOfUnlocked |
Unlock した回数 |
integer |
TRUE |
|
published |
作成日時 |
string |
TRUE |
|
updated |
更新日時 |
string |
TRUE |
|
Increment User Achievement オブジェクトフィールド
値 |
説明 |
型 |
書き込み不可 |
補足 |
---|---|---|---|---|
steps |
進捗度の差分値 |
integer |
false |
負数を含む整数が指定可能。 |
API リクエスト
HTTP メソッド
Authorization Code Grant
- GET
- 任意のユーザーのアプリ内で作成・更新した事のある User Achievement コレクションを取得する
- 任意のユーザーの User Achievement コレクションを Achievement ID を指定して取得する
- PUT
- 任意のユーザーの User Achievement オブジェクトを Achievement ID を指定して作成・更新する
Client Credentials Grant
- サポートしていません。
任意のユーザーのアプリ内で作成・更新した事のある User Achievement コレクションを取得する (GET)
エンドポイント
- Sandbox 環境
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@friends/achievements{/appId,achievementId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}
- 本番環境
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@friends/achievements{/appId,achievementId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}
URI Template パラメータ
userId
userId パラメータは下記のいずれかの値を指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
@me |
viewer の userId |
string |
必須 |
{userId} |
ユーザー ID |
string or array |
必須 |
self or friends
self or friends パラメータは下記のいずれかの値を指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
@self |
userId パラメータで指定したユーザー自身の User Achievement オブジェクトを取得する場合 |
string |
必須 |
@friends |
userId パラメータで指定したユーザーの友達の User Achievement コレクションを取得する場合 |
string |
必須 |
appId
appId パラメータは下記のいずれかの値を指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
@app |
現在実行中のアプリケーション ID |
string |
必須 |
{appId} |
個々に割り振られたアプリケーション ID |
string |
必須 |
achievementId
achievementId パラメータには以下を指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
{achievementId} |
任意の Achievement に対しての User Achievement コレクションを取得したい場合に指定します。 |
string or array |
任意 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。json のみ指定可能です。
値 |
説明 |
型 |
備考 |
---|---|---|---|
json |
"application/json; charset=utf8" |
string |
任意、デフォルト値 |
count
コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。
値 |
説明 |
型 |
備考 |
---|---|---|---|
count |
デフォルト値は 50 件で、最大 1000 件まで指定出来ます。 |
integer |
任意 |
※パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。
filterBy
filterBy は User Achievement コレクションの取得時にのみ使う事が出来ます。
filterBy を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterBy 値は検索条件のキーとなるフィールドを指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
filterBy |
条件を付けたいフィールド名を指定します。"state" のみ指定可能です。 |
string |
任意 |
現在指定可能な filterBy 値は以下の表になります。
filterBy |
説明 |
---|---|
state |
UserAchievement#state |
filterBy を指定する場合、filterOp, filterValue も指定されている必要があります。
filterOp
filterOp は User Achievement コレクションの取得時にのみ使う事が出来ます。
filterOp を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterOp 値は検索条件のキーと値に対してどのような評価を行うかを指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
filterOp |
評価する条件を指し示す演算子を指定します。"equals" のみ指定可能です。省略した場合は "equals" が指定されたとみなします。 |
string |
任意 |
filterOp を指定する場合、filterBy, filterValue も指定されている必要があります。
filterValue
filterValue は User Achievement コレクションの取得時にのみ使う事が出来ます。
filterValue を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterValue 値は検索条件のキーに対して、どのような値と評価するかを指定する事ができます。
値 |
説明 |
型 |
備考 |
---|---|---|---|
filterValue |
評価する値を指定します。"HIDDEN", "REVEALED", "UNLOCKED" が指定可能です。 |
string |
任意 |
filterValue を指定する場合、filterBy, filterOp も指定されている必要があります。
sortBy
sortBy は User Achievement コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。
値 |
説明 |
型 |
備考 |
---|---|---|---|
sortBy |
並べ替えのキーとなるフィールド名を指定します。"userId", "achievementId", "updated" のみ指定可能です。 |
string |
任意 |
sortBy を指定する場合、sortOrder も指定されている必要があります。
sortOrder
sortOrder は User Achievement コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソートのキーとなるフィールドを指定する事が出来ます。
値 |
説明 |
型 |
備考 |
---|---|---|---|
sortOrder |
昇順 (ascending)、降順 (descending) を指定します。 |
string |
任意 |
sortOrder を指定する場合、sortBy も指定されている必要があります。
updatedSince
updatedSince は User Achievement コレクションの取得時にのみ使う事が出来ます。
updatedSince を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して指定された日時以降のデータを取得する条件を設定することができます。
値 |
説明 |
型 |
備考 |
---|---|---|---|
updatedSince |
指定された日時以降のデータ (最終更新日時の下限値) を取得対象とします。但し sortBy が updated 以外の場合は無視されます。 |
string |
任意 |
fields
取得したいフィールドを指定する事が出来ます。指定可能なフィールド名については User Achievement オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
fields |
このリソースの特定のフィールドのみを指定して取得したい場合に設定します。 |
array |
任意 |
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。何も指定しない場合に取得できるデフォルトフィールドは以下になります。
["userId", "achievementId", "state"]
APIレスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
リクエスト HTTP メソッド |
レスポンスコード |
レスポンスメッセージ |
説明 |
---|---|---|---|
GET |
200 |
OK |
正常にデータ取得が完了しました |
GET |
400 |
Bad Request |
リクエストデータが不正です |
GET |
401 |
Unauthorized |
OAuth による認可が失敗しています |
GET |
403 |
Forbidden |
認証エラー以外の理由でアクセス出来ない場合です |
GET |
404 |
Not Found |
存在しない userId または userId のユーザーが appId のアプリケーションをインストールしていない場合。 |
GET |
405 |
Method Not Allowed |
メソッドが許可されていません |
GET |
500 |
Internal Server Error |
API 側の問題による失敗です |
GET |
503 |
Service Unavailable |
API 側の一時的なエラーです |
レスポンスのデータ構造
API のレスポンスの payload として返されるデータ構造です。
property |
title |
type |
description |
---|---|---|---|
entry |
エントリ一覧 |
array |
|
entry[].userId |
ユーザー ID |
string |
|
entry[].appId |
アプリケーション ID |
string |
|
entry[].achievementId |
Achievement ID |
string |
|
entry[].state |
状態 |
string |
|
entry[].steps |
達成度 |
integer |
|
entry[].numOfUnlocked |
Unlock した回数 |
integer |
|
entry[].published |
作成日時 |
string |
|
entry[].updated |
更新日時 |
string |
|
startIndex |
開始インデックス値 |
integer |
|
itemsPerPage |
ページ当たりのエントリ数 |
integer |
|
totalResults |
総エントリ数 |
integer |
|
filtered |
フィルタ適用フラグ |
boolean |
フィルタが適用された場合に true になります |
sorted |
ソート適用フラグ |
boolean |
ソートが適用された場合に true になります。 |
サンプル
任意のユーザーの User Achievement コレクションを取得する場合
リクエスト形式
GET /people/@me/@self/achievements/@app?filterValue=UNLOCKED&count=10&fields=achievementId%2CnumOfUnlocked%2Cupdated&updatedSince=2013-07-13T05%3A37%3A11&sortOrder=descending&sortBy=updated&filterBy=state Authorization: OAuth oauth_parameters
レスポンス形式
200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-cache Pragma: no-cache { "entry": [ { "achievementId": "blood_reign", "numOfUnlocked": 1, "updated": "2013-07-16T04:57:08" }, { "achievementId": "dragon_scale", "numOfUnlocked": 1, "updated": "2013-07-16T03:49:18" }, { "achievementId": "animal_hunter", "numOfUnlocked": 5, "updated": "2013-07-16T02:53:49" }, { "achievementId": "exorcist", "numOfUnlocked": 1, "updated": "2013-07-16T01:48:36" }, { "achievementId": "self_preservation", "numOfUnlocked": 2, "updated": "2013-07-16T00:51:54" }, { "achievementId": "berserk", "numOfUnlocked": 1, "updated": "2013-07-15T23:57:03" }, { "achievementId": "arbitration", "numOfUnlocked": 1, "updated": "2013-07-15T22:54:31" }, { "achievementId": "broken_heart", "numOfUnlocked": 3, "updated": "2013-07-15T21:54:15" }, { "achievementId": "sniper", "numOfUnlocked": 1, "updated": "2013-07-15T20:56:45" }, { "achievementId": "fist_fight", "numOfUnlocked": 1, "updated": "2013-07-15T19:57:15" } ], "startIndex": 1, "itemsPerPage": 10, "totalResults": 31, "filtered": true, "sorted": true, "updatedSince": true }
任意のユーザーの友達の User Achievement コレクションを取得する場合
![]() | 友達の User Achievement コレクションを取得する場合、achievementId の指定が必須です。 |
リクエスト形式
GET /people/@me/@friends/achievements/@app/bogus_hero?count=10&fields=userId%2Cstate%2CnumOfUnlocked%2Cupdated&updatedSince=2013-07-13T05%3A37%3A11&sortOrder=descending&sortBy=userId Authorization OAuth oauth_parameters
レスポンス形式
200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-cache Pragma: no-cache { "entry": [ { "userId": "sp.mbga.jp:10234", "state": "UNLOCKED", "numOfUnlocked": 1, "updated": "2013-07-15T19:26:42" }, { "userId": "sp.mbga.jp:10211", "state": "REVEALED", "numOfUnlocked": 0, "updated": "2013-07-16T01:26:49" }, { "userId": "sp.mbga.jp:10108", "state": "HIDDEN", "numOfUnlocked": 0, "updated": "2013-07-15T10:26:53" }, { "userId": "sp.mbga.jp:9987", "state": "REVEALED", "numOfUnlocked": 0, "updated": "2013-07-16T06:27:00" }, { "userId": "sp.mbga.jp:9312", "state": "UNLOCKED", "numOfUnlocked": 1, "updated": "2013-07-15T09:27:07" }, { "userId": "sp.mbga.jp:8778", "state": "UNLOCKED", "numOfUnlocked": 1, "updated": "2013-07-15T15:27:12" }, { "userId": "sp.mbga.jp:7009", "state": "HIDDEN", "numOfUnlocked": 0, "updated": "2013-07-15T20:27:17" }, ], "startIndex": 1, "itemsPerPage": 10, "totalResults": 17, "filtered": false, "sorted": true, "updatedSince": false }
任意のユーザーの User Achievement コレクションを Achievement ID を指定して取得する (GET)
エンドポイント
- Sandbox 環境
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?format,fields}
- 本番環境
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?format,fields}
URI Template パラメータ
userId
userId パラメータは下記のいずれかの値を指定します。値
説明
型
備考
@me
viewer の userId
string
必須
{userId}
ユーザー ID
string or array
必須
self
self パラメータは下記のいずれかの値を指定します。値
説明
型
備考
@self
userId パラメータで指定したユーザー自身の User Achievement オブジェクトを取得する場合
string
必須
appId
appId パラメータは下記のいずれかの値を指定します。値
説明
型
備考
@app
現在実行中のアプリケーション ID
string
必須
{appId}
個々に割り振られたアプリケーション ID
string
必須
achievementId
achievementId パラメータには以下を指定します。値
説明
型
備考
{achievementId}
任意の Achievement に対しての User Achievement コレクションを取得するために指定します。
string or array
必須
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。json のみ指定可能です。
値 |
説明 |
型 |
備考 |
---|---|---|---|
json |
"application/json; charset=utf8" |
string |
任意、デフォルト値 |
fields
取得したいフィールドを指定する事が出来ます。指定可能なフィールド名については User Achievement オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
値 |
説明 |
型 |
備考 |
---|---|---|---|
fields |
このリソースの特定のフィールドのみを指定して取得したい場合に設定します。 |
array |
任意 |
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。何も指定しない場合に取得できるデフォルトフィールドは以下になります。
["userId", "achievementId", "state"]
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
リクエスト HTTP メソッド |
レスポンスコード |
レスポンスメッセージ |
説明 |
---|---|---|---|
GET |
200 |
OK |
正常にデータ取得が完了しました |
GET |
400 |
Bad Request |
リクエストデータが不正です |
GET |
401 |
Unauthorized |
OAuth による認可が失敗しています |
GET |
403 |
Forbidden |
認証エラー以外の理由でアクセス出来ない場合です |
GET |
404 |
Not Found |
userId と achievementId がそれぞれ単一で指定された際に、その achievementId に対する UserAchievement オブジェクトが存在しない場合。 |
GET |
405 |
Method Not Allowed |
メソッドが許可されていません |
GET |
500 |
Internal Server Error |
API 側の問題による失敗です |
GET |
503 |
Service Unavailable |
API 側の一時的なエラーです |
レスポンスのデータ構造
API のレスポンスの payload として返されるデータ構造です。
property |
title |
type |
description |
---|---|---|---|
entry |
エントリ一覧 |
array |
|
entry[].userId |
ユーザー ID |
string |
|
entry[].appId |
アプリケーション ID |
string |
|
entry[].achievementId |
Achievement ID |
string |
|
entry[].state |
状態 |
string |
|
entry[].steps |
達成度 |
integer |
|
entry[].numOfUnlocked |
Unlock した回数 |
integer |
|
entry[].published |
作成日時 |
string |
|
entry[].updated |
更新日時 |
string |
|
startIndex |
開始インデックス値 |
integer |
|
itemsPerPage |
ページ当たりのエントリ数 |
integer |
|
totalResults |
総エントリ数 |
integer |
|
サンプル
任意のユーザーの User Achievement コレクションを Achievement ID を指定して取得する
リクエスト形式
GET /people/@me/@self/achievements/@app/bogus_hero Authorization: OAuth oauth_parameters
レスポンス形式
200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-cache Pragma: no-cache { "userId": "sp.mbga.jp:12345", "achievementId": "bogus_hero", "state": "REVEALED" }
複数の任意のユーザーの User Achievement コレクションを複数の Achievement ID を指定して取得する
リクエスト形式
GET /people/10234,10351,11487/@self/achievements/@app/blood_reign,animal_hunter Authorization: OAuth oauth_parameters
レスポンス形式
200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-cache Pragma: no-cache { "entry": [ { "userId": "sp.mbga.jp:10234", "achievementId": "blood_reign", "state": "UNLOCKED" }, { "userId": "sp.mbga.jp:10234", "achievementId": "animal_hunter", "state": "REVEALED" }, { "userId": "sp.mbga.jp:10351", "achievementId": "animal_hunter", "state": "REVEALED" }, { "userId": "sp.mbga.jp:11487", "achievementId": "blood_reign", "state": "HIDDEN" }, { "userId": "sp.mbga.jp:11487", "achievementId": "animal_hunter", "state": "UNLOCKED" } ], "startIndex": 1, "itemsPerPage": 5 "totalResults": 5 }
任意のユーザーの User Achievement オブジェクトを Achievement ID を指定して作成・更新する (PUT)
エンドポイント
- Sandbox 環境
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?fields}
- 本番環境
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?fields}
URI Template パラメータ
userId
userId パラメータは下記のいずれかの値を指定します。値
説明
型
備考
@me
viewer の userId
string
必須
{userId}
ユーザー ID
string or array
必須
self
self パラメータは下記のいずれかの値を指定します。値
説明
型
備考
@self
userId パラメータで指定したユーザー自身の User Achievement オブジェクトを取得する場合
string
必須
appId
appId パラメータは下記のいずれかの値を指定します。値
説明
型
備考
@app
現在実行中のアプリケーション ID
string
必須
{appId}
個々に割り振られたアプリケーション ID
string
必須
achievementId
achievementId パラメータには以下を指定します。値
説明
型
備考
{achievementId}
任意の Achievement に対しての User Achievement コレクションを取得するために指定します。
string or array
必須
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
fields
分割アップデート (Partial Update) の対象とする field を指定します。state, steps のいずれか一方のみ指定可能です。
値 |
説明 |
型 |
備考 |
---|---|---|---|
fields |
"state", "steps" いずれか一方のみを指定できます。 |
array |
任意 |
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
リクエスト HTTP メソッド |
レスポンスコード |
レスポンスメッセージ |
説明 |
---|---|---|---|
PUT |
200 |
OK |
正常にリソースが更新出来ました。 |
PUT |
400 |
Bad Request |
リクエストデータが不正です |
PUT |
401 |
Unauthorized |
OAuth による認可が失敗しています |
PUT |
403 |
Forbidden |
認証エラー以外の理由でアクセス出来ない場合です |
PUT |
404 |
Not Found |
userId と achievementId がそれぞれ単一で指定された際に、その achievementId に対する UserAchievement オブジェクトが存在しない場合。 |
PUT |
409 |
Conflict |
変更不能なリソースが指定された場合。 |
PUT |
500 |
Internal Server Error |
API 側の問題による失敗です |
PUT |
503 |
Service Unavailable |
API 側の一時的なエラーです |
レスポンスのデータ構造
User Achievement オブジェクトフィールドそのものが返却されます。
注意点
- state の更新は更新前の state 値に応じて制約があります。
- 更新前の state が HIDDEN の場合は REVEALED, UNLOCKED へのみ変更が出来ます
- 更新前の state が REVEALED の場合は UNLOCKED へのみ変更が出来ます
- 更新前の state が UNLOCKED の場合は、Achievement.repeatable が true の Achievement の場合にのみ UNLOCKED を再び指定する事が出来ます。
- steps の更新は更新前の以下のいずれかの状態を満たす場合に行うことができます。
- state 値が REVEALED
- Achievement.repeatable が true の Achievement の場合、かつ state 値が UNLOCKED の Achievement
- Achievement.repeatable が true の場合に steps の値が Achievement.totalSteps を越えた値が指定された場合、超えた値は設定されずに Achievement.totalSteps 値が採用されます。
サンプル
任意のユーザーの User Achievement オブジェクトを Achievement ID を指定して作成・更新する (PUT)
steps の更新
リクエスト形式
PUT /people/@me/@self/achievements/@app/bogus_hero?fields=steps Authorization: OAuth oauth_parameters Content-Type: application/json; charset=utf-8 { "steps": 10 }
レスポンス形式
200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-cache Pragma: no-cache { "userId": "sp.mbga.jp:12345", "appId": "12000129", "achievementId": "bogus_hero", "state": "REVEALED", "steps": 10, "numOfUnlocked": 0, "published": "2013-07-15T09:13:58", "updated": "2013-07-15T11:22:16" }
state の更新
リクエスト形式
PUT /people/@me/@self/achievements/@app/bullpen_ace?fields=state Authorization: OAuth oauth_parameters Content-Type: application/json; charset=utf-8 { "state": "REVEALED" }
レスポンス形式
200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-cache Pragma: no-cache { "userId": "sp.mbga.jp:12345", "appId": "12000129", "achievementId": "bullpen_ace", "state": "REVEALED", "steps": 0, "numOfUnlocked": 0, "published": "2013-07-15T09:13:58", "updated": "2013-07-15T11:22:16" }