Achievement API

概要

Achievement API を用いると、Mobage Developers に設定された Achievement の オブジェクトを取得することができます。

Achievement には、Achievement ID を指定しないで取得する方法と、Achievement ID を指定して取得する方法の 2 通りがあり、それぞれリクエスト方法が異なります。

 

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 を指定しないで取得する
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 を指定して取得する
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
    • 新規作成

PREVIOUS

Achievement

NEXT

User Achievement API