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

一般的なアプリケーションにおいて、入力された情報や何らかの方法で入手したコンテンツに対して、ファイルやデータベースに書き出しておくことで、アプリケーションの利用状況に関わらず情報を永続化しておくことが行われます。ソフトウェアのほとんどが、何らかの情報を永続化しているといっても言い過ぎではないでしょう。

mixiアプリにおいても、入力された情報や外部のサービスから取得したコンテンツなどを永続化しておきたいと考える機会は多いはずです。毎回ユーザに情報の入力を求めていては、人気となるmixiアプリとは言えないでしょう。さらに、あるユーザの情報を、他のユーザから参照したい場合も出てきます。特に、情報共有系のmixiアプリであれば、なおさらです。

OpenSocial JavaScript APIでは、情報の永続化を行う機構をOpenSocialコンテナが提供することが規定されています。この機構にアクセスして永続化情報のやり取りを行うためのAPIを、OpenSocialではPersistence APIと呼んでいます。これを使って、開発者が独自にデータベースを準備することなしに、情報の永続化と共有を利用することができるようになります。

※ Persistence APIにて保存された情報は、同じmixiアプリを利用している任意のユーザにて常に取得可能な状態となります。そのため、パスワードなど保護されるべき重要な情報を格納するための場所として適していませんので、ご注意ください。

Persistence APIが提供する機能

mixiアプリは、Persistence APIを利用することで、情報の永続化および共有を行うことが可能となります。その際、特に共有に関して、扱われる情報の持ち主が誰なのか、という点を考慮した処理を記述することになります。つまり、永続化された情報の取得に関して「誰の情報を取得するか」という指定が必要となるということです。

以下は、Persistence APIにて提供される機能の一覧です。

• ある情報に名前を付けて永続化する。
• 永続化されている情報を取り出す。
• 永続化されている情報を削除する。

永続化される情報の管理単位は、アプリ＋ユーザごととなります。異なるmixiアプリの永続化情報にアクセスすることはできません。また、情報を永続化することができるのは、Viewerが自分を持ち主として自分の領域に永続化することのみが許可されます。他のユーザの領域に情報を永続化することはできません。

それに対して、永続化されている情報を取得する際には、mixiアプリはViewerの情報だけでなく、その他のユーザの永続化情報についても取得することが可能です。例えば、Viewerの友人の永続化情報を取得することができます。

mixiアプリでは、Key-Valueペアの文字列情報の永続化をサポートしています。

情報の永続化

まずは、ある情報の永続化を行うシンプルな例を以下のリストに示します。

var msg = "Oops! ><";
var req = opensocial.newDataRequest();
req.add(req.newUpdatePersonAppDataRequest(opensocial.IdSpec.PersonId.VIEWER, "comment", msg), "response");
req.send(function(data) {
  if (data.hadError()) {
    var msg = data.getErrorMessage();
    // do something...
  } else {
    var response = data.get("response");
    if (response.hadError()) {
      var code = response.getErrorCode();
      // do something...
    } else {
      // do something...
    }
  }
});

情報の永続化を行う際には、opensocial.DataRequest.newUpdatePersonAppDataRequest()関数を使います。これによって、1組のKey-Value値を永続化することが可能です。この関数の引数には、以下の情報を指定することになります。

・ユーザのID
・永続化する情報のキー文字列
・永続化する情報の文字列

第1引数のユーザIDは、Viewer固定となります。他のユーザへの情報の永続化は、セキュリティの観点からmixi Platformでは許可されません。opensocial.IdSpec.PersonId.VIEWERもしくはViewerのIDのどちらかを指定することになります。

第2引数のキー文字列は、永続化された情報を後で取り出す際に必要となります。このキー文字列に対して、最初にこの関数を呼び出した時は新規に作成、同じキー文字列を指定して2回目以降にこの関数を呼び出した時は、永続化されている情報が更新されることになります。3つ目の引数は、永続化したい情報を文字列で指定します。

newUpdatePersonAppDataRequest()関数の結果として得られるリクエストオブジェクトをDataRequestオブジェクトに追加して、send()関数によりサーバへ依頼を行います。send()関数の引数に指定したコールバック関数を使って、情報の永続化に成功したかどうかを確認するようにしましょう。

複数のKey-Valueペアを永続化させたい場合は、newUpdatePersonAppDataRequest()関数を複数回呼び出して、Key-Valueペアの数だけリクエストオブジェクトを生成してください。

永続化された情報の取得

永続化された情報を取得する際には「誰の永続化情報を取得するか」を指定することになります。Persistence APIでは、一度に複数人の永続化情報を取得することができます。この際、取得対象とするユーザの集合を特定するために、opensocial.IdSpecクラスを使用することになります。

Persistence APIにて提供されるnewFetchPersonAppDataRequest()関数を使うことで、永続化された情報を取得することができます。以下のリストは、Viewerの友人が持つ情報を取得する例です。エラー処理は省略しています。

var params = {};
params[opensocial.IdSpec.Field.USER_ID] = opensocial.IdSpec.PersonId.VIEWER;
params[opensocial.IdSpec.Field.GROUP_ID] = "FRIENDS";
var idSpec = opensocial.newIdSpec(params);
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonAppDataRequest(idSpec, ["comment"]), "response");
req.send(function(data) {
  var response = data.get("response").getData();
  for (var id in response) {
    var msg = response[id]["comment"];
    // do something...
  }
});

Viewerの友人の集合という条件を持つIdSpecオブジェクトを生成し、newFetchPersonAppDataRequest()関数の引数に渡して永続化情報を取得しています。この際、取得対象とする情報のキー名を配列で指定します。つまり、一度に複数のKey-Valueペアを取得することが可能ということです。

send()関数に渡すコールバック関数の引数から、取得した永続化情報を取り出します。取得結果は、ユーザIDをプロパティ名とする形で格納されています。for文で各IDごとにオブジェクトを取り出し、さらにKey-Valueペアのキー名をプロパティ名として指定することで、個々の永続化情報を取得し、それぞれ何らかの処理を行います。

永続化されている全ての情報を取得したい場合には、全てのキー文字列を配列で渡す方法の他に、「*」を指定することも可能です。例えば、

req.add(req.newFetchPersonAppDataRequest(idSpec, "*"), "response");

と指定することで、「全てのキー」を指定したことになります。

永続化された情報の削除

永続化された情報の中で必要でなくなったものに関しては、削除を行うことができます。削除は、opensocial.DataRequestクラスにあるnewRemovePersonAppDataRequest()関数を利用します。

以下のリストは、永続化された情報を削除する例です。

var req = opensocial.newDataRequest();
req.add(req.newRemovePersonAppDataRequest(
    opensocial.IdSpec.PersonId.VIEWER, ["comment"]), "response");
req.send(function(data) {
  var response = data.get("response").getData();
  if (response.hadError()) {
    var code = response.getErrorCode();
    // do something...
  }
});

永続化された情報の削除は、そのmixiアプリを利用しているユーザ、つまりViewerに対してのみ行うことが許可されています。そのため、newRemovePersonAppDataRequest()関数の第1引数には、opensocial.IdSpec.PersonId.VIEWERのみ指定することが可能となっています。

第2引数には、削除対象のキー文字列の配列、あるいは全てのキーを表す「*」を指定します。send()関数にて指定するコールバック関数の引数から、正しく削除されたかどうかのエラーチェックを行うことが、安定したmixiアプリに求められる処理となります。

永続化可能な情報の容量制限に関して

Persistence APIにて永続化可能な情報の最大容量は以下となります。

• 1つのKeyに対する文字列は、64KBまでとなります。
• 1ユーザが1アプリに付き利用可能な全てのKeyに対する文字列の合計は、10MBまでとなります。

※ 全角文字は3バイト(UTF-8)計算となります。

エラーコード

Persistence APIの呼び出し時に、いくつか結果として得られる可能性があるエラーコードがあります。これらのエラーコードは、ResponseItemオブジェクトのgetErrorCode()関数を呼び出すことによって得ることが可能です。エラーコードの種別によって、適切な処理を行ってください。