コレクション

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

注釈

バックエンド API にアクセスする場合には、jQuery の読み込み、および、ホワイトリストへの cloud.monaca.mobi の登録 ( 各 OS の設定ファイル上に ) を行います。詳細は、Android の場合はこちら または iOS の場合はこちら をご確認ください。

メソッド/プロパティー

解説

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

利用可能なオプションを、次に記します。

  • propertyNames : 検索対象のユーザーのプロパティーを指定します。指定がない場合、ユーザーのすべてのプロパティーを返します。

  • limit : 結果の件数の上限です。

  • page : 指定したページ以降から、結果を取得します。

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

数値

アイテム数

items

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

 
戻り値

$.Promise オブジェクト

結果の処理には、 done()fail()always() を使用します。

エラーコード

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

-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

利用可能なオプションを、次に記します。

  • propertyNames : 検索対象のユーザーのプロパティーを指定します。指定がない場合、ユーザーのすべてのプロパティーを返します。

  • limit : 結果の件数の上限です。

  • page : 指定したページ以降から、結果を取得します。

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

数値

アイテム数

items

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

 
戻り値

$.Promise オブジェクト

結果の処理には、 done()fail()always() を使用します。

エラーコード

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

-32602

不正なパラメーターです。

例 :

次の例では、 diary コレクション内で検索を行い、 nicknamemy 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 つ取得

指定したアイテムを、コレクションから 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

利用可能なオプション:

  • propertyNames : 検索対象のユーザーのプロパティーを指定します。指定がない場合、ユーザーのすべてのプロパティーを返します。

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

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

 
戻り値

$.Promise オブジェクト

結果の処理には、 done()fail()always() を使用します。

エラーコード

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

-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 つ取得

ユーザーのアイテムを、コレクションから 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

利用可能なオプション:

  • propertyNames: 取得するデータサイズを制限するため、フィルターをかけます。

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

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

 
戻り値

$.Promise オブジェクト

結果の処理には、 done()fail()always() を使用します。

エラーコード

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

-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 つ挿入

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

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

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

パラメーター
item

新規アイテムに関して、ユーザーが定義したデータ

permission

アイテムにパーミッションを設定するときに使用するオブジェクト。オブジェクトに設定する Key は、 “public” ( すべてのユーザーが対象 ) または ユーザーの Oid になります。また、オブジェクトに設定する Value は、 “r” ( 読み取り許可 ) 、 “w” ( 書き込み許可 ) 、 “rw” ( 読み取りと書き込み許可 ) 、 “” ( すべて不許可 ) のいずれかとなります。例 : { “public”: ‘rw’, “oidOfUserA”: ‘r’, “oidOfUserB”: ‘rw’ } 。permission は、Key と Value の組み合わせで設定します。

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

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

 
必須
item

Key 名には、 [a-zA-Z0-9] を使用して、 [a-zA-Z] から始まる必要がります。データサイズは、500 KB 内です。

戻り値

$.Promise オブジェクト

結果の処理には、 done()fail()always() を使用します。

エラーコード

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

-32602

不正なパラメーターです。

-14

パーミッションがありません ( アプリからのデータ挿入が制限されている場合 )。

次の例では、 titlebody_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

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

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

数値

更新したアイテム数

戻り値

$.Promise オブジェクト

結果の処理には、 done()fail()always() を使用します。

エラーコード

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

-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);
});