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

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

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

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

データの取得 (stream(), history())20,000データ/分
remove()(利用非推奨)コネクション数の上限×30回/分
send()コネクション数の上限×240回/分
その他のメソッドコネクション数の上限×120回/分

Milkcocoa Install

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

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

MilkCocoa

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

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

new MilkCocoa()

MilkCocoaのインスタンスを作ることで、コネクションを確立することができます。DataStoreの取得やログイン機能等もこのインスタンスを通して行います。※現在利用非推奨です。代わりにconnectWithApiKey()を利用ください。

引数
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を入力します。
戻り値

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

使い方
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)
コールバック関数を渡すことが出来ます。エラー処理や作成したユーザー情報の取得に利用してください。
err

アカウント追加に関するエラーを渡します。コールバック関数内でエラー処理をする際に活用してください。

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

アカウントの追加に成功した場合にユーザーの情報がObject形式で渡されます。 失敗した場合はnullが渡されます。 ユーザー情報には以下のプロパティが登録されています。

戻り値

戻り値はありません。

使い方
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)
コールバック関数を渡すことが出来ます。
err

ログアウトに関するエラーを数値で渡します。ログアウトに関して現時点ではフロントエンド側が関与するエラーは存在しません。

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

戻り値はありません。

使い方
milkcocoa.logout();

user()

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

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

アカウント情報取得に関するエラー

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

アカウントの追加に成功した場合にユーザーの情報をObject形式で渡されます。 ログインしていない場合はnullが渡されます。

戻り値

戻り値はありません。

使い方
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)
データがサーバに到達した時点でこのコールバックが呼ばれます。省略可能です。
err

サーバに到達しなかった場合のエラー内容です。デフォルトの設定では、基本的にnullが返されます。

datum

タイプ概要
idプッシュされたデータストア要素のID
valueプッシュされた値
onError(err)
セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数、保存数の上限に達している際に、このコールバックが呼ばれます。
err

エラーの内容

戻り値

戻り値はありません。

使い方
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)
データがサーバに到達した時点でこのコールバックが呼ばれます。省略可能です。
err

サーバに到達しなかった場合のエラー内容です。デフォルトの設定では、基本的にnullが返されます。

datum

タイプ概要
idセットされたデータストア要素のID
valueセットされた値
onError(err)
セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数、保存数の上限に達している際に、このコールバックが呼ばれます。
err

エラーの内容

戻り値

戻り値はありません。

使い方
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)
サーバで削除操作が行われた時点でこのコールバックが呼ばれます。省略可能です。
err

サーバで削除操作が行われなかった場合のエラー内容です。デフォルトの設定では、基本的にnullが返されます。

datum

タイプ概要
id削除されたデータストア要素のID
onError(err)
セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数の上限に達している際に、このコールバックが呼ばれます。
err

エラーの内容

戻り値

戻り値はありません。

使い方
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)
データがサーバに到達した時点でこのコールバックが呼ばれます。省略可能です。
err

サーバに到達しなかった場合のエラー内容です。デフォルトの設定では、基本的にnullが返されます。

datum

タイプ概要
value送信された値
onError(err)
セキュリティルールによりAPIの発行が中断された場合やメッセージ配信数の上限に達している際に、このコールバックが呼ばれます。
err

エラーの内容

戻り値

戻り値はありません。

使い方
//現在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)
コールバック関数を渡すことが出来ます。
err

エラーを返します。成功した時はnullが入っています。

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)
データの取得が完了した際に呼ばれるコールバックを指定します。コールバックの引数に取得したデータを含むオブジェクトが渡されます。
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();