kintone REST API は、kintone のアプリやレコード、スペースを操作できる API です。
プロトコル
HTTPS
フォーマット
JSON
文字コード
UTF-8
エスケープ文字
\
を使用します。
日時のフォーマット
日時を扱うフィールドでは、次の形式の文字列を指定してください。
日付
- フォーマット
YYYY-MM-DD
- 補足
- 次の形式も許容されます。
YYYY
(例:2015)YYYY-MM
(例:2015-07)YYYY-M
(例:2015-7)YYYY-M-D
(例:2015-7-5)
- 月日を省略すると 01 で補完され、桁数が足りない場合は 0 埋めされます。
- 2015 → 2015-01-01
- 2015-07 → 2015-07-01
- 2015-7 → 2015-07-01
- 2015-7-5 → 2015-07-05
時刻
- フォーマット
HH:MM
- 補足
- UTC には変換されません。
日時(取得するとき)
- フォーマット
YYYY-MM-DDTHH:MM:SSZ
- 補足
- たとえば、日本時間(JST)の 2012 年 3 月 22 日 14 時 00 分は、「2012-03-22T05:00:00Z」と表します。
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「Z」は UTC を表します。 - 「T」以降を省略すると、UTC として扱われます。
- 一覧の設定を取得する API では、日時は UTC で出力されます。
日時(登録または更新するとき)
- フォーマット
YYYY-MM-DDTHH:MM:SS±HH:MM
またはYYYY-MM-DDTHH:MM:SSZ
- 補足
- たとえば、日本時間(JST)の 2012 年 3 月 22 日 14 時 17 分は、次のように表します。
「2012-03-22T14:17:00+09:00」「2012-03-22T05:17:00Z」 - 「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
- 「±HH:MM」には、UTC との時刻の差を指定します。
- 「T」以降を省略すると、UTC として扱われます。
- 秒情報を指定して登録または更新を行と、秒情報は無視されます。
たとえば、「2019-02-06T12:59:59Z」と指定すると、「2019-02-06T12:59:00Z」として登録または更新されます。
リクエスト
URL
ゲストスペース以外
https://sample.cybozu.com/k/v1/リソース
ゲストスペース内のアプリ
https://sample.cybozu.com/k/guest/スペースのID
/v1/リソース
リクエストヘッダー
送信するリクエストに応じて次のリクエストヘッダーを指定します。
kintone REST API リクエストを送信する API を使って、kintone REST API を実行する場合、リクエストヘッダーの指定は不要です。
ヘッダー名 | 必須 | 内容 |
---|---|---|
Host | 必須 | sample.cybozu.com:443 |
Content-Type | 省略可 | application/json リクエストボディに JSON 文字列を指定する場合は必須です。 |
X-Cybozu-Authorization | 条件必須 | 「ログイン名:パスワード」を Base64 エンコードした値 パスワードを使って認証する場合は、必須です。 詳細は、 パスワード認証 を参照してください。 |
X-Cybozu-API-Token | 条件必須 | kintone の API トークン API トークンを使って認証する場合は必須です。 詳細は、 APIトークン認証 を参照してください。 |
Authorization | 条件必須 | 「Basic 」と「"Basic認証のユーザー名:Basic認証のパスワード" を Base64 エンコードした値」を結合した値 Basic 認証 を設定している場合、必須です。 詳細は、 Basic 認証を設定している環境 を参照してください。 |
X-HTTP-Method-Override | 省略可 | HTTP メソッド(GET/POST/PUT/DELETE) このヘッダーは、リクエスト URL が 8 KB を超えると発生する Request URL Too Large エラーを回避する目的で使用します。 「X-HTTP-Method-Override」に HTTP メソッドを指定して POST リクエストを送信すると、指定した HTTP メソッドに対応する API が実行されます。 以下は、ヘッダーを付けて レコードを複数取得する API を実行するときの例です。 curl -X POST https://sample.cybozu.com/k/v1/records.json \このヘッダーは、すべての kintone REST API で利用できますが、 外部の API を実行する API で実行した場合には、動作を保証していません。 「X-HTTP-Method-Override」に指定する HTTP メソッドは、大文字を指定してください。 kintone REST API リクエストを送信する API で URL の長さが 4 KB を超える GET リクエストを送信した場合、「X-HTTP-Method-Override」ヘッダーが自動的に付与され、POST リクエストとして送信されます。 |
レスポンス
HTTP ステータスコード
リクエストに成功した場合、200 番台のステータスコードが返ります。
リクエストに失敗した場合、200 番台以外のステータスコードと、次のプロパティをもつオブジェクトが返ります。
パラメーター名 | 型 | 説明 |
---|---|---|
id | 文字列 | エラー ID サポートへの問い合わせの際に利用します。 |
code | 文字列 | エラーの種類を表すコード |
message | 文字列 | エラーメッセージ API を実行するユーザーの表示言語の設定によって異なります。 |
エラーの例
|
|
レスポンスヘッダー
パラメーター名 | 型 | 説明 |
---|---|---|
X-ConcurrencyLimit-Limit | 数値 | 同時接続数の上限値 必ず 100 が返ります。 |
X-ConcurrencyLimit-Running | 数値 | 現在の同時接続数 |
kintone REST API リクエストを送信する API を実行したときのレスポンス
kintone REST API リクエストを送信する API を使って、kintone REST API を実行した場合、コールバック関数に渡される情報は、リクエストボディのみです。
レスポンスボディ以外の情報を利用する場合には、
kintone REST API リクエストを送信する API 以外の方法で、kintone REST API を実行してください。
注意事項
- リクエストデータ、およびレスポンスデータの JSON フォーマットには、今後フィールドやキーなどが追加される場合があります。
- REST API を実行すると監査ログに記録されます。詳細は
kintoneの監査ログの確認方法/ログ一覧
を参照してください。
- 1 日に実行できる API は、1 つのアプリにつき 10,000 件までです。ただし、次の API はリクエスト数にカウントされません。
- ファイルのダウンロード
- ファイルのアップロード
- スペース情報の取得
- スペースの作成
- スペースの本文の更新
- スペースのスレッドの更新
- スペースのスレッドへの投稿
- スペースのメンバーの取得
- スペースのメンバーの更新
- ゲストスペースのゲストメンバーの更新
- ゲストユーザーの一括追加
- ゲストユーザーの一括削除
- スペースの削除
- API 一覧の取得
- API スキーマ情報の取得
制限事項
同時接続数
同時にリクエストできる API は、1 ドメインにつき 100 までです。
レコードを操作する API
-
複数のレコードを取得する API の
offset
で指定できるレコードの上限数は、10,000 件までです。 - 一度に登録/更新/削除できるレコードは、100 件までです。
- 1 つのテーブルに大量の行を追加しないでください。
アプリの構成によっては、負荷がかかり、レコードの表示や REST API を使った操作など、レコードの処理に影響します。
テーブルの行数がレコードの描画時間に与える影響の検証結果は、 kintone のテーブルの行数とレコード一覧・詳細画面の描画時間との関係 を参照してください。 - 存在しないフィールドコードを指定して、レコードを取得/登録/更新した場合でも、存在しないフィールドコードは無視されて処理されます。
- 次のフィールドは、値の取得のみです。登録や更新はできません。
- ルックアップフィールドによって値が入力されるフィールド
- カテゴリー
- 計算
- ステータス
更新する場合は、 レコードのステータスを更新する API を使います。 - 作業者
更新する場合は、 レコードの作業者を更新する API を使います。
- レコードの登録や更新をする API でルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」は、「レコード番号」フィールド、または「値の重複を禁止する」を設定したフィールドを指定してください。
- ルックアップフィールドの「コピー元のフィールド」に、自動計算を設定している「文字列 1 行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。
ファイルをアップロードする API
アップロードしたファイルは、一時保管領域に保存されます。
レコードの登録や更新をする API でレコードに添付しない限り、3 日間で削除されます。
一時保管領域に保存したファイルは、ディスク使用量に含まれます。
レコードにコメントする API
一度に取得できるレコードのコメントは 10 件までです。
その他の制限事項
- kintone に関するその他の制限事項は、
制限値一覽
を確認してください。
- その他、サービスに関する制限事項は、
サイボウズのクラウドサービス制限事項
を確認してください。