mixiアプリで友達情報を取得する

mixiアプリで始めるOpenSocial入門（5）

　前回は、 OpenSocialアプリケーションからOpenSocialコンテナに対して情報のリクエストを行うためのDataRequestオブジェクトの使い 方と、個人の情報を取得するためのリクエストを作成するnewFetchPersonRequestメソッドの使い方について説明しました。今回は、友達の情報を取得するためのnewFetchPeopleRequestメソッドの使い方を見ていきましょう。

はじめに

　前回は、OpenSocialアプリケーションからOpenSocialコンテナに対して情報のリクエストを行うためのDataRequestオブジェクトの使い方について説明しました。また、個人の情報を取得するためのリクエストを作成するnewFetchPersonRequestメソッドの使い方についても説明しました。

　今回は、友達の情報を取得するためのnewFetchPeopleRequestメソッドの使い方を見ていきましょう。

友達の情報の取得サンプル

　今回のサンプルではVIEWERのマイミクの人数と、それぞれのニックネームを表示します。

　DataRequestオブジェクトを使ったリクエストの流れはnewFetchPersonRequestメソッドを使う場合と同様ですが、リクエストの作成とレスポンスの処理の部分が異なってきます。

newFetchPeopleRequestメソッド

　newFetchPeopleRequestメソッドは友達の情報を取得するためのリクエストを作成します。

　メソッドの第一引数には、どの範囲の友達を取得するのかを表すopensocial.IdSpecオブジェクトを指定します。IdSpecは取得する友達の範囲を、opensocial.IdSpec.Fieldクラスで定義された以下の3つのパラメータを使って指定することができます。

opensocial.IdSpec.Fieldクラスのフィールド

フィールド名	概要
USER_ID	基点となるユーザーのPersonID
GROUP_ID	ユーザーの関係。mixiでは基点となるユーザーを表すSELFと、マイミクを表すFRIENDSが使用可能
NETWORK_DISTANCE	基点となるユーザーからの距離。ただしmixiアプリでは1に固定

　NETWORK_DISTANCEとは、直接の友達の場合の距離を1とし、友達の友達は2、さらにその友達であれば3、のように、友達関係をいくつ辿ればその人に到達できるか、を表します。

友達関係と距離の図。間に友達が入るほど距離が大きくなる

　mixiアプリでは、NETWORK_DISTANCEが1に固定され、基点となるユーザーのマイミクだけが取得可能となっています。従って、マイミクのマイミクまで一度に取得することはできません。

　友達の範囲を表すIdSpecオブジェクトはopensocial.newIdSpec関数で作成することができます。

　newFetchPeopleRequestメソッドの第2引数には、newFetchPersonRequestメソッドの場合と同様に、パラメータ名とパラメータ値のペアを複数格納した連想配列を追加パラメータとして指定します。第2引数は省略することもできます。

　パラメータとして扱える項目は、newFetchPersonRequestメソッドの場合と同じ、opensocial.DataRequest.PeopleRequestFieldsクラスのフィールドとして定義されています。以下に定義されているフィールドを示します。

opensocial.DataRequest.PeopleRequestFieldsクラスで定義された、
情報取得時の主なパラメータ

フィールド名	概要
FILTER	情報のフィルタ方法。opensocial.DataRequest.FilterTypeの値ですべての友達（ALL）、同じアプリケーションを使用している友達（HAS_APP）、OpenSocialコンテナで定義された親友（TOP_FRIENDS）のいずれかを指定する
FIRST	複数の情報をページングして受け取る際の、最初の情報のインデックス
MAX	一度に取得する情報の最大個数。デフォルトは20
PROFILE_DETAILS	個人の情報のうち、どの項目を取得するかを指定する（複数の項目を指定可能）
SORT_ORDER	複数の情報の並べ換えの順番。opensocial.DataRequest.SortOrderの値でアルファベット順（NAME）,OpenSocialコンテナで定義された親友順（TOP_FRIENDS）のいずれかを指定する

　なお、パラメータの中でフィルタ方法、ソート順で出てきたTOP_FRIENDSとは、仲の良さ・新しく友達になったなど、OpenSocialコンテナで定義される友達リスト内での順番付けのことを表します。この機能はオプショナルで、OpenSocialコンテナごとにサポート状況や、フィールドの指す意味が異なります。mixiアプリではFILTER、SORT_ORDERのどちらにおいてもTOP_FRIENDSはサポートされていないようです。

レスポンスの処理

　newFetchPeopleRequestで作成したリクエストを処理した場合には、ResponseItemオブジェクトにはopensocial.Personオブジェクトを複数含むコレクション（opensocial.Collection）が格納されます。コレクションには、次のようなメソッドが含まれています。

opensocial.Collectionクラスの主なメソッド

メソッド名	概要
size	コレクションのサイズを返します。情報をページングして取得している場合は、全体の件数ではなく、現在取得している件数を返します。
getTotalSize	コレクションの所属する、より大きな結果セットのサイズを返します。情報をページングして取得している場合でも、全体の件数を返します。
each	コレクションの各メンバーを順に取り出し、指定した関数の引数として実行します。

　表中でも説明してありますが、sizeメソッドは「現在取得している件数」を、getTotalSizeメソッドは「（ページングなどのために）現在取得していないものも含めた総件数」を返します。例えば、mixiアプリでnewFetchPeopleRequestで作成したリクエストに対するレスポンスの場合、getTotalSizeメソッドでマイミクシィの総数を取得することができます。

　eachメソッドは以下のサンプルでも使い方を解説しますが、コレクションのメンバーを順にたどることができるので、有用なメソッドです。