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

mixiでは、写真を登録して友人や他ユーザと共有可能な「フォトアルバム」サービスを従来より提供しています。登録された写真は、アルバムという単位で整理しておくことも可能です。

mixiアプリでは、登録されたアルバムやその中に入っている写真の情報を取得し、他のコンテンツとマッシュアップするためのAPIを提供しています。これは、OpenSocial 0.9にて規定されたAlbums APIに準拠したものです。

アルバム情報の取得

フォトアルバムのコンテンツを利用する際には、まず登録されているアルバムの一覧を取得することから始めます。そのためには、opensocial.DataRequest.newFetchAlbumsRequest()関数を利用します。

var req = opensocial.newDataRequest();
req.add(req.newFetchAlbumsRequest(opensocial.IdSpec.PersonId.OWNER), "albums");

newFetchAlbumsRequest()関数の引数は、取得対象のユーザを指定します。これは以下のどちらかとなります。

• opensocial.IdSpec.PersonId.OWNER
• opensocial.IdSpec.PersonId.VIEWER

そして、DataRequestオブジェクトにadd()関数を使ってリクエストオブジェクトを追加します。send()関数によってmixiのサーバに問い合わせが行われ、コールバック関数に結果が渡されます。

req.send(function(data) {
  var albums = data.get("albums").getData();
  albums.each(function(album) {
    var id = album.getField(opensocial.Album.Field.ID);
    var title = album.getField(opensocial.Album.Field.TITLE);
    // do something...
  });
});

取得した複数のアルバム情報は、opensocial.Collectionオブジェクトとして保持されているため、each()関数を使って各アルバム情報を取り出すことができます。アルバム情報から、以下の情報を取得することが可能です。

• フォトアルバムのID – album.getField(opensocial.Album.Field.ID)
• フォトアルバムのタイトル – album.getField(opensocial.Album.Field.TITLE)

これらの情報を使って、フォトアルバムの一覧を表示したり、ユーザにフォトアルバムの選択をさせたりすると良いでしょう。

写真情報の取得

あるフォトアルバムに登録されている写真の情報を取得し、各写真のURLを使ってmixiアプリ上で表示することができます。写真の情報を取得するために、opensocial.Album.newFetchMediaItemsRequest()関数を利用します。

var albumId = ...;
var req = opensocial.newDataRequest();
req.add(req.newFetchMediaItemsRequest(
        opensocial.IdSpec.PersonId.OWNER, albumId), "mediaItems");

newFetchMediaItemsRequest()関数には、以下の引数を指定します。

• opensocial.IdSpec.PersonId.OWNER または opensocial.IdSpec.PersonId.VIEWER
• フォトアルバムのID

DataRequestオブジェクトにadd()関数を使って、newFetchMediaItemsRequest()関数にて生成したリクエストオブジェクトを追加します。send()関数によってmixiのサーバに問い合わせが行われ、コールバック関数に結果が渡されます。

req.send(function(data) {
  var mediaItems = data.get("mediaItems").getData();
  mediaItems.each(function(mediaItem) {
    var thumbnailUrl = mediaItem.getField(opensocial.MediaItem.Field.THUMBNAIL_URL);
    var url = mediaItem.getField(opensocial.MediaItem.Field.URL);
    // do something...
  });
});

取得した複数の写真情報は、opensocial.Collectionオブジェクトとして保持されているため、each()関数を使って各写真情報を取り出すことができます。写真情報から、以下の情報を取得することが可能です。

• オリジナルの写真URL – mediaItem.getField(opensocial.MediaItem.Field.URL)
• サムネイルURL – mediaItem.getField(opensocial.MediaItem.Field.THUMBNAIL_URL)
• 説明文 – mediaItem.getField(opensocial.MediaItem.Field.DESCRIPTION)

mixiアプリにて、これらの情報から写真の一覧などを表示すると良いでしょう。

件数が多い場合のページング

取得対象のユーザのアルバムやフォトの数がとても多かった場合、全件を取得することは現実的ではありません。そのため、複数回に分けて結果の一覧を取得することができます。このような分割した取得を、ページングと呼びます。

ページングのために、opensocial.DataRequest.PeopleRequestFieldsクラスにて規定されているMAXおよびFIRST定数を利用することができます。以下は、その利用例です。

var params = {};
params[opensocial.DataRequest.PeopleRequestFields.MAX] = 10;
params[opensocial.DataRequest.PeopleRequestFields.FIRST] = 30;
var req = opensocial.newDataRequest();
req.add(req.newFetchAlbumsRequest(opensocial.IdSpec.PersonId.OWNER, params), "albums");
req.send(function(data) {
  var albums = data.get("albums").getData();
  var offset = albums.getOffset();
  var total = albums.getTotalSize();
  var size = albums.size();
  var msg = total + "件中 " + offset + " - " + (offset + size) + " 件目";
  // do something...
});

MAXには、1リクエストあたりの取得される最大の件数を指定します。そしてFIRSTには、IdSpecオブジェクトで特定されるユーザの集合の中で、何件目から取得するかを指定します。取得結果のCollectionオブジェクトからは、各種関数を使って、取得された件数や全体の件数などを得ることが可能です。これらを使用して、上記の例のようにページ処理を画面に表示するなどすればよいでしょう。

現状の制限について

Albums APIの利用について、現状では以下の制限がありますので、ご注意ください。

取得対象のフォトアルバムおよび写真は、OwnerおよびViewerのどちらかとなります。また、デフォルトで取得可能なフォトアルバムおよび写真は、全体公開と設定されているもののみとなります。

Viewerのアルバムについては以下のようにVISIBILITYパラメータを付与するこ
とで、全体公開以外のアルバムおよび写真も取得することができます(Viewerがアプリをマイアプリとして登録している必要があります)。

var params = {};
params[mixi.DataRequest.AlbumRequestFields.VISIBILITY] = 'all';
var req = opensocial.newDataRequest();
req.add(req.newFetchAlbumsRequest(idspec, params), "albums");
req.send(function (data) { ... });

VISIBILITYパラメータとして設定可能な値は現時点では’all’のみとなります。

かんたん公開機能に関して

新しいmixiフォトでは、アルバムを指定せずに写真をアップロードできる「かんたん公開」機能が提供されます。

「かんたん公開」はnewFetchAlbumsRequest()により、１つのアルバムとして提供されます（albumIdは常に1となります）。その他の操作に関しては、他のアルバム同様にアクセスが可能です。