Getting Started(JavaScript, Node.js)

こちらのドキュメントは、JavaScript SDK(Node.js SDKも含む)を使ってMilkcocoaを使い始める方法です。

※こちらを始める前に、チュートリアルのこのページを参考にMilkcocoaに登録・アプリの作成・app_idの確認を行っておいて下さい。

null

オリジンの設定(Webブラウザで利用する場合のみ)

WebブラウザでMilkcocoaを利用する場合は、使い始める前にMilkcocoaを実行するオリジンを指定します。

オリジン」とは、「プロトコル(httphttpsなど)」と「ホスト(example.comnews.example.comなど)」、「ポート(:80:8000など)」の組み合わせです。多くの場合、プロトコルはhttp、ポートは80なので、その場合はホストのみを登録頂いて構いません(httpsの場合もポートの記述は不要です)。

アプリの管理画面の「設定」の「許可Origin」に入力して下さい。

注意すべき点は、オリジンは「ブラウザの機能」です。そのため、こちらを設定してもブラウザ以外の環境であればどこでも実行できるため、アクセス制御目的での利用はおやめ下さい。

※開発環境用にlocalhost127.0.0.0がデフォルトで登録されています。開発が終わってWeb上に公開した際には、こちらの2つは削除下さい。

milkcocoa.jsを読み込む

ではMilkcocoaを使い始めましょう。Webブラウザで利用する場合は、まずコンテンツサーバからmilkcocoa.jsを読み込みましょう。以下のscriptタグをHTMLファイル内に書きます。

<script src="http://cdn.mlkcca.com/v0.6.0/milkcocoa.js"></script>

Node.jsの場合は以下のようにnpmでインストールしたのち、requireで読み込みます。

npm install milkcocoa
var MilkCocoa = require('milkcocoa');

milkcocoaオブジェクトの作成(MilkCocoaとのコネクションの確立)

次に、APIを呼び出すためのオブジェクト(milkcocoa)を作成します。このオブジェクトを使って様々な関数を呼び出します(milkcocoa.dataStore()milkcocoa.user()など)。なお、milkcocoaオブジェクトを作成した時点で、Milkcocoaとのコネクションが確立されます。

var milkcocoa = MilkCocoa.connectWithApiKey('your-app-id.mlkcca.com', 'API_Key', 'API_Secret');

your-app-idの部分は、作成したアプリが持っている固有の文字列で、ログインを行った先のアプリの管理画面で確認できます。

データストアオブジェクトを作成しデータを送信・保存する

MilkcocoaのAPIで核となる、データのやり取りを行うためのデータストアオブジェクトを作成しましょう。dataStore()関数に、好きなデータストア名を引数にいれてオブジェクトを作成します(作成と言っていますが、毎回作成しているわけではないので、厳密には取得という言い方が正しいかもしれません)。今回は、ds(DataStoreの略)という名前を使いましょう。

// 'messages'というデータストア名のデータストアを作成(取得)
var ds = milkcocoa.dataStore('messages');

このdsオブジェクトを使って、messagesというデータストアに対して、データの送信(ds.send())、データの送信&保存(ds.push())、保存されたデータの取り出し(ds.stream())など様々なデータのやり取りを行います。

以下がデータ送信、データ送信&保存の例です。データの形式はJSON形式になります。

// titleが'hoge'、contentが'huga'というデータを送信(保存はされない)
ds.send({title : 'hoge', content : 'huga'});
// titleが'hoge'、contentが'huga'というデータを送信&保存
ds.push({title : 'hoge', content : 'huga'});

push()が正しく行われたか(データが正しく保存されたか)確認するために、管理画面の「データストア」画面で見てみましょう。

「データストアの選択」でmessagesを選択して「リスト表示」して保存されたデータを確認します。Valueの列に{"title":"hoge","content":"huga"}を持ったデータがあれば成功です。

イベントを監視して、データを受け取る

先ほどのセクションでsend()でデータを送信しましたが、このイベントを受け取るには、on()関数を使います。第一引数に受け取りたいイベントを入れて、次の引数にイベントが実行されたタイミングで実行したい関数(コールバック関数)を登録します。

ds.on('send', function() {
  console.log('sendされました!');
});

これで、send()が行われたタイミングで、コンソールに「sendされました!」と表示されるかと思います。さらにそのコールバック関数の第一引数に、send()push()で送信されたデータが入ってきます。

ds.on('send', function(sended) {
  console.log('sendされました!titleは'+sended.value.title+'contentは'+sended.value.content+'です!');
});

ここで注意して頂きたいのは、データの構造です。あなたが送信したデータは、sendedの下ではなく、sended.valueの中に入っています。これは、その他のメタ情報(IDやタイムスタンプ)と明確にわけるためです。具体的には以下のようなデータ構造になっています。

// sended
{
    id: [String],
    timestamp: [Number],
    value: {
        title: 'hoge',
        content: 'huga'
    }
  }

ただ、IDやタイムスタンプは保存の際に付与されるものなので、単に送信されたデータを受け取る場合は、それらはundefinedになります。

保存されたデータの取得

最後に保存されたデータを読んでみましょう。保存された複数のデータを取得するには、stream()関数を使います。取ってきたデータを使って処理を実行するにはnext()関数を使います。next()関数の引数にコールバック関数を書き、コールバック関数の第二引数に配列でデータが渡ってきます(第一引数はエラーが入っています、エラーが無ければnullになります)。

ds.stream().next(function(err, messages){
  console.log(messages);
  /*
  messages -> [{
    id: [String],
    timestamp: [Number],
    value: {
        title: '...',
        content: '...'
    }
  },
  {
    id: [String],
    timestamp: [Number],
    value: {
        title: '...',
        content: '...'
    }
  },
  ...
  ]
  */
});

なお、デフォルトでは、「降順(pushのみ使用であれば新しい順と同義)」で「データ数50まで」のデータを取ってきます。その辺りのオプションは、APIドキュメントをご覧下さい。

また、新しくhistory()というAPIも実装致しました。history()では、データが保存された期間を指定して取得できるのが大きな特長です。

// Historyオブジェクトを作成
var history = ds.history();

// 1月1日0:00〜2月1日0:00までのデータを取得すると指定
history.span(new Date(2015, 0).getTime(), new Date(2015, 1).getTime());

// データを取得したときのコールバック関数の登録
history.on('data', function(messages){
  console.log(messages);
  /*
  messages -> [{
    id: [String],
    timestamp: [Number],
    value: {
        title: '...',
        content: '...'
    }
  },
  {
    id: [String],
    timestamp: [Number],
    value: {
        title: '...',
        content: '...'
    }
  },
  ...
  ]
  */
});

// データ取得の開始
history.run();

history()も、デフォルトでは、「降順(pushのみ使用であれば新しい順と同義)」で「データ数50まで」のデータを取ってくるようになっています

また、get()関数を使えば特定の1つのデータを取得できます。get()やその他のAPIも含め、APIドキュメントをご覧頂ければと思います。