mixi Developer Center (ミクシィ デベロッパーセンター)

mixi Connect

mixi Connect » mixi Graph API » 技術仕様 » mixiアプリ用API » Persistence API

Persistence API

Persistence APIとは、mixiアプリごとにユーザに関するデータ（永続化情報）をmixiサーバ上にKey-Value形式で格納する機能です。
ユーザ自身と友人のデータの読み込みも可能です。

ここでは、Persistence APIについて、その使用方法を説明します。

永続化情報については詳しくは情報を共有してみようをご参考ください。

 

事前に必要なもの

Persistence APIを利用するためには、以下の情報をすでに入手している必要があります。

  • “mixi_apps2”スコープについて認可されたアクセストークン

上記以外のスコープで認可されたアクセストークンを使用して、Persistence APIにアクセスすることはできません。現状では、mixi_apps2スコープはmixiアプリやmixi API SDK for Android™、mixi API SDK for iOSからのみ利用することが可能です。

Persistence APIで提供される機能とスコープ

Persistence APIでは一つのスコープで全ての機能がまとめて提供されています。

スコープ 機能 メソッド
mixi_apps2 ユーザのデータの書き込み
ユーザや友人のデータの読み込み
ユーザのデータの削除		 POST, PUT
GET
DELETE

詳しくはmixiアプリのユーザ認可処理や、mixi API SDK for Android™の初期化と認可処理、mixi API SDK for iOSの初期化と認可処理をご参照ください。

データの登録

Persistence APIの登録機能により、ユーザに関するデータを保存することができます。

POST https://api.mixi-platform.com/2/apps/appdata/@me/@self
PUT https://api.mixi-platform.com/2/apps/appdata/@me/@self
  • POSTとPUTメソッドが対応されていますが、機能は同じになります。

リクエストボディとして、Key-Value情報を以下のようにapplication/json形式にて指定します。

{
    "greeting" : "ようこそ！",
    "level" : "5"
}

通常の場合は以下のレスポンスが返ってきます。

{
    "response_code" : 200
}

エラーコード

状況 ステータス
コード		 errorの値 error_descriptionの値 補足
リクエストのContent-Typeが未対応 400 bad_request Bad request  
Key/Value指定が不正 400 parameter_invalid No key/value pairs  
100個以上のKey/Value指定 413 request_entity_too_large Too many key/value pairs (max=最大Key数) 同時に99個のKeyまで登録できます。
容量越え 400 parameter_invalid Limit exceeded size quota (max=最大容量) mixiアプリ・ユーザごとに合計10,000,000バイトを超える場合は発生します。

エラーが発生した場合のレスポンスについて、共通エラーコードをご参照ください。

データの取得

Persistence APIでは、以下の3つの区分でデータを取得することが可能です。

  • ユーザ自身のデータの取得
  • ユーザの全ての友人のデータの取得
  • 指定のユーザ（ユーザ自身または友人）のデータの取得

取得するフィールド（Key）を指定することができます。

GET https://api.mixi-platform.com/2/apps/appdata/[User-ID]/[Group-ID]?fields=[フィールド一覧]
パラメータ 指定する値
User-ID 取得したいユーザのID、もしくは認可ユーザ自身を示す“@me”
Group-ID “@self”または“@friends”
fields 取得したいデータをカンマ切れのKey一覧にて指定することができます。
“*”または“@all”は全てを意味します。デフォルトは全てです。
（fieldsは省略可）
  • fieldsのデフォルト値は“*”（全て）になります。

リクエストの例

GET https://api.mixi-platform.com/2/apps/appdata/@me/@self
GET https://api.mixi-platform.com/2/apps/appdata/@me/@friends
GET https://api.mixi-platform.com/2/apps/appdata/@me/@self?fields=greeting,level

データの削除

ユーザの指定のデータを削除することができます。ユーザ自身以外のデータの削除は不可能です。

DELETE https://api.mixi-platform.com/2/apps/appdata/@me/@self?fields=[フィールド一覧]
パラメータ 指定する値
fields 削除したいデータをカンマ切れのKey一覧にて指定することができます。
“*”または“@all”は全てを意味します。デフォルトは全てです。
（fieldsは省略可）

リクエストの例

DELETE https://api.mixi-platform.com/2/apps/appdata/@me/@self
DELETE https://api.mixi-platform.com/2/apps/appdata/@me/@self?fields=greeting,level

共通エラーコード

もし処理に失敗した場合は、ステータスコード400番台または500番台と共に、そのエラーの内容を持つ以下のようなJSON文字列が返却されます。

状況 ステータス
コード		 errorの値 error_descriptionの値 補足
認証情報が不正(selectorが無効) 403 permission_denied Permission denied  
更新数制限（180秒間に180回） 503 service_unavailable appdata update frequency is too high 発生した場合はRetry-Afterヘッダーで指定される秒数を待つ必要があります。
不正値(値がnull、配列、ハッシュなど) 400 bad_request No value associated with specified key. 値は文字列をご利用ください。 
{
    "error" : "status_conflicted",
    "error_description" : "status cannot be changed"
}

利用制限

  • 1つのKeyに対する文字列は、65535バイトまでとなります。
  • 同時に99個のKeyまで登録できます。
  • mixiアプリ・ユーザごとに合計10,000,000バイトまでとなります。
  • 180秒に180回まで更新（登録・削除）リクエストができます。mixiアプリ・ユーザごとの制限になります。

※ 全角文字は3バイト（UTF-8）計算となります。
※ RESTful APIと共通の制限となります。

ページング、表現形式

Persistence APIは、ページングは未サポートとなります。サポートされる表現形式は、JSON形式のみです。

このページの上部へ

©MIXI