データ連携に奮闘中の皆様、いかがお過ごしでしょうか。
HULFT Square とkintoneをつなぐ際の3種類の方法のメリット・デメリットを、見ていきたいと思います。
| 観点 | 1. kintone接続 | 2. kintone API接続 | 3. REST接続(トークン) |
|---|---|---|---|
| 認証 | ユーザーログイン | ユーザーログイン | APIトークン |
| 設定の簡単さ | ◎ | ○ | △ |
| GUIでのマッピング | ◎ | ○ | △ |
| 最小権限の実現 | △ | △ | ◎ |
| ページング | 設定項目あり | 項目なし | 必要なら自分で設定 |
| レコードのCRUD | ◎ | 指定不可 | 自分で組み立て |
| ファイル操作 | 対応 | 指定不可 | 自分で組み立て |
| 専用オペレーションにないAPI | 不可 | ○ | ○ |
| User API | 不可 | 不可 | 手段として案内あり |
| ゲストスペース | 要確認 | 設定項目あり | URLで指定 |
| 複数アプリの扱い | 1コネクションで可 | 1コネクションで可 | トークン管理が必要 |
| 実装の保守しやすさ | ◎ | ○ | △ |
kintone側の認証の違い
| 認証 | 内容 |
|---|---|
| ユーザーログイン | ユーザー名とパスワードで認証します。操作はそのユーザーの権限で動きます。 |
| APIトークン | アプリごとに発行します。トークンに付けた権限(閲覧、追加、編集、削除など)の範囲で動きます。APIトークンはヘッダー X-Cybozu-API-Token で渡します。1リクエストに複数アプリのトークンをカンマ区切りで指定できます。 |
方式1:kintone接続(レコード取得などの専用オペレーション)
概要
レコード取得、レコード追加、レコード更新、テーブル読み取りなどの専用オペレーションです。フィールド一覧を読み込んでGUIでマッピングできます。
メリット
設定が簡単です。フィールド情報を取得して、そのままマッピングに使えます。
ページングを設定項目で指定できます。「ページングを有効にする」にチェックを入れると、取得件数(既定は500件)と方式を選べます。
ページングの方式は3種類です。offset(合計1万件以下向け)、カーソルAPI、レコードID順があります。
添付ファイルをHULFT Squareのストレージへ出力できます。
大容量データ処理を選べます。
デメリット
ユーザーのパスワードに依存します。異動、退職、パスワード変更で突然止まるおそれがあります。
権限がログインしたユーザーに紐づくため、必要以上に広い権限になりがちです。
ページングを無効にすると、kintone API既定の100件しか取得されません。チェックし忘れると欠損に気づきにくくなります。
ページングを有効にしたときは、検索クエリに offset や limit を書けません。
kintoneコネクターで使えるのはkintone REST APIだけで、User APIは使えません。
方式2:kintone API接続(API呼び出し)
概要
「API種別」を選んで、kintone REST APIを呼び出すオペレーションです。入出力はXML型で、スキーマは自動で読み込まれます。
メリット
専用オペレーションがないAPIを、同じコネクションで呼べます。
ゲストスペースを有効にして、ゲストスペースIDを指定できます。
認証は方式1と同じコネクションなので、トークンを別に管理する必要がありません。
大容量データ処理に対応しています。
デメリット
次のAPIは指定できません。
レコード取得、登録、更新、削除
レコード一括取得
ファイルのアップロードとダウンロード
API一覧の取得、APIスキーマ情報の取得
ページングの設定項目がありません。
ユーザーログインなので、方式1と同じパスワード依存と権限の課題があります。
方式3:REST接続(APIトークン)
概要
汎用のRESTコネクターで、kintone REST APIを直接呼びます。URLとヘッダー、リクエストの内容を自分で指定します。
メリット
APIトークンで認証できます。アプリ単位で権限を「閲覧のみ」などに絞れるため、最小権限にしやすくなります。
個人のパスワードに依存しないので、異動や退職の影響を受けません。
トークンは再生成や無効化ができます。漏えいしたときの影響範囲もアプリ単位に限定できます。
kintoneコネクターで扱えないAPI(User APIなど)を呼ぶときの手段になります。サポートの案内も、RESTコネクターなど汎用のコネクターで要件を満たせるかの確認です。
同じ作り方を、kintone以外のSaaS連携にも流用できます。
デメリット
URL、ヘッダー(X-Cybozu-API-Token)、リクエストボディを自分で組み立てます。
ページングは必要な場合に自分で設定します。500件を超える取得では、offset や cursor の繰り返しを組み込みます。
複数アプリを扱うには、アプリごとのトークン管理が必要です。
トークンが漏れると、そのアプリのデータを操作されます。ログやスクリーンショットに残さないよう注意が必要です。
レスポンスのスキーマ定義とマッピングに手間がかかります。
トークンで許可されるAPIの範囲に限られます。
運用面での観点
連携用ユーザーを用意する
方式1と方式2では、個人のアカウントを使わず、連携専用のkintoneユーザーを作るのが現実的です。専用ユーザーにすると、異動や退職の影響を避けられ、権限もまとめて管理できます。
権限をどこまで絞れるか
方式3は、トークン単位で権限を絞れます。方式1と方式2は、連携用ユーザーの権限設定で絞ります。この場合、ユーザーが見られるアプリすべてが操作対象になるので、アプリの権限設計が前提になります。
エラー時の切り分け
方式1と方式2では、読み取り対象のフィールドの設定漏れや、401エラー(認証ヘッダーの不正)が出た事例があります。サブドメイン名の誤りも、コネクターのエラーとして定義されています。方式3では、URL、ヘッダー、ボディのどこが誤っているかを自分で切り分けます。
使い分けの目安
| 場面 | おすすめ方式 |
|---|---|
| まず試したい、PoC | 1 |
| レコードを定期的に取得して他システムへ連携 | 1 |
| 専用オペレーションにないAPIを呼びたい | 2 |
| アクセス範囲をアプリ単位で絞りたい | 3 |
| 個人アカウントに依存したくない | 3 |
| (連携専用ユーザー) | 1、2 |
| User APIなどkintoneコネクターで扱えないAPIが必要 | 3 |