コレクション

次の関数とプロパティーを使用して、 コレクション を管理します。

メソッド/プロパティー 解説
monaca.cloud.Collection() コレクション オブジェクトを取得します。
monaca.cloud.Collection.find() すべてのユーザーのデータをコレクションから取得します。
monaca.cloud.Collection.findMine() ユーザーのデータをコレクションから取得します。
monaca.cloud.Collection.findOne() 指定したアイテムをコレクションから 1 つ取得します。
monaca.cloud.Collection.findOneMine() ユーザーのアイテムをコレクションから 1 つ取得します。
monaca.cloud.Collection.insert() コレクションにデータを挿入します。
monaca.cloud.Collection.updatePermission() コレクション アイテムのパーミッション ( 権限 ) を一括更新します。

Collection()

指定した名前を使用して、 コレクション オブジェクトを取得します。コレクションは、自動的には作成されないため、 あらかじめ、IDE 上で手動で作成しておきます。

monaca.cloud.Collection(collectionName: string) : Object

パラメーター

パラメーター 型 解説
collectionName 文字列 コレクション名を指定します。

戻り値

  • コレクション オブジェクト

例

"diary" コレクションの取得方法を記します。

var Diary = monaca.cloud.Collection("diary"); // returns Collection object

Collection.find()

すべてのユーザーのデータをコレクションから取得します。.

Collection.find(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

パラメーター

パラメーター 型 解説
criteria 文字列 Criteria または 文字列
orderBy 文字列 field_name ASC|DESC。並べ替え条件を複数指定する場合には、配列を使用します。例 ： [“title ASC”, “author ASC”]
options JSON オブジェクト 利用可能なオプションを、次に記します。
  • propertyNames: 検索対象のユーザーのプロパティーを指定します。指定がない場合、ユーザーのすべてのプロパティーを返します。
  • limit: 結果の件数の上限です。
  • page: 指定したページ以降から、結果を取得します。

戻り値

型 解説
$.Promise オブジェクト 結果の処理には、 done()、fail()、always() を使用します。

done() コールバック関数の result パラメーター

  • totalItems: アイテム数
  • items: コレクション アイテムの配列

エラーコード

エラーが発生すると、Error オブジェクトを返します。

コード 解説
-32602 不正なパラメーターです。

例

次の例では、 diary コレクション内で検索を行い、 Criteria に一致したアイテムを、 "_createdAt" プロパティー順 ( 降順 ) でソートして返します。返されるアイテムは、 "title" と "body" の 2 つのプロパティーを保持しています。

var Diary = monaca.cloud.Collection("diary");
var Criteria = monaca.cloud.Criteria('title == "Monaca"');
Diary.find(Criteria, "_createdAt DESC", {propertyNames: ["title", "body"], limit: 5})
.done(function(result)
{
    console.log('Total items found: ' + result.totalItems);
    console.log('The body of the first item: ' + result.items[0].body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

または、criteria に文字列を指定して、渡すこともできます。

var Diary = monaca.cloud.Collection("diary");
Diary.find('title == "Monaca"', "", {propertyNames: ["title", "body"], limit: 5})
.done(function(result)
{
    console.log('Total items found: ' + result.totalItems);
    console.log('The body of the first item: ' + result.items[0].body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.findMine()

ユーザーのデータを、コレクションから取得します。

Collection.findMine(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

パラメーター

パラメーター 型 解説
criteria 文字列 Criteria または 文字列
orderBy 文字列 field_name ASC|DESC。並べ替え条件を複数指定する場合には、配列を使用します。例 ： [“title ASC”, “author ASC”]
options JSON オブジェクト 利用可能なオプションを、次に記します。
  • propertyNames: 検索対象のユーザーのプロパティーを指定します。指定がない場合、ユーザーのすべてのプロパティーを返します。
  • limit: 結果の件数の上限です。
  • page: 指定したページ以降から、結果を取得します。

戻り値

型 解説
$.Promise オブジェクト 結果の処理には、 done()、fail()、always() を使用します。

done() コールバック関数の result パラメーター

  • totalItems: アイテム数
  • items: コレクション アイテムの配列

エラーコード

エラーが発生すると、Error オブジェクトを返します。

コード 解説
-32602 不正なパラメーターです。

例

次の例では、 diary コレクション内で検索を行い、 nickname が my nickname に一致したアイテムを、 "_createdAt" プロパティー順 ( 降順 ) でソートして返します。返されるアイテムは、 "title" と "body" の 2 つのプロパティーを保持しています。

var Diary = monaca.cloud.Collection("diary");
Diary.findMine('nickname == "my nickname"', "", {propertyNames: ["title", "body"], limit: 5})
.done(function(result)
{
    console.log('Total items found: ' + result.totalItems);
    console.log('The body of the first item: ' + result.items[0].body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.findOne()

指定したアイテムを、コレクションから 1 つ取得します。複数のアイテムが条件に合う場合には、最初のアイテムを返します。

Collection.findOne(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

パラメーター

パラメーター 型 解説
criteria 文字列 Criteria または 文字列
orderBy 文字列 field_name ASC|DESC。並べ替え条件を複数指定する場合には、配列を使用します。例 ： [“title ASC”, “author ASC”]
options JSON オブジェクト 利用可能なオプション:
  • propertyNames: 検索対象のユーザーのプロパティーを指定します。指定がない場合、ユーザーのすべてのプロパティーを返します。

戻り値

型 解説
$.Promise オブジェクト 結果の処理には、 done()、fail()、always() を使用します。

done() コールバック関数の result パラメーター

  • items: コレクション アイテム [ result が空の場合には、ヌル ( null ) となります ]

エラーコード

エラーが発生すると、Error オブジェクトを返します。

コード 解説
-32602 不正なパラメーターです。

例

次の例では、 diary コレクション内で検索を行い、Criteria に一致したアイテムを、 "_createdAt" プロパティー順 ( 降順 ) にソートして返します。

var Diary = monaca.cloud.Collection("diary");
Diary.findOne('title == "Monaca"', "_createdAt DESC")
.done(function(result)
{
    console.log('The body of the item: ' + result.body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.findOneMine()

ユーザーのアイテムを、コレクションから 1 つ取得します。複数のアイテムが条件に合う場合には、最初のアイテムを返します。

Collection.findOneMine(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

パラメーター

パラメーター 型 解説
criteria 文字列 Criteria または 文字列
orderBy 文字列 field_name ASC|DESC。並べ替え条件を複数指定する場合には、配列を使用します。例 ： [“title ASC”, “author ASC”]
options JSON オブジェクト 利用可能なオプション:
  • propertyNames: 取得するデータサイズを制限するため、フィルターをかけます。

戻り値

型 解説
$.Promise オブジェクト 結果の処理には、 done()、fail()、always() を使用します。

done() コールバック関数の result パラメーター

  • items: コレクション アイテム [ result が空の場合には、ヌル ( null ) となります ]

エラーコード

エラーが発生すると、Error オブジェクトを返します。

コード 解説
-32602 不正なパラメーターです。

例

次の例では、 diary コレクション内で検索を行い、Criteria に一致したアイテムを、 "_createdAt" プロパティー順 ( 降順 ) にソートして返します。

var Diary = monaca.cloud.Collection("diary");
Diary.findOneMine('title == "Monaca"', "_createdAt DESC")
.done(function(result)
{
    console.log('The body of the item: ' + result.body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.insert()

コレクション にアイテムを 1 つ挿入します。

Collection.insert(item: Object, [permission: Object]) : $.Promise

パーミッション ( 権限 ) の設定に関わらず、ユーザーの所有者には、読み取りと書き込み権限が与えられています。

パラメーター

パラメーター 型 解説 必須
item JSON オブジェクト 新規アイテムに関して、ユーザーが定義したデータ Key 名には、 [a-zA-Z0-9] を使用して、 [a-zA-Z] から始まる必要がります。データサイズは、500 KB 内です。
permission JSON オブジェクト アイテムにパーミッションを設定するときに使用するオブジェクト。オブジェクトに設定する Key は、 “public” ( すべてのユーザーが対象 ) または ユーザーの Oid になります。また、オブジェクトに設定する Value は、 “r” ( 読み取り許可 ) 、 “w” ( 書き込み許可 ) 、 “rw” ( 読み取りと書き込み許可 ) 、 “” ( すべて不許可 ) のいずれかとなります。例 : { “public”: ‘rw’, “oidOfUserA”: ‘r’, “oidOfUserB”: ‘rw’ } 。permission は、Key と Value の組み合わせで設定します。

戻り値

型 解説
$.Promise オブジェクト 結果の処理には、 done()、fail()、always() を使用します。

done() コールバック関数の result パラメーター

  • items: コレクション アイテムの配列

エラーコード

エラーが発生すると、Error オブジェクトを返します。

コード 解説
-32602 不正なパラメーターです。
-14 パーミッションがありません ( アプリからのデータ挿入が制限されている場合 )。

例

次の例では、 title 、 body 、 _createdAt の 3 つのフィールドを持つアイテムを、 "diary" コレクションに挿入します。挿入後、 x00000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx ( id ) を所持するユーザーに対して、このアイテムへの読み取り専用のパーミッションを与えます。

var Diary = monaca.cloud.Collection("diary");
var friendUserOid = "x00000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
var permission = {};
permission[friendUserOid] = "r";

Diary.insert({title: 'Any title', body: 'Hello World'}, permission)
.done(function(result)
{
    console.log("Inserted!");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.updatePermission()

コレクションアイテムのパーミッション ( 権限 ) を、一括更新します。

Collection.updatePermission(criteria: Criteria or String, permission: Object, [options: Object]) : $.Promise

パラメーター

パラメーター 型 解説
criteria 文字列 Criteria または 文字列
permission JSON オブジェクト パーミッションを指定するオブジェクト。rw は読み取りと書き込み、 r は読み取り専用、 w は書き込み専用、空の文字列は 「 パーミッションなし 」 となります。利用可能なオプションとして、
  • forceOverwrite: boolean があります。こちらのオプションを使用して、現在のパーミッションの上書きを行うか否か決定します ( デフォルト : false ) 。

戻り値

型 解説
$.Promise オブジェクト 結果の処理には、 done()、fail()、always() を使用します。

done() コールバック関数の result パラメーター

  • numUpdates: 更新したアイテム数

エラーコード

エラーが発生すると、Error オブジェクトを返します。

コード 解説
-32602 不正なパラメーターです。
-14 パーミッションがありません ( アプリからのデータ挿入が制限されている場合 )。

例

次の例では、読み取りと書き込みのパーミッションを User X へ、読み取りのみのパーミッションを User Y へ与えます。

var Diary = monaca.cloud.Collection("diary");

var oids =
{
    userX: "x00000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    userY: "x00000000-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
};

var newPermission = {};
newPermission[oids.userX] = "rw";
newPermission[oids.userY] = "r";

Diary.updatePermission('group_id == 1', newPermission)
.done(function(result)
{
    console.log(result.numUpdates + " items updated");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

関連項目：