概要

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

• User Achievement を取得する
  • 任意のユーザーのアプリ内で作成・更新した事のある User Achievement コレクションを取得する (GET)
  • 任意のユーザーの User Achievement コレクションを Achievement ID を指定して取得する (GET)
• User Achievement を更新する
  • 任意のユーザーの User Achievement オブジェクトを Achievement ID を指定して作成・更新する (PUT)

User Achievement オブジェクトフィールド

User Achievement を表すオブジェクトになります。

Increment User Achievement オブジェクトフィールド

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 パラメータは下記のいずれかの値を指定します。

self or friends

self or friends パラメータは下記のいずれかの値を指定します。

appId

appId パラメータは下記のいずれかの値を指定します。

achievementId

achievementId パラメータには以下を指定します。

クエリパラメータ

下記のクエリパラメータを指定する事が出来ます。

format

レスポンス形式を指定する事が出来ます。json のみ指定可能です。

count

コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。

※パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。

filterBy

filterBy は User Achievement コレクションの取得時にのみ使う事が出来ます。
filterBy を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterBy 値は検索条件のキーとなるフィールドを指定します。

現在指定可能な filterBy 値は以下の表になります。

filterBy を指定する場合、filterOp, filterValue も指定されている必要があります。

filterOp

filterOp は User Achievement コレクションの取得時にのみ使う事が出来ます。
filterOp を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterOp 値は検索条件のキーと値に対してどのような評価を行うかを指定します。

filterOp を指定する場合、filterBy, filterValue も指定されている必要があります。

filterValue

filterValue は User Achievement コレクションの取得時にのみ使う事が出来ます。
filterValue を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して検索条件を加える事が出来ます。filterValue 値は検索条件のキーに対して、どのような値と評価するかを指定する事ができます。

filterValue を指定する場合、filterBy, filterOp も指定されている必要があります。

sortBy

sortBy は User Achievement コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。

sortBy を指定する場合、sortOrder も指定されている必要があります。

sortOrder

sortOrder は User Achievement コレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対してソート条件を加える事が出来ます。sortOrder 値はソートのキーとなるフィールドを指定する事が出来ます。

sortOrder を指定する場合、sortBy も指定されている必要があります。

updatedSince

updatedSince は User Achievement コレクションの取得時にのみ使う事が出来ます。
updatedSince を指定すると、レスポンスとして返って来る User Achievement オブジェクトのコレクションに対して指定された日時以降のデータを取得する条件を設定することができます。

fields

取得したいフィールドを指定する事が出来ます。指定可能なフィールド名については User Achievement オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。

パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。何も指定しない場合に取得できるデフォルトフィールドは以下になります。

["userId", "achievementId", "state"]

APIレスポンス

レスポンスコード

API のレスポンスコードは以下のいずれかになります。

レスポンスのデータ構造

API のレスポンスの payload として返されるデータ構造です。

サンプル

任意のユーザーの 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 のみ指定可能です。

fields

取得したいフィールドを指定する事が出来ます。指定可能なフィールド名については User Achievement オブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。

パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。何も指定しない場合に取得できるデフォルトフィールドは以下になります。

["userId", "achievementId", "state"]

API レスポンス

レスポンスコード

API のレスポンスコードは以下のいずれかになります。

レスポンスのデータ構造

API のレスポンスの payload として返されるデータ構造です。

サンプル

任意のユーザーの 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 のいずれか一方のみ指定可能です。

API レスポンス

レスポンスコード

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