User Achievement

概要

User Achievement API とは、定義された Achievement に対してのユーザーの達成状況を取得、更新することのできる API です。
 
User Achievement API では、以下の操作が可能となります。

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"
}
 

PREVIOUS

Achievement

NEXT

Bank Debit