2009-11-25

OpenSocial jQuery から OpenSocial Host の外部データベースを操作する基本手順を紹介します

おはようございます。なかじまんです。

OpenSocial jQuery から OpenSocial Host の Core API を使って、OpenSocial Host の外部データベースを操作する手順とソースコードを紹介します。

OpenSocial Host の外部データベースを使うメリットは、次のとおりです。

* OpenSocial AppData とは異なり、すべてのユーザが同じデータ領域を共有できる
* OpenSocial AppData とは異なり、個々のデータに対して、パーミッションを指定できる
* OpenSocial AppData とは異なり、個々のデータに対して、データ容量の制約がない
* OpenSocial AppData とは異なり、個々のデータに対して、ワード検索できる
* 外部データベースは HeartRails によって、安全、確実にホストされ、負荷対策も期待できる(に違いない)

OpenSocial Host の外部データベースにできなこともあります。

* OpenSocial AppData とは異なり、友達リストのソーシャルグラフが使えない

なので、OpenSocial API と OpenSocial Host の特徴をよく理解して、組み合わせて使うことになるのだろうと考えます。

ユーザの登録

はじめに OpenSocial Host のユーザ登録をしてください。
ユーザ登録は無料です。Open ID を使えば、パスワードを預ける必要はありません。



アプリケーションの登録

次に OpenSocial Host にログインして、新しいアプリケーションを登録してください。
アプリケーションの変更や削除はいつでもできますので、アプリケーション名は仮のものでも構いません。



アプリケーションを登録すると、アプリケーションキーが発行されますので、動作対象とするコンテナのアプリケーションキーを手元に控えてください。



アプリケーションの関連付け

ガジェット XML を用意して、動作対象とするコンテナにガジェット XML を登録してください。ガジェット XML は OpenSocial Host でホストしてもよいですし、自社サーバや Google AppEngine、Amazon S3 など、どこでホストしてもかまいません。

そして、次のように、ガジェット XML から /app/register を呼び出します。
このとき、前述のアプリケーションキーをパラメータとして、リクエストを署名します。
呼び出しが成功すると、OpenSocial Host とガジェット XML が関連付き、これ以降、ガジェット XML から OpenSocial Host の外部データベースが使えるようになります。
なお、関連付いた後は /app/register の呼び出しは不要です。アプリケーションの開発をはじめるとき、1度だけ呼び出してください。
// Register Application
  var url = 'http://opensocialhost.com/app/register';
  var data = { application_key: '( Your Application Key )' };
  
  $.ajax({
    type: 'post', url: url, oauth: 'signed', data: data, dataType: 'json'
  }).next(function(r) {
    if (r.hadError)
      throw r.errorCode; // call error
  }).error(function(e) {
    console.error(e+'');
  });
}}}
データの追加

/data/insert を呼び出して、データを追加できます。このとき、Key-Value 形式のデータとパーミッションをパラメータとして、リクエストを署名します。

* 既存のデータは上書きできます。ただし、パーミッションは上書きできません。パーミッションを変更するときは、データを削除した後、データを再挿入します。
* 読み込みと書き込みのパーミッションは別々です。書き込みは読み込みを兼ねません。
* パーミッションは public, private, specified を指定できます。specified のときは、カンマ区切りで、複数のユーザ ID を指定できます。
// Insert Data
  var url = 'http://opensocialhost.com/data/insert';
  var data = {
    comment: { text: 'Say Hello!', lastModified: new Date().getTime() },
    feeling: 'well',
    footprint: true
  };

  // Object を OpenSocial Host のパラメータに変換する
  // Key はそのまま、Value は JSON (String) に変換する
  var _data = {}, i = 1;
  $.each(data, function(k, v) {
    _data['key'+i] = k;
    _data['value'+i] = gadgets.json.stringify(v);
    i++; 
  });

  // 読み込みパーミッションを指定する
  //_data.read_permission = 'public'; // 誰でも(初期値)
  //_data.read_permission = 'private'; // 自分のみ
  //_data.read_permission = 'specified'; // 特定のユーザのみ
  //_data.read_permission_specified = '( User ID ),( User ID ), ...';  

  // 書き込みパーミッションを指定する  
  //_data.write_permission = 'public'; // 誰でも(初期値)
  //_data.write_permission = 'private'; // 自分のみ
  //_data.write_permission = 'specified'; // 特定のユーザのみ
  //_data.write_permission_specified = '( User ID ),( User ID ), ...';  
  
  $.ajax({
    type: 'post', url: url, oauth: 'signed', data: _data, dataType: 'json'
  }).next(function(r) {
    if (r.hadError)
      throw r.errorCode;
  }).error(function(e) {
    console.error(e+'');
  });
データの更新

/data/update を呼び出して、データを更新できます。このとき、Key-Value 形式のデータをパラメータとして、リクエストを署名します。
// Update Data  
  var url = 'http://opensocialhost.com/data/update';
  var data = { feeling: 'bad', footprint: false };

  // Object を OpenSocial Host のパラメータに変換する
  // Key はそのまま、Value は JSON (String) に変換する
  var _data = {}, i = 1;
  $.each(data, function(k, v) {
    _data['key'+i] = k;
    _data['value'+i] = gadgets.json.stringify(v);
    i++; 
  });

  $.ajax({
    type: 'post', url: url, oauth: 'signed', data: _data, dataType: 'json'
  }).next(function(r) {
    if (r.hadError)
      throw r.errorCode;
  }).error(function(e) {
    console.error(e+'');
  });
データの削除

/data/delete を呼び出して、データを削除できます。このとき、Key をパラメータとして、リクエストを署名します。
// Delete Data  
  var url = 'http://opensocialhost.com/data/delete';
  var data = [ 'comment', 'feeling' ];

  // Array を OpenSocial Host のパラメータに変換する
  var _data = {};
  $.each(data, function(i, v) {
    _data['key'+(i+1)] = v; 
  });

  $.ajax({
    type: 'post', url: url, oauth: 'signed', data: _data, dataType: 'json'
  }).next(function(r) {
    if (r.hadError)
      throw r.errorCode;
  }).error(function(e) {
    console.error(e+'');
  });
データの取得

/data/select を呼び出して、データを取得できます。このとき、Key をパラメータとして、リクエストを署名します。
// Select Data  
  var url = 'http://opensocialhost.com/data/select';
  var data = [ 'comment', 'feeling', 'footprint' ];

  // Array を OpenSocial Host のパラメータに変換する
  var _data = {};
  $.each(data, function(i, v) {
    _data['key'+(i+1)] = v; 
  });

  $.ajax({
    type: 'post', url: url, oauth: 'signed', data: _data, dataType: 'json'
  }).next(function(r) {
    if (r.hadError)
      throw r.errorCode;
    
    // OpenSocial Host のレスポンスを Object に変換する
    // Key はそのまま、Value は JSON (String) から Object に戻す
    var data = {};
    $.each(r.data, function(i, v) {
      data[v.key] = gadgets.json.parse(v.value);
    });   
    return data;
  
  }).next(function(data) {
    console.info(data.comment.text);
    console.info(data.comment.lastModified);
    console.info(data.feeling);
    console.info(data.footprint);
  }).error(function(e) {
    console.error(e+'');
  });
データの検索

/data/search を呼び出して、データを検索できます。このとき、フィルタ条件、ソート条件、ページング条件をパラメータとして、リクエストを署名します。

* 指定した文字列を Key に含むデータを検索できます。部分一致のみです。
* 指定した文字列を Value に含むデータを検索できます。部分一致のみです。
* Key と Value の両方を指定したときは、上記の AND 条件になります。
* page はページ番号です。インデックスではありません。
* sort は asc, desc を指定できます。ソート順はデータの追加日時です。更新日時ではありません。
// Search Data
  var url = 'http://opensocialhost.com/data/search';
  var data = {
    key: 'feeling', value: 'well', page: 1, per_page: 10, sort: 'asc'
  };

  $.ajax({
    type: 'post', url: url, oauth: 'signed', data: data, dataType: 'json'
  }).next(function(r) {
    if (r.hadError)
      throw r.errorCode;

    // OpenSocial Host のレスポンスを Object に変換する
    // Key はそのまま、Value は JSON (String) から Object に戻す    
    $.each(r.data, function(i, v) {
      v.value = gadgets.json.parse(v.value);
    });
    return $.extend(r.data, {
      page: r.page, per_page: r.per_page, total_counts: r.total_counts
    });
  
  }).next(function(data) {
    $.each(data, function(i, v) {
      console.info(v.key, v.value);
    });
    console.info(data.page, data.per_page, data.total_counts);
  }).error(function(e) {
    console.error(e+'');
  });
データのグループ化や階層化

OpenSocial Host の外部データベースは、すべてのユーザで共有して、パーミッションでアクセス件をコントロールします。ですので、どのユーザのデータなのか、どの種類のデータなのかは、次のように Key の文字列を使って表現する必要があります。
// VIEWER ID を使って、どのユーザのデータなのかを区別する
  var key = viewer.id + '$comment';
  var data = { text: 'Say Hello!', lastModified: new Date().getTime() };
データの確認 -- 2009/11/26 追加

OpenSocial Host にログインして、外部データベースの内容を確認できます。

* 指定した文字列を Key または Value に含むデータを検索できます。
* データの Key や Value、パーミッション、作成日時など、詳しく表示できます。
* データを削除できます。



関連リンク

* OpenSocial Host Core API
* OpenSocial Host ユーザフォーラム
投稿者 時刻:
ラベル: ,

0 件のコメント:

コメントを投稿

登録: コメントの投稿 (Atom)