kintoneAPIのつまずきをまとめる

Date2026/07/10 Last Modified2026/07/10

概要

社内の独自アプリケーションを使い、kintoneへのCSVアップロード、またレコードのダウンロードをする機能を開発することになった。
APIをつなげるだけかと思っていたら、独特な仕様に結構つまずいたので備忘録として。

CSVアップロードとフォームは違う。JSバリデーションという罠

kintoneは"アプリ"という場所にデータを格納する。（フォーム機能＋テーブルのような感じ）
アプリへレコードを追加するとき、2種類の方法が存在する。

フォームで1件ずつ追加
CSVでまとめてアップロード

ここで、フォームに関してはJSファイルを定義することにより、独自のバリデーションをかけることができる。
例えばカラムで「サービスAを選んだ場合、選べるプランはBに固定する」など、項目の選択に応じて動的にバリデーションをかけたり「氏名の姓と名に全角スペースを入れる」のような正規表現が必要な制約も入れられる。
しかし、CSVで一括アップロードする場合は、必須や型のバリデーションはできるが、JSバリデーションはかけられないという罠がある。
これにより、CSVアップロードでは不正なデータも登録できてしまう。
現場ではExcelシートに制限を事細かに書いて対応していたようだが、間違ってしまうことも多かった模様。

そのため、kintone内に別アプリを作ったり、カスタムCSVアップロード画面を作ったりすればよいそうなのだが、kintoneの業務フローを変えたくないというのと、kintoneに詳しい技術者がおらず、前段にバリデーション可能なCSVアップロードWEBアプリを1つ作ってしまうことになった。

ここで大変だったのは「kintoneほどの有名システムで、そんな融通が利かないわけないでしょ！」という意見を否定するのに時間がかかったことである……。
ドキュメントを隅々まで読んで、フォームとCSVアップロードでは処理のフローが異なっていることがわかったので、それで一応納得してもらえた。
AIにも聞きながらこの結論に至ったのだが、他によい方法があれば試してみたい。

lookupフィールドにはAPIが必要

CSVアップロードアプリを作成するにあたって、フォームに入っていたJSバリデーションを洗い出し、それをCSVに適用する形になった。
単純にJSファイルの処理をPHPに変換するだけなので、そこまでは難しくない。
むしろ大変だったのは、API経由のCSVアップロード処理の方だった。

API経由でCSVアップロードした場合、扱いとしては"トークンを持った未ログインユーザー"である。
このユーザーは、通常ユーザーとしてkintoneへログインしたときと異なり、トークンのあるアプリ単位にしかアクセスできないという制限がある。
データを参照するだけならさしたる問題はないのだが、更新するときはlookupフィールドという制限に突き当たる。

lookupフィールドとは、optionsのように決められた選択肢から選ぶフィールドで、選択肢の内容は別アプリのデータを参照している。
つまるところ、その別アプリのデータを取得しないことにはlookupの候補すら出すことができずエラーで落ちてしまうのだ。

これの解決策として、すべてのappIdを保持しておくのと、X-Api-Tokenに複数のトークンを付与することである。
1リクエストに複数トークンを載せるのは初めての例だった。

更新者の切り分けは論理名

アップロードを代替するアプリケーションとして、更新者をアカウント単位で切り分ける必要があった。
それで、IDを結びつける必要があるのかなと思って必死に探していたのだが……。

kintoneポータルより上位にアクセス制限がある

いよいよ本番で稼働させようと思ったとき、テストで実行してみたところ403エラーになった。
APIトークンを持っていても、許可されたIPアドレスしかリクエストできないということが判明する。

kintoneより上位にcybozu管理画面が存在し、そこでアクセス制限を導入している場合はIPリストが規定できるよう。
社内からAPIを叩いてOKだったので、そういった制限があることが完全に盲点になっていた……。
普通にkintoneアプリにログインする場合と、APIをする場合で共通のリストを使うようで、たまたま社内で作業者がいたからリストに登録されていて発見が遅れてしまった。