ドキュメント

ユーザー情報を取得する

ソーシャルアプリが採用している OpenSocial は、ユーザー情報やグループ情報にアプリケーションからアクセスすることができる API が規定されています。これらの API を利用することにより、Aipo内のデータを活用したアプリケーションを作成することができるようになります。ユーザー情報の場合、利用中(自分)のユーザー情報およびAipoに登録されているユーザー情報にアクセスすることができます。

ユーザー情報の取得処理は、OpenSocial で定められている People API を利用することになります。OpenSocial 1.0 で規定されている仕様については下記をご覧ください。

http://opensocial-resources.googlecode.com/svn/spec/1.0/Social-Gadget.xml#osapi.people

ユーザー情報の取得

Aipoのユーザー情報を取得する JavaScript API を利用するためには、まず以下のようにガジェットXMLを記述して osapi フィーチャーを有効にする必要があります。

<Module ...>
  <ModulePrefs>
    <Require feature="osapi" />
     ...
  </ModulePrefs>
...
</Module>

利用者のユーザー情報を取得するコードは以下のようになります。

osapi.people.get({ userId: '@viewer' }).execute(function(response) {

    // ユーザーID
    // 例)org001:sample1
    var userId = response.id;

    // 表示名(氏名)
    // 例)木村 一郎
    var displayName = response.displayName;

    // ...
});
  • ユーザー情報は osapi.people.get() メソッドを利用して取得します。
  • osapi.people.get() メソッドの userId パラメータには、取得したいユーザーの ID を指定します。
  • 利用者のユーザー情報を取得する場合は、userId パラメータに @viewer を指定します。

また、別名の osapi.people.getViewer() メソッドを使っても同じことができます。

osapi.people.getViewer().execute(function(response) {
    // ...
});

ユーザー情報で取得できる項目は以下のとおりです。

項目名 説明 サンプル
id ユーザーID "org001:sample1"
displayName 表示名(氏名) "木村 一郎"
name 氏名 { givenName: "一郎", familyName: "木村" }

ユーザー情報の取得範囲は osapi.people.get() メソッドの userId と groupId パラメータで指定します。

userId groupId 説明
@viewer @self (省略可) 利用中のユーザー(Viewer)
@owner @self (省略可) @viewer を指定した場合と同様
ユーザーID @self (省略可) 指定したユーザー

ユーザー一覧の取得

Aipoに登録されているユーザーの一覧を取得するコードは以下のようになります。

osapi.people.get({ userId: '@viewer', groupId: '@all' }).execute(function(response) {

    var users = response.list;

    for (var i in users) {
        
        // ユーザーID
        // 例)org001:sample1
        var userId = users[i].id;

        // 表示名(氏名)
        // 例)木村 一郎
        var displayName = users[i].displayName;

        // ...
    }
    // ...
});
  • ユーザー一覧を取得する場合は、groupId パラメータに @all あるいは @friends を指定します。
  • 無効化されているユーザーは一覧に含まれません。

また、別名の osapi.people.getViewerFriends() メソッドを使っても同じことができます。

osapi.people.getViewerFriends().execute(function(response) {
    // ...
});

ユーザー一覧の取得範囲は osapi.people.get() メソッドの userId と groupId パラメータで指定します。

userId groupId 説明
@viewer @friends Aipoに登録されているユーザー全体(ただし、無効化ユーザーは含まれません。)
@viewer @all @friends と同様
@owner @friends @viewer と同様
@owner @all @viewer と同様
ユーザーID @friends @viewer と同様
ユーザーID @all @viewer と同様

ユーザー一覧のページング

Aipoに登録されているユーザー数が多い場合、ユーザー一覧で全件取得するのは負荷の面であまり好ましくありません。OpenSocial ではデータ取得の範囲を絞り込むためのパラメータが用意されています。

ユーザー一覧をページング処理するコードは以下のようになります。

osapi.people.get({ userId: '@viewer', groupId: '@all', startIndex: 10, count: 50}).execute(function(response) {

    // 全件数
    // 例)100
    var total = response.totalResults;

    // 開始位置
    // 例)10
    var startIndex = response.startIndex;

    // 取得件数
    // 例)50
    var count = response.itemsPerPage;

    var users = response.list;

    for (var i in users) {
        // ユーザーID
        // 例)org001:sample1
        var userId = users[i].id;

        // 表示名(氏名)
        // 例)木村 一郎
        var displayName = users[i].displayName;

        // ...
    }
    // ...
});
  • startIndex パラメータには取得開始位置、count パラメータには取得件数を指定します。
  • count パラメータのデフォルト値は 20、最大値は 1000 となります。

ユーザー一覧のフィルタ

ユーザー一覧から特定の条件で絞り込みたい場合は、フィルタ条件を利用します。

ユーザー一覧を氏名で絞り込むコードは以下のようになります。

osapi.people.get({ userId: '@viewer', groupId: '@all', filterBy: 'name', filterOp: 'contains', filterValue: '太郎' }).execute(function(response) {
    // ...
});

フィルタに指定することのできるパラメータは以下のようになります。

filterBy filterOp filterValue 説明
name equals
contains
startsWith
任意の文字列 氏名を指定した文字列で絞り込みます。

filterOp パラメータに指定できる条件とその役割は以下のようになります。省略した場合は、equals が指定されます。

filterOp 説明
equals (省略時) filterBy の項目は filterValue と一致する
contains filterBy の項目が filterValue を含む
startsWith filterBy の項目が filterValue で始まる
present filterBy の項目が値を持つ

ユーザー一覧のソート

ユーザー一覧を並び替えたい場合は、ソート条件を利用します。

ユーザー一覧を降順で並び替えるコードは以下のようになります。

osapi.people.get({ userId: '@viewer', groupId: '@all', sortBy: 'position', sortOrder: 'descending' }).execute(function(response) {
    // ...
});
  • sortBy パラメータにソート対象の項目、sortOrder パラメータにソートの方向(昇順、降順)を指定します。

ソートに指定することのできるパラメータは以下のようになります。

sortBy sortOrder 説明
position ascending
descending
Aipoに登録されている並び替え順序でソートします。

sortOrder パラメータに指定できる条件とその役割は以下のようになります。省略した場合は、ascending が指定されます。

sortOrder 説明
ascending (省略時) 昇順でソートする
descending 降順でソートする