更新情報

2023-01-25
SEといっても、Gitについて何も知らないと良くないのでとりあえず記事をリンクしました。

2022-01-27
やはりkintone APIの知識もある程度は知っておく方が良いと思うので、下の方に追加しました。

2020-01-31
基本設計の話しでは無いですが、お客様とのお話しで良くあるのがユーザーアカウントの増減の話し。お客様にとっては月々のランニングコストの話しになるのでその場で正確にお伝えすると後々良いかと思います。

2019-12-09

ついに2019年12月のアップデートで、ルックアップコピー項目に複数選択フィールドが選択できるようになりました！
https://kintone.cybozu.co.jp/update/main/2019-12.html

下記のフィールドがルックアップのコピー項目で選択可能に！

複数選択フィールド
チェックボックスフィールド

2019-11-14

kintone の機能追加のスピードが早いです(@@;
開発のやり方を従来と変えたそうです。Cybozu Days で開発者の方が語っていたらしい。

5.ルックアップの罠に下記の通り書いたのですが、

注目は 「ほかのフィールドのコピー」で指定できるフィールド です。
一覧で見るとほとんどコピー出来そうですよね。
テーブルはまあコピー出来ないのも分かりますが（出来ると楽ですが）、 複数選択系はほぼコピー出来ない。

これ、2019/12/08の定期メンテナンスにおける kintone API 更新情報 (2019/11/13) APIに実装されるので、基本機能でも実装されそうですよ（知らないけど）。１２月のアップデート情報に期待です。

はじめに

SEで採用されたからには、ほとんどSEの経験が無くても 「システム設計？出来ますよ（やった事ないけど）」 という振りをしなければなりません。でも経験が無いので結構辛い。

kintone簡単じゃん。と思ってもやっぱり色々と制約が多くて、「出来ますよ」といって持ち帰って要求仕様まとめて、基本設計に入ったら「出来ないじゃん」とか結構あります。

そんな時に役立つリンクをまとめて見たいと思います。

1. kintone の制約

kintoneというか cybozu.com の制約も意外と多いのね。

というわけで、kintoneの運用基盤のcybozu.comの制限事項です。

cybozu.com 制限事項

その中の kintone全般で押さえておきたいポイントは次の２点。

アプリ内のフィールド数上限 500
APIの利用制限 1アプリ10,000リクエスト/日、ドメインごとのAPI同時アクセス数：100

1.のフィールド数のカウントにはラベル、罫線、スペース等は含まれないのでそこまで気にしなくても良いのかな。

kintone 制限値一覧

でも MS Excelで入力フォームを作っていて、それのリプレイス案件などは注意が必要かもです。上限があることをご説明して、なんと無くあるだけのフィールドは設計段階で削除やアプリ分割等の提案も必要かと思います。

2.の日当たりのAPIリクエストや同時アクセス数の方が厄介ですね。
APIでなんでも出来るからいいやとホイホイ受けないことですね。ヒヤリング時点で最初に「どのくらいのアカウント数で利用するのか」や「同時アクセス数」は確認して、難しそうなら無理に kintone で無くても別のアプローチもありますよと提案した方が良いかもです。

100人位で1つのアプリを利用するとあっという間に制限超えとなるケースもありそうです。

2. 関連レコードの罠

関連レコード便利ですね。2つのアプリのキーフィールドを結びつけてアプリ内に表示する。まさにリレーショナル！って感じで感動を覚えました。テーブルと違って事前に設定が必要ですがソート順も設定出来るのも良い感じ。

それで、このアプリのフィールドとあちらの参照先アプリのフィールドを結び付けて「楽勝です」と思ったら、設定画面のフィールドに出てこない。

関連レコード一覧の設定項目「表示するレコードの条件」に指定できるフィールド

まあ大体は問題ないかと思いますが、 日付は紐づいてくれなかった。 計算フィールドで数値に変更したりして苦労してます。
あとはテーブル内部のフィールドもだめ。なのでキーフィールドは最初から意識して決めておく事が大事だと痛感しています。

ヒヤリングの時に「関連レコードで紐づければ」と感じたら、キーフィールドは 文字列（1行）、数値、計算、リンク、レコード番号 ということを思い出して、その場で関連レコード利用の判断が出来ると良いかと思います。

3. 自動計算の罠

自動計算も便利ですね。数値の合計も、文字列の連結にも使います。
自動計算は2つのフィールド「計算」と「文字列（1行）」が用意されていて、当たり前ですが計算結果として何を返すかで違いがあります。

フィールド種類	計算結果	備考
「計算」	数値,日時,日付,時刻,時間	結果はフィールドタイプによる
「文字列（1行）」	文字列

「結構いろいろ出来るじゃん」とか思って、 アプリのレコード番号 を使おうとすると 計算式に含まれるフィールドコードが存在しない、または形式が正しくありません。 とか怒られます。

計算式で参照できるフィールドと、そのフィールドの値のデータ型

アプリのレコード番号が使えると、ユニークキーとして再利用できて便利なのですが。

4. ユーザー情報の取得の罠

APIの話ですが、ログインユーザーの情報はいいんですよ別に。

ユーザー情報の取得

kintone.getLoginUser() で取得出来るので。

でもユーザー管理のアプリを持つまでも無いけど、ユーザーアカウントの情報を cybozu.com の運用基盤側から取得したいというときってありますよね？

でも ユーザーエクスポート API（JSON出力）をご確認ください。
って少し敷居が高く無いですか？

5. ルックアップの罠

最後はルックアップです。

ルックアップを設定する

注目は 「ほかのフィールドのコピー」で指定できるフィールド です。

一覧で見るとほとんどコピー出来そうですよね。
テーブルはまあコピー出来ないのも分かりますが（出来ると楽ですが）、 ~~複数選択系はほぼコピー出来ない。~~

~~チェックボックス、複数選択のフィールドはコピー出来ない。~~
添付ファイルもだめですが、これは出来ると嬉しいのですが。

複数選択系も全て対応していただけると、地味に助かります。

2020-01-31追記

2019年12月のアップデートにて
ルックアップフィールドの、「ほかのフィールドのコピー」で指定できるフィールドに複数選択系が追加されました。
https://jp.cybozu.help/k/ja/user/app_settings/form/lookup/otherfield_copy.html

コピー先	コピー元
チェックボックス	チェックボックス
複数選択	複数選択

その他

ユーザーの使用停止と、契約ユーザー数の関係

2020-01-31追記

上記にあるように、kintoneを利用中のユーザーをcybozu.com共通管理(以下共通管理)から使用停止にした場合でも、請求は止まりません。
請求は

サイボウズドットコムストアでの契約ユーザー数を基準

にされるので、ユーザーの増減処理を行う必要があります。

月契約の場合、反映は翌月1日からとなっています。

ご契約ユーザー数（コース）の変更をご発注いただくと、翌月分から変更後のユーザー数（コース）が課金対象となります。

詳細は、お客様ごとに実際の契約内容を確認ですね。（サイボウズ直とオフィシャルパートナーから購入では違うことがあるかと思います）

一例として、
1/31に10ユーザーを8ユーザーに変更→2/1から8ユーザーの請求が発生。（2月の請求分は8ユーザー）

ユーザー数の追加など、契約内容を変更する

まとめ

行き当たりばったりでアプリを作るのも良いですが、後で出来ませんとならないようにヒヤリングの時点でアプリの構成図（関連図）をイメージして、出来るだけカスタマイズしない標準機能で実装したいなと思っています。

kintone API で出来ること

2022-01-27追記

プログラミングまでやらなくても、カスタマイズでどんなことが出来るのか、できないのかはざっくりと分かってないとダメかもしれないです。
なのでkintone APIについてもまとめておきます。

基本情報

まずはここ、登録して開発環境も取得しましょう。
cybozu developer network
https://developer.cybozu.io/hc/ja

APIのアップデートもチェックです。
kintone API の主なアップデート
https://developer.cybozu.io/hc/ja/articles/900001682323

CSの学習ガイドは上手くまとまってます。
kintone 認定資格カスタマイズスペシャリスト学習ガイド
https://developer.cybozu.io/hc/ja/articles/360022670672

kintoneにカスタマイズJSを登録する方法

基本的には、管理者が「アプリの設定」画面から「JavaScript / CSSでカスタマイズ」を選び、JSやCSSファイルをアップロードします。

注意点は、PCとモバイルは別々にアップロードする必要があります。

モバイルファーストとかで書いていても、スマホ画面で見ると表示されない時は、まずここを疑いましょう。

用語集

・レコード番号とレコードIDの違い
　・レコードIDはほかのレコードと重複しない番号で、必ずユニークな数字。
　・レコード番号もほかのレコードと重複しない番号。アプリコードを設定すると、アプリコードと番号の組み合わせがレコード番号になる。

・kintone REST API
　REST形式でkintoneのデータベースにアクセスすることができるAPIの仕様。
　REST形式でやりとりできる環境があれば、例えばAWS等の外部サービスからでもkintone REST APIのリクエストエンドポイント経由でkintoneのデータにアクセスが可能。

・kintone JavaScript API
　kintoneに用意されたJavaScript用のAPIプログラム。
　kintoneのカスタマイズJSからREST APIにアクセスするkintone.api()などがある。

kintone REST API

kintone REST APIの共通仕様

ここは結構見ていると面白いことが書いてあるので、時々見直すこと。

日付と日時周り

日付、時刻、日時フィールド（作成日時、更新日時フィールドも含む）のデータのフォーマットについて記載があります。
基本的に、日時フィールド（作成日時、更新日時フィールドも含む）はUTCで取得されるので、取得した値を表示したりする際には、変換する必要があります。

日付フィールド→フォーマット：YYYY-MM-DD　月日を省略した場合は01で補完される。2022-7→2022-07-01, 2023→2023-01-01。UTCに変換されない。
日時フィールド→取得時：YYYY-MM-DDTHH:MM:SSZ　「T」と「Z」は固定値。詳細のJSではUTCに変換されるみたいです。"一覧の取得APIでは日時はUTCで出力されます。"の一覧の取得APIが何を指すのか分かりませんが、一覧画面のフィールド情報取得 APIでは、UTCに変換されませんでした。（DOMの情報なので当たり前ですが）

※上記"一覧の取得API"が何を指すのか、cybozuから回答ありました。
https://developer.cybozu.io/hc/ja/articles/201941754/comments/4416452259609

「一覧の取得API」は「一覧の設定の取得」API を指しております。
https://developer.cybozu.io/hc/ja/articles/204529784

どうも、一覧の設定の取得APIにて取得した、絞り込み条件の日時はUTC形式になるということの様です。

確認方法

どんな感じでデータが取れるかを確認する方法です。

kintoneアプリに、日付や日時フィールドを追加した状態で、データを入力して
デベロッパーツールのコンソールから下記を打ち込んで、レコード詳細を見てみます。

レコード詳細取得
https://developer.cybozu.io/hc/ja/articles/201942014#step2

var record = kintone.app.record.get();
console.log(record);

発注日:
type: "DATE"
value: "2022-01-07"

納品日時:
type: "DATETIME"
value: "2022-01-24T00:30:00Z"

更新日時:
type: "UPDATED_TIME"
value: "2022-01-28T02:38:00Z"

取得の際は、UTCで取得されるのでその辺りを考慮。登録の際もUTCを意識してフォーマットを設定する必要がありますね。

CSV書き出しと読み込みの際の日時フォーマットについて

データ移行の際に、CSVファイルで行うことがあるので検証しました。

CSV書き出し→UTCに変換されません。
CSV読み込み→読み込み時のフォーマット補完の設定があるので、UTCを意識しなくても大丈夫でした。

CSV読み込み時は、日付の形式も、エクセルのスラッシュ区切り"YYYY/MM/DD"でも良い感じに読み込み変換してくれるようです。

ユーザー認証

認証周りは一旦飛ばします。

リクエストヘッダ

同じく飛ばします。

レスポンス

HTTPステータスコードが「200」であれば正常終了、それ以外はエラー終了。

kintone JavaScript APIの、kintone.api()を使ってREST APIで情報を取得するときには、レスポンスボディ（つまりレコードのJSON情報）だけなので、レスポンスヘッダーなどが欲しいときには別の手段が必要です。

kintone.api()でリクエストした場合のレスポンスについて
kintone.api()でkintone REST APIをリクエストした際、コールバックに渡される情報はレスポンスボディのみです。
そのため、レスポンスボディ以外の情報を利用する場合はkintone.api()以外でリクエストする必要があります。

kintone JavaScript APIの、kintone.api()を使ってレコード一括取得してみます。
https://developer.cybozu.io/hc/ja/articles/202331474#step2

var body = {
  'app': kintone.app.getId()
};
kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

正常時

エラー時

kintone.api()ではエラー情報についても、簡易的なものが返されるだけなので、レスポンスヘッダーを含んだデータが必要な場合、例えば、下記の kintone-rest-api-client などのライブラリを利用します。
https://developer.cybozu.io/hc/ja/articles/900000767263-kintone-JavaScript-Client-kintone-rest-api-client-

エラーレスポンスがヘッダー情報を含めて取得できます。（正常な時のレスポンスヘッダーは取得できません）
https://github.com/kintone/js-sdk/blob/master/packages/rest-api-client/docs/errorHandling.md#kintonerestapierror

(() => {
  'use strict';
  kintone.events.on('app.record.index.show', (event) => {
    const client = new KintoneRestAPIClient();
    const APP_ID = kintone.app.getId();
    const params = {
      app: APP_ID,
      query: 'order by レコード番号 asc limit 1000 offset 10000'
    };
    client.record.getRecords(params).then((resp) => {
      console.log(resp);
    }).catch((err) => {
      console.log(err.id);
      console.log(err.code);
      console.log(err.headers);
      console.log(err.message);
    });
  });
})();

エラー表示

下記はkintone.proxyを利用する例です。
認証情報のAPIトークンをJSファイルに含めるのはセキュリティ上問題になりますので、本番環境では利用しないでください。
セキュリティに関することは、下記の「セキュアコーディングガイドライン」を確認ください。

セキュアコーディングガイドラインの「認証情報を適切に取り扱う」
https://developer.cybozu.io/hc/ja/articles/201919400#step8

(function() {
  'use strict';
  kintone.events.on('app.record.index.show', function(event) {
    const appId = kintone.app.getId();
    const url = 'https://luck-gk.cybozu.com/k/v1/records.json';
    const headers = {
      'Host': '<subdomain>.cybozu.com:443',
      'X-Cybozu-API-Token': '<API-TOKEN>',
      'Content-Type': 'application/json',
      'X-HTTP-Method-Override': 'GET'
    };
    kintone.proxy(url, 'POST', headers, { 'app': appId }, function(body, status, headers) {
      // success
      console.log(status, JSON.parse(body), headers);
    }, function(error) {
      // error
      console.log(error);
    });
  });
})();

すべてのkintone REST APIのレスポンスヘッダには、次の情報が含まれています。

レスポンスヘッダーを確認する為にはkintone.api()以外の方法で情報を取得することが必要です。

X-ConcurrencyLimit-Limit → 同時接続数の上限値。固定値の100です。
X-ConcurrencyLimit-Running → 現在の同時接続数

同時接続数の情報は、kintone JavaScript API の kintone.api.getConcurrencyLimit で取得することができるので、通常はこちらを使う方が良いかもしれません。
https://developer.cybozu.io/hc/ja/articles/115005946966

制限事項

制限事項も基本設計時には重要な要件になります。

ドメインへの同時接続

APIによる同時接続数はドメインごとに100が上限。

例えば、1000人で使っていて一斉にAPIが動いたときに、上限値に引っかかることもありそうです。
検証したことは無いですが。。。

アプリのレコード操作API

一度に取得できるレコードは500件までです。

500件以上はオフセットしながらレコードを繰り返し取得する必要があります。

レコードの一括取得（クエリで条件を指定）のoffset の上限値は1万件です。

オフセットは1万上限なので、カーソルAPIなど他の方法で取得します。

ちょっと体験してないですが、カーソルAPIにも何気に制限があるので要注意です。
https://developer.cybozu.io/hc/ja/articles/360029152012#step4
カーソルの数は１ドメイン！あたり、10カーソルまでなどなど。。。

・カーソルの作成 API
・カーソルの作成は1ドメインあたり同時に1リクエストのみ実行できます。実行中のリクエストがある場合は待機します。
・有効なカーソルの数は1ドメイン辺り10です。
・上限に達した場合、次のいずれかが発生するまで新しいカーソルを開くことはできません。
・既存のカーソルの1つからすべてのレコードを取得する
・既存のカーソルが自動的に削除される前に、明示的に閉じる
・既存のカーソルの有効期限が切れる
・カーソルの有効期限は、カーソルの作成またはカーソルからレコードを取得による最終リクエスト時刻から10分です。

・一度に登録、更新、および削除できるレコードは100件までです。

登録・更新系のAPIは一度に100件が上限です。
複数アプリへのレコード一括処理
API（バルクリクエスト）を利用して、同一アプリに適用すれば100件 x 20リクエスト = 2000件まで一括でレコード登録することができます。

1つのテーブルに登録できる行数の上限値は5,000行までです。

テーブルに5,000行も入力する運用がちょっと浮かばないですが、上限値があるということだけは知っていた方が良いですね。

レコード取得、登録、更新において、存在しないフィールドコードを指定した場合は、そのフィールドコードへの処理は無視されます。

つまり、フィールドコードを間違って指定しても特にエラーにならないということか？
処理は無視されるの部分がちょっと分かりません。

次のフィールドは、レコードの取得 APIによって値の取得のみできます。レコードの登録API及びレコードの更新APIで値の登録と更新はできません。

ルックアップフィールドによって値が入力されるフィールド
カテゴリー
計算
ステータス (更新は、レコードのステータスの更新 API をご利用ください。)
作業者（更新は、レコードの作業者の更新API をご利用ください。）
レコード登録、更新において、ルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」はレコード番号または「値の重複を禁止する」に設定されている必要があります。
ルックアップフィールドの「コピー元のフィールド」に自動計算の設定をしている「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。

ルックアップコピーと計算については良いですが、カテゴリーについてはAPIで登録・更新ができないのは注意したいです。

ステータスと作業者も、専用のAPIを利用する必要がありそうです。また試してみます。
ステータスはCSVでも更新できないので、それと同じでしょうか。

ルックアップフィールドの値を更新する場合は、「コピー元のフィールド」重複禁止になってないとリクエストが失敗するので注意です。CSVでの更新の場合も同様。
レコード番号で紐づける場合は、レコード番号は必ず一意なので更新の問題もないということですが、できればルックアップのレコード番号ではなく、別途一意の番号を用意した方が後々良いかと思います。

ルックアップの設定時は、コピー元のフィールドが重複禁止でなくてもルックアップ設定ができますが、後でルックアップに指定したフィールドを更新するときは、おそらく重複レコードが増えていると思われるので、（※紐付けするアプリのコピー元のフィールドを重複禁止にしようとしても重複レコードがたくさんで修正も難しい状況）基本設計の時に重複禁止にしておきたいです。

レコードステータスの更新

ステータス「申請中」から「承認」アクションを指定して、APIでステータスを「承認」に変更します。

var body = {
  'app': kintone.app.getId(),
  'id': 2,
  'action': '承認',
};
kintone.api(kintone.api.url('/k/v1/record/status.json', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

User API

ユーザーAPIはcybozu.com共通管理に登録されたユーザー・グループ、組織などのデータにアクセスするAPIです。

User API の共通仕様

認証は、パスワード認証とセッション認証になります。
kintone.api()を使って、kintoneのカスタマイズJSから実行できます。

アクセス権

APIのアクセス権が重要になります。
CSVのAPIは実行に「cybozu.com共通管理者」の権限が必要になります。

2022-02-10現在
・インポート系のAPIには全て、「cybozu.com共通管理者」の権限が必要。
・エクスポート系のAPIは、JSON形式出力のAPIは、全ユーザーでアクセス可。

JSON形式APIのリクエスト

REST APIリクエストのkinton.api()
https://developer.cybozu.io/hc/ja/articles/202166310

エクスポートAPIは、同期型のAPIのためレスポンスが直ぐに返却されません。

kintone.api(kintone.api.url('/v1/users', true), 'GET', {}).then(function(resp) {
  console.log(resp);
}, function(error) {
  console.log(error);
});

セッション認証の場合のレスポンスデータについて

セッション認証を利用した場合のAPIはログインユーザーの権限で実行されます。
kintoneのアプリに、アプリ権限やレコード権限が設定されている場合は、APIのレスポンスもアプリ・レコードの権限に基づいた結果が返却されます。

ユーザーエクスポート API（JSON）

一度に100件まで取得可能。それ以上はoffsetで取得します。
組織に所属している場合は、同じ組織のユーザーが取得されます。
組織に所属していない場合は、組織に所属していないユーザーが取得されます。

その他知っておくと良いこと

Gitについて
https://qiita.com/sy250f/items/56f15d10fa4e84d60212

全てのSEに送りたい。kintone の基本設計で押さえておきたいポイント５選

更新情報

はじめに

1. kintone の制約

2. 関連レコードの罠

3. 自動計算の罠

4. ユーザー情報の取得の罠

5. ルックアップの罠

2020-01-31追記

その他

ユーザーの使用停止と、契約ユーザー数の関係

まとめ

kintone API で出来ること

基本情報

kintoneにカスタマイズJSを登録する方法

用語集

kintone REST API

kintone REST APIの共通仕様

日付と日時周り

確認方法

CSV書き出しと読み込みの際の日時フォーマットについて

ユーザー認証

リクエストヘッダ

レスポンス

制限事項

ドメインへの同時接続

アプリのレコード操作API

レコードステータスの更新

User API

User API の共通仕様

アクセス権

JSON形式APIのリクエスト

セッション認証の場合のレスポンスデータについて

ユーザーエクスポート API（JSON）

その他知っておくと良いこと