LoginSignup
43
33

More than 5 years have passed since last update.

kintoneAdvent Calendar 2016Day 3
@kiku38

kintone Utility for JavaScript を使ってみたよ

Last updated at Posted at 2016-12-02

こちら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"
        }]
    }]
}
43
33
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
43
33