(cache) JavaScript API Reference

APIリファレンス(JavaScript, NodeJS)

※注1：Node.js SDKは最新バージョンに更新下さい。History APIは0.3.x以降でのみ利用できます。

※注2：現在、remove APIの利用は非推奨となっております。

※注3：メソッドごとに1分間に発行できるAPI数が限られています（制限は今後緩和される可能性があります）。

remove()（利用非推奨）	コネクション数の上限×30回／分
send()	コネクション数の上限×240回／分
その他のメソッド	コネクション数の上限×120回／分

Milkcocoa Install

MilkCocoa APIを利用するには、以下のScriptタグをHTMLファイルの<head>タグなどの中に書き込んでください

<script src="https://cdn.mlkcca.com/v2.0.0/milkcocoa.js"></script>

MilkCocoa

MilkCocoaオブジェクトはmilkcocoaを使用するに当たって不可欠なオブジェクトです。 MilkCocoaオブジェクトは、ソケット通信用コネクションの確立、ユーザーのログイン機能やデータとのやりとりをするDataStoreオブジェクトの発行等アプリのマネージャーのように働きます。

メソッド	詳細
new MilkCocoa()	データストアへの接続を確立し、通信に使うMilkCocoaオブジェクトのインスタンスを取得します。
connectWithApiKey()	new Milkcocoa()をAPI Keyを使って行います。
dataStore()	データの保存や取得の命令を出すため、データストアとの通信を行うDataStoreオブジェクトを取得します。
authWithToken()	ログインの処理を行います。
logout()	ユーザーのログアウト処理を行います。
user()	現在ログインしているユーザの情報を取得します。ユーザーのログイン・非ログインで表示する情報を切り分けるなどして利用します。

new MilkCocoa()

MilkCocoaのインスタンスを作ることで、コネクションを確立することができます。DataStoreの取得やログイン機能等もこのインスタンスを通して行います。

引数

new MilkCocoa(host)

host: MilkCocoaのデータストアのホストへのURLをString型で渡します。ホストサーバーへのURLはapp-id.mlkcca.com となっており、app-idはそれぞれのアプリに固有のIDで、アプリケーションの作成の時に取得できます。

戻り値

正しいAppIDを渡した場合、戻り値としてホストとの通信が確立しているMilkCocoaのインスタンスを取得することができます。このインスタンスを使ってデータストアとの通信やログイン機能を使うことができます。コールバック関数は引数に入れても入れなくても動作します。

使い方

var milkcocoa = new MilkCocoa('app-id.mlkcca.com');

connectWithApiKey()

MilkCocoaのインスタンスを作る際に、API Keyを使って認証を行う場合、new Milkcocoa()の代わりにこちらを使用します。

引数

connectWithApiKey(host, api_key, api_secret)

host: MilkCocoaのデータストアのホストへのURLをString型で渡します。ホストサーバーへのURLはapp-id.mlkcca.com となっており、app-idはそれぞれのアプリに固有のIDで、アプリケーションの作成の時に取得できます。
api_key: アプリの管理画面で生成されたAPI Keyを入力します。API Secretとペアで入力することで認証します。
api_secret: アプリの管理画面で生成されたAPI Secretを入力します。

戻り値

使い方

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

dataStore()

DataStoreオブジェクトを取得します。このDataStoreオブジェクトを介してデータストアを操作することができます。

引数

dataStore(path)

path: データストアのパスを指定します。パスは"/"を用いて区切ることが出来ます。

戻り値

指定したパスへのDataStoreオブジェクトを返します。

使い方

//"chat/message"を扱うデータストアを作ります。
var messageDataStore = milkcocoa.dataStore('chat/message');

//DataStoreのchildメソッドを使用することで、chat/messageへこのようにアクセスすることもできます。
var messageDataStore = milkcocoa.dataStore('chat').child('message');

authWithToken()

ユーザーのログイン処理を行うメソッドです。詳しい使い方はこちらのブログ記事をご覧下さい。

引数

authWithToken(token, callback)

token: ログインに使用するトークンを文字列で渡します。
callback(err, user): コールバック関数を渡すことが出来ます。エラー処理や作成したユーザー情報の取得に利用してください。

エラーメッセージ	概要
null	ログインが正常に終了しました。
invalid token	トークンが無効です。

戻り値

戻り値はありません。

使い方

milkcocoa.authWithToken(token, function(err, user) {
    switch(err){
    case null:
        console,log(user);
        break;
    case 'invalid token':
        console.log('トークンが無効です。');
        break;
    }
});

logout()

ログアウトの処理を行うためのメソッドです。logout()を実行せずとも、管理画面で指定したセッション有効期限の期間が経つと自動的にログアウトされます。

引数

logout(callback)

callback(err): コールバック関数を渡すことが出来ます。

エラーメッセージ	概要
null	ログアウトが正常に終了しました。

戻り値

戻り値はありません。

使い方

milkcocoa.logout();

user()

現在ログインしているユーザーの情報を取得するメソッドです

引数

user(callback)

callback(err, user): コールバック関数を渡すことが出来ます。

エラー文字列	概要
null	ログアウトが正常に終了しました。
"origin denied"	許可Originが設定されていません。

戻り値

戻り値はありません。

使い方

milkcocoa.user(function(err, user) {
    if(err) {
        //error
        return;
    }
    if(user) {
        console.log("Logged in", user);
    }else{
        console.log("Not logged in");
    }
});

DataStore

DataStoreはデータのやり取りを行うためのオブジェクトです。

メソッド	詳細
push()	データストアに新しくデータを追加します。
set()	データストアの要素を変更します。
remove()	データストアからデータを削除します。※現在、利用非推奨
send()	データストアにデータを残さず、現在接続されているユーザーにデータを送信することができます。
on()	データストアへのイベントを登録します。
off()	データストアに登録されたイベントを解除します。
get()	特定のデータストア要素を取得することができます。
stream()	データストアからデータを順番に取得します。
history()	データストアからデータを取得します。取得する際に期間や個数を指定することができます。
child()	子のデータストアを取得するメソッドできます。

push()

データストアに新しいデータを追加するメソッドです（1回にpushできる最大サイズは4Kbyteです）。

引数

push(object, onComplete, onError)

object: データストアへプッシュするデータをオブジェクト形式で渡します。このときデータストア要素のIDは自動で付加されます。
onComplete(err, datum): データがサーバに到達した時点でこのコールバックが呼ばれます。省略可能です。
onError(err): セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数、保存数の上限に達している際に、このコールバックが呼ばれます。

タイプ	概要
id	プッシュされたデータストア要素のID
value	プッシュされた値

戻り値

戻り値はありません。

使い方

milkcocoa.dataStore('chat').push({ 'content' : 'Hello!' });

milkcocoa.dataStore('chat').push({ 'content' : 'Hello!!!' }, function(err, pushed){
    //サーバに到達
    console.log(pushed);
    /*
    {
        id: 'foo(自動生成)',
        value: {
            content: 'Hello!!!'
        }
    }
    */
}, function(err) {
    //"Permission denied" or "limit exceeded"
});

set()

データストアの要素を更新、追加するメソッドです。

引数

set(id, datum, onComplete, onError)

id: 更新したいデータストア要素のidを指定します。
datum: 更新、追加するデータを引数として渡します。
onComplete(err, datum): データがサーバに到達した時点でこのコールバックが呼ばれます。省略可能です。
onError(err): セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数、保存数の上限に達している際に、このコールバックが呼ばれます。

タイプ	概要
id	セットされたデータストア要素のID
value	セットされた値

戻り値

戻り値はありません。

使い方

dataStore.set('id1', { 'title' : 'First Post!', 'content' : 'Hello, I am fred.'});

milkcocoa.dataStore('chat').set('test', { 'content' : 'Hello!!!' }, function(err, set){
    //サーバに到達
    console.log(set);
    /*
    {
        id: 'test',
        value: {
            content: 'Hello!!!'
        }
    }
    */
}, function(err) {
    //"Permission denied" or "limit exceeded"
});

remove()

データストアからデータを削除するメソッドです。※現在、利用非推奨となっております。

引数

remove(id, onComplete, onError)

id: 削除したいデータストア要素のidを渡します。
onComplete(err, datum): サーバで削除操作が行われた時点でこのコールバックが呼ばれます。省略可能です。
onError(err): セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数の上限に達している際に、このコールバックが呼ばれます。

タイプ	概要
id	削除されたデータストア要素のID

戻り値

戻り値はありません。

使い方

dataStore('user').set('fred', {'status':'premium'});
dataStore('user').remove('fred');

milkcocoa.dataStore('chat').remove('test', function(err, removed){
    //サーバでの削除操作が完了
    console.log(removed);
    /*
    {
        id: 'test'
    }
    */
}, function(err) {
    //"Permission denied" or "limit exceeded"
});

send()

データストアをにデータを保存しないデータの送信を行うことが出来ます。このメソッドによって、同じデータストアのsendイベントを監視しているクライアントにデータを送信することが出来ます。

引数

send(object, onComplete, onError)

object: 相手に送りたいオブジェクトを渡すことができます。
onComplete(err, datum): データがサーバに到達した時点でこのコールバックが呼ばれます。省略可能です。
onError(err): セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数の上限に達している際に、このコールバックが呼ばれます。

タイプ	概要
value	送信された値

戻り値

戻り値はありません。

使い方

//現在dataStoreのsendイベントをon関数で監視しているユーザにデータを送ることが出来ます。
//ただし、データストアにデータは保存されません。
dataStore.send({
    content : 'Hello!'
});
milkcocoa.dataStore('chat').send({ 'content' : 'Hello!!!' }, function(err, sent){
    //サーバに到達
    console.log(sent);
    /*
    {
        value: {
            content: 'Hello!!!'
        }
    }
    */
}, function(err) {
    //"Permission denied" or "limit exceeded"
});

on()

データストアにイベントを登録するメソッドです。子のデータストアに関する変更に関してもイベントを監視できます。

引数

on(event, callback)

event

イベントをstring形式で指定することができます。

タイプ	概要
"push"	データストアのpushイベントを監視します
"remove"	データストアのremoveイベントを監視します
"set"	データストアのsetイベントを監視します
"send"	データストアのsendイベントを監視します

callback(datum)

指定したイベントに対するコールバックを設定できます。

datum

タイプ	概要
path	更新または追加されたデータストア要素のパス
id	更新または追加されたデータストア要素のID
value	更新または追加された値

戻り値

戻り値はありません。

使い方

var ds_user = milkcocoa.dataStore('user');

//コールバックを設定
ds_user.on('push', function(pushed) {
    console.log('pushed!', pushed.id, pushed.value);
});

ds_user.on('set', function(set) {
    console.log('set!', set.id, set.value);
});

ds_user.on('send', function(sent) {
    console.log('sent!', sent.value);
});

ds_user.on('remove', function(removed) {
    console.log('removed!', removed.id);
});

//どのユーザーがpushしてもon関数は実行される
ds_user.push({
    message : 'I am pushing.'
});

off()

データストアに登録されたイベントを解除します。

引数

off(event)

event: 登録を解除したいイベント名を渡します。

戻り値

戻り値はありません。

使い方

dataStore('user').on('push', function(){...});
dataStore('user').off('push');

get()

特定のデータストア要素をidを指定して取得することができます。

引数

get(id, callback)

id: データストア要素のID
callback(err, datum): コールバック関数を渡すことが出来ます。

戻り値

戻り値はありません。

使い方

milkcocoa.dataStore('users').get('fred', function(err, datum) {
    console.log(datum);
    /*
    {
        id: 'fred',
        timestamp: 12345... ,
        value: {
            ...
        }
    }
    */
});

stream()

データストアからデータを取得するオブジェクトである、Streamオブジェクトを取得するメソッドです。

引数

stream()

引数はありません。

戻り値

Streamオブジェクトを返します。Streamオブジェクトに関してはこちらを御覧ください。

使い方

milkcocoa.dataStore('user').stream().sort('desc').next(function(err, data) {
    console.log(data);
    /*
    [{
        id: 'foo',
        timestamp: 12345... ,
        value: {
            ...
        }
    },
    {
        id: 'bar',
        timestamp: 12345... ,
        value: {
            ...
        }
    }
    ...
    ]
    */
});

history()

データストアからデータを取得するオブジェクトである、Historyオブジェクトを取得するメソッドです。

引数

history()

引数はありません。

戻り値

Historyオブジェクトを返します。Historyオブジェクトに関してはこちらを御覧ください。

使い方

var history = milkcocoa.dataStore('message').history();
history.sort('asc');
history.size(10);
history.limit(100);
var onDataCount = 0;
history.on('data', function(data) {
    console.log(data, ++onDataCount);
    /*
    data -> [{
        id: 'foo',
        timestamp: 12345... ,
        value: {
            ...
        }
    },
    {
        id: 'bar',
        timestamp: 12345... ,
        value: {
            ...
        }
    }
    ...
    ]
    */
});
history.on('end', function() {
    console.log('end');
});
history.on('error', function(err) {
    console.error(err);
});
history.run();

child()

子のデータストアを取得するメソッドできます。もし指定した子が存在しない場合は子が自動で生成され、その子のDataStoreオブジェクトを取得することができます。

引数

child(path)

path: このデータスアへのパスをString形式で指定することができます。

戻り値

指定したパスへのDataStoreオブジェクトを返します。

使い方

var ds_chat = milkcocoa.dataStore('user').child('chat');

Stream

Streamオブジェクトはデータを取得するメソッドです。Streamオブジェクトを発行したDataStore以下にあるidをもつデータストアを取得することが出来ます。

メソッド	詳細
size()	一回で取得するデータの個数を決めます。
sort()	指定した要素でデータを降順にソートします。
next()	データストアからデータの取得を行います。

size()

一回で取得するデータの個数を決めるためのメソッドです。

引数

size(num)

num: データサイズを指定します。デフォルトは50、上限値は999です。

戻り値

条件が追加されたStreamオブジェクトを返します。

使い方

//pushした順番に対して降順で取得
milkcocoa.dataStore('user').stream().size(10).next(function(err, data) {
    console.log(data); // 最新の10件のデータ
});

//データを999個以上取得したい場合は以下の方法を使います

var stream = milkcocoa.dataStore('user').stream().size(999).sort('asc');

function loop(stocks, callback) {
  stream.next(function(err, elems) {
    stocks = stocks.concat(elems); // 結合
    if(elems.length > 0) loop(stocks, callback); // elemsが空になるまでloop()を実行
    else callback(stocks); // コールバックにstocksを渡す
  });
}

loop([], function(data) {
  // dataにすべてのデータが
  data.forEach(function(d,i){
    console.log(d);
  });
});

sort()

指定した要素でデータをソートする条件を追加するメソッドです。降順も昇順も、配列の順番は古い方から並んでいることに注意して下さい。

引数

sort(mode)

mode

ソートの昇順、降順を指定します。

タイプ	概要
"asc"	昇順でソートします。
"desc"	降順でソートします。

戻り値

条件が追加されたStreamオブジェクトを返します。

使い方

//pushした順番に対して昇順で取得
milkcocoa.dataStore('user').stream().sort('asc').next(function(err, data) {
    console.log(data); // 古い方から10件のデータ
});

next()

データの取得を開始するメソッドです。追加された検索条件を元にデータストアからデータを取得し、指定したコールバック関数に渡すことが出来ます。

引数

next(callback)

callback(data): データの取得が完了した際に呼ばれるコールバックを指定します。コールバックの引数に取得したデータを含むオブジェクトが渡されます。

戻り値

戻り値はありません。

使い方

dataStore.stream().next(function(err, data) {
    console.log(data);
});

// ネストすることで続きのデータを取得することが出来ます
var stream = dataStore.stream().size(10).sort('asc');
stream.next(function(err, data) {
    console.log(data); // 1~10番目のデータ
    stream.next(function(err, data) {
        console.log(data); // 11~20番目のデータ
    });
});

History

Historyオブジェクトはデータを取得するメソッドです。データストアにpushされたデータに対して、期間や個数などを指定してデータを取得できます。デフォルト（何も指定せずにrun()を実行すると）では降順で50個のデータを1回だけ取得します。

メソッド	詳細
sort()	データを取得する順番を決めます。
size()	データを何個づつ取得するかを決めます。
limit()	データを全部で何個取得するかを指定します。
span()	データを取得する期間を指定します。
on()	イベントハンドラを設定します。
run()	データの取得を実行します。

sort()

データを取得する順番を決めます。こちらはstream()のsort()とは違い、降順で配列の順番も新しい方から（より直感的）となっています。

引数

sort(sort)

sort

ソートの昇順、降順を指定します。

タイプ	概要
"asc"	昇順でソートします。
"desc"	降順でソートします。

戻り値

条件が追加されたHistoryオブジェクトを返します。

使い方

var history = milkcocoa.dataStore('message').history();
history.sort('desc');

size()

データを何個づつ取得するかを決めます。

引数

size(size)

size: 個数を指定します。1〜999の間で指定できます。

戻り値

条件が追加されたHistoryオブジェクトを返します。

使い方

var history = milkcocoa.dataStore('message').history();
history.size(10);

limit()

データを全部で何個取得するかを指定します。指定した個数の取得が完了すると、'end'イベントが発行されます。limit()はspan()と同時に使用することはできません。

引数

limit(limit)

limit: データ取得上限を指定します。

戻り値

条件が追加されたHistoryオブジェクトを返します。

使い方

var history = milkcocoa.dataStore('message').history();
history.size(10);
history.limit(2000);
// 上記のように書くと'data'イベントが200回発行されます。
history.on('data', function(data) {
    // 200回呼ばれる
    console.log(data);
});

span()

データを取得する期間を指定します。ただし、データの保存時間を「idで判別」するため、この指定は「push()で保存したデータにのみ」有効です。span()はlimit()と同時に使用することはできません。

引数

span(start, end)

start: 期間開始のタイムスタンプ
end: 期間終了のタイムスタンプ

戻り値

条件が追加されたHistoryオブジェクトを返します。

使い方

var history = milkcocoa.dataStore('message').history();
// 2015/10/30-2015/11/3のpush()で保存したデータを取得
history.span(new Date(2015,9,30).getTime(), new Date(2015,10,3).getTime());

on()

イベントハンドラを設定します。

引数

on(event, callback)

event

data,end,errorのいずれかを指定します。

タイプ	概要
"data"	size()で指定したデータ数を取得した都度呼ばれます。コールバックにデータが返ってきます。
"end"	limit()またはspan()で指定したデータ数や期間分の全てのデータを取得し終わったら呼ばれます。
"error"	エラーが起こったら呼ばれます。コールバックにはエラーオブジェクトが返ってきます。

callback(data)

コールバックを指定します。

data: dataイベントの場合は、取得したデータが返ってきます。errorイベントの場合は、エラーオブジェクトが帰ってきます。

戻り値

条件が追加されたHistoryオブジェクトを返します。

使い方

var history = milkcocoa.dataStore('message').history();
history.sort('desc');
history.size(20);
history.limit(100);
history.on('data', function(data) {
    // 100/20 = 5回呼ばれる
    console.log(data);
});
history.on('end', function() {
    console.log('end');
});
history.on('error', function(err) {
    console.error(err);
});
history.run();

run()

データの取得を実行します。

引数

run()

引数はありません。

戻り値

戻り値はありません。

使い方

var history = milkcocoa.dataStore('message').history();
history.sort('desc').size(10).span(new Date(2015, 9, 30).getTime(), new Date(2015, 10, 3).getTime());
history.on('data', function(data) {
    console.log('get data', data);
});
history.on('end', function() {
    console.log('end');
});
history.run();