JavaScript
AdventCalendar
kintone
AdventCalendar2016
kintoneDay 3

kintone Utility for JavaScript を使ってみたよ

More than 1 year has passed since last update.

こちらkintone Advent Calendar 2016 3日目の記事になります。

今回は2ヶ月ほど前にこっそりリリースされた kintone Utility for JavaScript の紹介をさせてもらおうかと思います。

kintone Utility for JavaScript は kintone API をより手軽に利用するためのライブラリになっています。

例えば、kintone Rest APIでは複数レコードの取扱が100件(GETは500件まで)になっており、それ以上の件数を処理する場合は再帰処理を書く必要がありました。これはJSを始めたばかりの方には難易度が高いです。

他にも、DB処理ではよく利用されるUPSERT機能というのがありますが、kinotneで同じことをしようと思うとGETして ある/なし を判断してPOSTかPUT化で振り分けて...とかなり手間でした。

そのような部分をより手軽に扱えるように関数を呼び出すだけで よしなに 処理してくれるライブラリになっています。

本文はほぼこちらの和訳です。


導入方法


ダウンロード

こちらのページから kintoneUtility.min.jsをダウンロード


アプリへ設定

ダウンロードした kintoneUtility.min.js をアプリに設定します。(JavaScriptやCSSでアプリをカスタマイズする)



kintoneUtility kintoneUtility.rest.getRecord

レコード1件取得


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.id
Number

レコードID

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

var param = {

app: 146,
id: 1,
isGuest: false
};

kintoneUtility.rest.getRecord(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null ,' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


kintoneUtility.rest.getRecords

複数のレコード取得


  • 取得できるレコードの上限は500件です


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.query
String
×
クエリ文字列

param.fields
Array
×
取得するフィールドコード指定
指定しない場合はアクセスできる
すべてのフィールドが返却される

param.totalCount
Boolean
×
true: クエリ条件にヒットしたレコードのトータル件数(totalCount)が返却される
false: トータル件数(totalCount)にnullが入って返却される

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

var param = {

app: 146,
query: 'テキストフィールド != "" limit 500 offset 100',
fields: ['$id', '数値フィールド'],
totalCount: true,
isGuest: false
};

kintoneUtility.rest.getRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null ,' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


kintoneUtility.rest.getAllRecordsByQuery

クエリ条件に合う全レコード取得


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.query
String
×

クエリ文字列
※ limit, offsetパラメータの使用はできません

param.fields
Array
×
取得するフィールドコード指定
指定しない場合はアクセスできるすべてのフィールドが返却される

param.totalCount
Boolean
×
true: クエリ条件にヒットしたレコードのトータル件数(totalCount)が返却される
false: トータル件数(totalCount)にnullが入って返却される

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

var param = {

app: 146,
query: 'テキストフィールド != ""',
fields: ['$id', '数値フィールド'],
totalCount: true,
isGuest: false
};

kintoneUtility.rest.getAllRecordsByQuery(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null ,' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


kintoneUtility.rest.postRecord

レコード1件登録


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.record
Object
×
レコード情報 (詳細はこちら)
設定しない場合、デフォルトのフィールド設定値で登録されます
存在しないフィールドが設定されている場合、そのフィールドは無視されエラーとなりません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

var record = {

'フィールド1': {
value: 12345
},
'フィールド2': {
value: 'こんにちは'
}
};
var param = {
app: 146,
record: record,
isGuest: false
};

kintoneUtility.rest.postRecord(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンスデータ

{

"id": "60",
"revision": "1"
}


kintoneUtility.rest.postRecords

複数のレコード登録


  • 登録できるレコードの上限は2000件です

  • レコード数が2000件より多い場合エラーとなります

  • いずれかのレコード登録に失敗した場合は、すべてのレコード登録処理がロールバックされます


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.records
Array
×
レコードオブジェクトの配列 (レコード情報の詳細はこちら)
設定しない場合、デフォルトのフィールド設定値で登録されます
存在しないフィールドが設定されている場合、そのフィールドは無視されエラーとなりません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

var record = {

'フィールド1': {
value: 12345
},
'フィールド2': {
value: 'こんにちは'
}
};
var param = {
app: 146,
record: record,
isGuest: false
};

kintoneUtility.rest.postRecord(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{
"ids": [
"61",
"62"
],
"revisions": [
"1",
"1"
]
}]
}


kintoneUtility.rest.postAllRecords

すべてのレコード登録

登録できるレコードの上限はありませんが、内部的には kintoneUtility.rest.postRecords と同様の仕組みで繰り返し処理を行っているようなので2000件ずつ登録処理を行うが、失敗した場合は対象の2000件のブロックのレコードのみロールバックされます

例えば6000個のレコードを登録するとします。その場合レコードはリクエストごとに以下のブロックに属します。

リクエストが分かれるブロック
対象となるレコード

1ブロック
1〜2000

2ブロック
2001〜4000

3ブロック
4001〜6000

それぞれのブロックは個別のリクエスト処理を行っているため、ブロック内ではロールバックは有効となりますが、ブロックを跨いでロールバックが有効にはなりません。

では、この時2500件目でエラーが出るとしましょう。その場合は以下のような結果となります。

リクエストが分かれるブロック
処理結果

1ブロック
2000件全てのレコードが登録される

2ブロック
ロールバックされレコードは登録されない

3ブロック
登録処理が行われない


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.records
Array
×
レコードオブジェクトの配列 (レコード情報の詳細はこちら)
設定しない場合、デフォルトのフィールド設定値で登録されます
存在しないフィールドが設定されている場合、そのフィールドは無視されエラーとなりません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

var records = [{

'フィールド1': {
value: 1234
},
'フィールド2': {
value: 'こんにちは'
}
}, {
'フィールド3': {
value: 5678
},
'フィールド4': {
value: 'こんばんは'
}
}];
var param = {
app: 146,
records: records,
isGuest: false
};

kintoneUtility.rest.postAllRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{
"ids": [
"18",
"19"
],
"revisions": [
"1",
"1"
]
}]
}


kintoneUtility.rest.putRecord

レコード1件更新


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.id
Number
× ※1

レコードID

param.updateKey
Object
× ※1

このパラメータに設定するフィールドは [値の重複を禁止する][必須項目にする] が有効になっている必要があります

param.updateKey.field
String
× ※1

主キーとなるフィールドコード

param.updateKey.value
String
× ※1

主キーとなるフィールドの値

param.revision
Number
×
リビジョン番号
値が一致しない場合はエラーとなります
値が指定されていないか-1の場合リビジョン番号はチェックはされません

param.record
Object
×
レコード情報 (詳細はこちら)
設定しない場合、デフォルトのフィールド設定値で登録されます
存在しないフィールドが設定されている場合、そのフィールドは無視されエラーとなりません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue

※1 param.id、param.updateKeyのどちらかは必ず指定する必要があります。


サンプルコード


レコードIDでの更新

    var record = {

'フィールド1': {
value: 9876
},
'フィールド2': {
value: 'Hello'
}
};
var param = {
app: 146,
id: 5,
record: record,
isGuest: false
};

kintoneUtility.rest.putRecord(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


updateKeyでの更新

    var record = {

'フィールド3': {
value: 4321
},
'フィールド4': {
value: 'Hello'
}
};
var key = {
field: '更新キー',
value: 'App-008'
};
var param = {
app: 146,
updateKey: key,
record: record,
isGuest: false
};

kintoneUtility.rest.putRecord(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"revision": "3"
}


kintoneUtility.rest.putRecords

複数のレコード更新


  • 更新できるレコードの上限は2000件です

  • レコード数が2000件より多い場合エラーとなります

  • いずれかのレコード更新に失敗した場合は、すべてのレコード更新処理がロールバックされます


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.records
Array

レコードID、updateKeyを含んだレコードオブジェクトの配列 (詳細はこちら)

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue

※ 更新時の主キーとなるid/updateKeyについてはこちらのパラメータを参照


サンプルコード

    var records = [{

id: 10,
record: {
'フィールド1': {
value: 9876
},
'フィールド2': {
value: 'Hello'
}
}
}, {
updateKey: {
field: '更新キー',
value: 'App-008'
},
record: {
'フィールド3': {
value: 4321
},
'フィールド4': {
value: 'Hello'
}
}
}];
var param = {
app: 146,
records: records,
isGuest: false
};

kintoneUtility.rest.putRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{
"records": [{
"id": "10",
"revision": "14"
}, {
"id": "8",
"revision": "9"
}]
}]
}


kintoneUtility.rest.putAllRecords

すべてのレコード更新


  • 登録できるレコードの上限はありませんが、内部的には kintoneUtility.rest.putRecords と同様の仕組みで繰り返し処理を行っているようなので2000件ずつ登録処理を行うが、失敗した場合は対象の2000件のブロックのレコードのみロールバックされます


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.records
Array

レコードID、updateKeyを含んだレコードオブジェクトの配列 (詳細はこちら)

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue

※ 更新時の主キーとなるid/updateKeyについてはこちらのパラメータを参照


サンプルコード

    var records = [{

id: 2,
record: {
'フィールド1': {
value: 10000
},
'フィールド2': {
value: 'hoge'
}
}
}, {
updateKey: {
field: '更新キー',
value: 'App-012'
},
record: {
'フィールド3': {
value: 9999
},
'フィールド4': {
value: 'fuga'
}
}
}];
var param = {
app: 146,
records: records,
isGuest: false
};

kintoneUtility.rest.putAllRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{
"records": [{
"id": "2",
"revision": "3"
}, {
"id": "12",
"revision": "6"
}]
}]
}


kintoneUtility.rest.deleteRecords

複数のレコード削除


  • 削除できるレコードの上限は2000件です

  • レコード数が2000件より多い場合エラーとなります

  • いずれかのレコード削除に失敗した場合は、レコード削除処理がロールバックされます


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.ids
Array

削除対象対象となるレコードIDの配列

param.revisions
Array
×
予想されるリビジョン番号
1番目のID番号は配列の1番目のリビジョン番号に対応し、2番目のIDは2番目のリビジョン番号に対応します。
値が一致しない場合はエラーとなります
値が指定されていないか-1の場合リビジョン番号はチェックはされません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

    var ids = [

6,
16
];
var param = {
app: 146,
ids: ids,
isGuest: false
};

kintoneUtility.rest.deleteRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{}]
}


kintoneUtility.rest.deleteAllRecords

指定されたIDすべてのレコード削除


  • 2000件以上のレコードも削除できるがロールバックはされません


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.ids
Array

削除対象対象となるレコードIDの配列

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

    var ids = [

4,
14
];
var param = {
app: 146,
ids: ids,
isGuest: false
};
kintoneUtility.rest.deleteAllRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{}]
}


kintoneUtility.rest.deleteAllRecordsByQuery

クエリ条件に合うすべてのレコード削除


  • 2000件以上のレコードも削除できるがロールバックはされません


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.query
String
No

クエリ文字列
※ limit, offsetパラメータの使用はできません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

    var param = {

app: 146,
query: 'フィールド1 = "1234"',
isGuest: false
};

kintoneUtility.rest.deleteAllRecordsByQuery(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{}


kintoneUtility.rest.upsertRecord

レコード1件を登録もしくは更新


  • updateKeyが存在しない場合はレコードを登録する

  • updateKeyが存在する場合はレコードを更新する


パラメータ

名称
データタイプ
必須
説明

param.app
Number

アプリID

param.updateKey
Object

このパラメータに設定するフィールドは [値の重複を禁止する][必須項目にする] が有効になっている必要があります

param.updateKey.field
String

主キーとなるフィールドコード

param.updateKey.value
String

主キーとなるフィールドの値

param.revision
Number
×
リビジョン番号
値が一致しない場合はエラーとなります
値が指定されていないか-1の場合リビジョン番号はチェックはされません

param.record
Object
×
レコード情報 (詳細はこちら)
設定しない場合、デフォルトのフィールド設定値で登録されます
存在しないフィールドが設定されている場合、そのフィールドは無視されエラーとなりません

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue


サンプルコード

    var record = {

'フィールド1': {
value: 5555
},
'フィールド2': {
value: 'fugafuga'
}
};
var param = {
app: 146,
updateKey: {
field: '更新キー',
value: 'App-010'
},
record: record,
isGuest: false
};

kintoneUtility.rest.upsertRecord(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"revision": "15"
}


kintoneUtility.rest.upsertRecords

複数のレコードを登録もしくは更新


  • updateKeyが存在しない場合はレコードを登録する

  • updateKeyが存在する場合はレコードを更新する

  • 上限については試せていないため不明です


パラメータ

名称
データタイプ
必須
説明

param
Object

param.app
Number

アプリID

param.records
Object

レコードオブジェクトの配列 (レコード情報の詳細はこちら)

param.isGuest
Boolean
×
デフォルトはfalse
アプリがゲストスペース内にある場合はtrue

※ 更新時の主キーとなるid/updateKeyについてはこちらのパラメータを参照


サンプルコード

    var records = [{

updateKey: {
field: '更新キー',
value: 'App-003'
},
record: {
'フィールド3': {
value: 'upsert 003'
}
}
}, {
updateKey: {
field: '更新キー',
value: 'App-011'
},
record: {
'フィールド4': {
value: 999999
}
}
}];
var param = {
app: 146,
records: records,
isGuest: false
};

kintoneUtility.rest.upsertRecords(param).then(function(resp) {
// 成功時の処理を記載する
console.log(JSON.stringify(resp, null, ' '));
}).catch(function(error) {
// エラー時の処理を記載する
console.log(error.message);
});


成功時のレスポンス

{

"results": [{
"records": [{
"id": "3",
"revision": "4"
}, {
"id": "11",
"revision": "3"
}]
}]
}