kintone REST APIの共通仕様 (original) (raw)
- Top
- kintone
- kintone APIドキュメント
- kintone REST API
- kintone REST API共通
- kintone REST APIの共通仕様
kintone REST APIの共通仕様
固定リンクがコピーされました
目次
kintone REST APIは、kintoneのアプリやレコード、スペースを操作できるAPIです。
このページでは、kintone REST APIの共通仕様を説明します。
各APIの仕様の詳細は、それぞれのAPIのページを確認してください。
APIによって異なります。
RESOURCEは、APIによって異なります。
詳細は各APIのページを確認してください。
通常（ゲストスペース以外）
https://sample.cybozu.com/k/v1/`RESOURCE`
ゲストスペース
https://sample.cybozu.com/k/guest/`SPACE_ID`/v1/`RESOURCE`
送信するリクエストに応じて次のリクエストヘッダーを指定します。
kintone REST APIリクエストを送信するAPI（kintone.api()）を使って、kintone REST APIを実行する場合、リクエストヘッダーの指定は不要です。
kintone REST APIリクエストを送信するAPI
kintone REST APIを実行するドメインとポート番号（443）を、「ドメイン:ポート番号」の形式で指定します。
Hostは必須です。
Content-Type
指定する値はリクエストボディの形式によって異なります。
- JSON文字列の場合：application/json
- マルチパートの場合：multipart/form-data
リクエストボディを送信する場合のみ指定します。
「ログイン名:パスワード」をBase64エンコードした値を指定します。
パスワードを使って認証する場合のみ指定します。
パスワード認証の詳細は、次のページを参照してください。
パスワード認証
kintoneのAPIトークンを指定します。
APIトークンを使って認証する場合のみ指定します。
APIトークン認証の詳細は、次のページを参照してください。
APIトークン認証
「XMLHttpRequest」または空文字列以外の文字列を指定します。
セッションで認証する場合のみ指定します。
セッション認証の詳細は、次のページを参照してください。
セッション認証
次の値を半角スペースで結合した値を指定します。
- Basic
- 「Basic認証のユーザー名:Basic認証のパスワード」をBase64エンコードした値
Basic認証を設定している場合のみ指定します。
Basic認証を設定している環境でのリクエスト方法は、次のページを参照してください。
Basic認証を設定している環境
実行するAPIのHTTPメソッド（GET／POST／PUT／DELETEのいずれか）を大文字で指定します。
このヘッダーにHTTPメソッドを指定してPOSTリクエストを送信すると、指定したHTTPメソッドに対応するAPIが実行されます。
リクエストURLが8KBを超える場合に指定すると、Request URL Too Largeエラーを回避できます。
たとえば、次のリクエスト例はレコードを複数取得するAPIを実行できます。
| 1 2 3 4 5 | curl -X POST https://sample.cybozu.com/k/v1/records.json \ -H 'X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=' \ -H 'Content-Type: application/json' \ -H 'X-HTTP-Method-Override: GET' \ -d '{ "app": 1, "query": "更新日時 > \"2024-02-03T09:00:00Z\"" }' |
|---|
このヘッダーは、すべてのkintone REST APIで利用できます。
ただし、外部のAPIを実行するAPIでkintone REST APIを実行したときの動作はサポートしていません。
外部のAPIを実行する
cybozu.comで利用できる表示言語の言語コードを指定します。
表示言語が「Webブラウザーの設定に従う」の場合、このヘッダーで指定した言語がレスポンスボディの言語に反映されます。
リクエスト結果の表示言語を指定したい場合のみ指定します。
JSON形式で指定します。文字コードはUTF-8です。
ただし、ファイルをアップロードするAPIはマルチパート形式で指定します。
ファイルをアップロードするAPI
JSON文字列でエスケープが必要な文字は、\でエスケープしてください。
GETメソッドのAPIでは、URLのクエリパラメーターとしてリクエストパラメーターを付与し、リクエストを送信できます。
たとえばリクエストパラメーターのappが「1」の場合、クエリパラメーターは次のように指定します。
| 1 | /k/v1/records.json?app=1 |
|---|
エスケープ
URLの仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「更新日時 > "2024-10-01T09:00:00+0900"」をパーセントエンコーディングした例です。
| 1 | /k/v1/records.json?app=1&query=%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3E%20%222024-10-01T09%3A00%3A00%2B0900%22%20 |
|---|
配列型のパラメーターを指定する場合
配列を要素に分解してパーセントエンコーディングします。
リクエストパラメーターのfieldsに、「レコード番号」と「ドロップダウン」を指定する例を示します。
fields=[レコード番号,ドロップボックス]という配列を要素に分解します。1 /k/v1/records.json?app=1&fields[0]=レコード番号&fields[1]=ドロップダウン - クエリパラメーターのキーや値をパーセントエンコーディングします。
1 /k/v1/records.json?app=1&fields%5B1%5D=%e4%bd%9c%e6%88%90%e6%97%a5%e6%99%82&fields%5B2%5D=%e3%83%89%e3%83%ad%e3%83%83%e3%83%97%e3%83%80%e3%82%a6%e3%83%b3
HTTPステータスコード
固定リンクがコピーされました
リクエストに成功した場合、200番台のステータスコードが返ります。
リクエストに失敗した場合、200番台以外のステータスコードとエラーレスポンスが返ります。
エラーレスポンス
同時接続数の上限値です。
必ず100が返ります。
現在の同時接続数です。
kintone REST APIリクエストを送信するAPIで実行した場合
kintone REST APIリクエストを送信するAPIを使って、kintone REST APIを実行した場合、コールバック関数に渡される情報は、レスポンスボディだけです。
レスポンスボディ以外の情報を利用する場合には、kintone REST APIリクエストを送信するAPI（kintone.api()）以外の方法で、kintone REST APIを実行してください。
kintone REST APIリクエストを送信するAPI
JSON形式で返されます。文字コードはUTF-8です。
ただし、ファイルをダウンロードするAPIでは、バイナリデータが返されます。
ファイルをダウンロードするAPI
次のプロパティをもつオブジェクトがJSON形式で返されます。
| パラメーター名 | 型 | 説明 |
|---|---|---|
| id | 文字列 | エラーIDサポートへの問い合わせの際に利用します。 |
| code | 文字列 | エラーの種類を表すコード |
| message | 文字列 | エラーメッセージ出力されるメッセージの言語は、APIを実行したユーザーの表示言語の設定によって異なります。 表示言語の設定 |
エラーの例
| 1 2 3 4 5 | { "id": "1505999166-897850006", "code": "CB_IJ01", "message": "不正なJSON文字列です。" } |
|---|
日時を扱うフィールドでは、次の形式の文字列を指定してください。
フォーマット
YYYY-MM-DD
補足
次の形式も許容されます。
YYYY（例：2024）YYYY-MM（例：2024-07）YYYY-M（例：2024-7）YYYY-M-D（例：2024-7-5）
月日を省略すると01で補完され、桁数が足りない場合は0埋めされます。
- 2024 → 2024-01-01
- 2024-07 → 2024-07-01
- 2024-7 → 2024-07-01
- 2024-7-5 → 2024-07-05
フォーマット
HH:MM
補足
UTCには変換されません。
日時（取得するとき）
固定リンクがコピーされました
フォーマット
YYYY-MM-DDTHH:MM:SSZ
補足
たとえば、日本時間（JST）の2024年3月22日14時00分は、「2024-03-22T05:00:00Z」と表します。
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「Z」はUTCを表します。
「T」以降を省略した場合、UTC 0時の指定と同等です。
例：2024-03-22を指定した場合、2024-03-22T00:00:00Zと同等になります。
一覧の設定を取得するAPIでは、日時はUTCで出力されます。
一覧の設定を取得するAPI
日時（登録または更新するとき）
固定リンクがコピーされました
フォーマット
YYYY-MM-DDTHH:MM:SS±HH:MMまたはYYYY-MM-DDTHH:MM:SSZ
補足
たとえば、日本時間（JST）の2024年3月22日14時17分は、次のように表します。
「2024-03-22T14:17:00+09:00」「2024-03-22T05:17:00Z」
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「±HH:MM」には、UTCとの時刻の差を指定します。
「T」以降を省略した場合、UTC 0時の指定と同等です。
例：2024-03-22を指定した場合、2024-03-22T00:00:00Zと同等になります。
秒情報を指定して登録または更新を行と、秒情報は無視されます。
たとえば、「2024-02-06T12:59:59Z」と指定すると、「2024-02-06T12:59:00Z」として登録または更新されます。
- リクエストデータ、およびレスポンスデータのJSONフォーマットには、今後フィールドやキーなどが追加される場合があります。
- REST APIを実行すると監査ログに記録されます。
kintoneの監査ログの確認方法／ログ一覧
同時にリクエストできるAPIは、1ドメインにつき100までです。
1日に実行できるAPIリクエスト数
固定リンクがコピーされました
1つのアプリにつき実行できるAPIのリクエスト数の上限は、次のとおりです。
- スタンダードコース：10,000件
- ワイドコース：100,000件
リクエスト数にカウントされないAPIは、次のページを確認してください。
1日に実行できるAPIリクエスト数
レコードを操作するAPI
固定リンクがコピーされました
- 複数のレコードを取得するAPIの
offsetで指定できるレコードの上限数は、10,000件までです。
複数のレコードを取得するAPI - 一度に登録／更新／削除できるレコードは、100件までです。
- 1つのテーブルに大量の行を追加しないでください。
アプリの構成によっては負荷がかかり、レコードの表示やREST APIを使った操作などのレコードの処理に影響します。
kintoneの性能を考慮したレコードの操作方法は、次のTipsを参照してください。
kintoneの性能改善 - 存在しないフィールドコードを指定して、レコードを取得／登録／更新した場合でも、存在しないフィールドコードは無視されて処理されます。
- 次のフィールドは、値の取得のみです。登録や更新はできません。
- ルックアップフィールドによって値が入力されるフィールド
- カテゴリー
- 計算
- ステータス
更新する場合は、レコードのステータスを更新するAPIを使います。
レコードのステータスを更新するAPI - 作業者
更新する場合は、レコードの作業者を更新するAPIを使います。
レコードの作業者を更新するAPI
- レコードの登録や更新をするAPIでルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」は、「レコード番号」フィールド、または「値の重複を禁止する」を設定したフィールドを指定してください。
- ルックアップフィールドの「コピー元のフィールド」に、自動計算を設定している「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。
ファイルをアップロードするAPI
固定リンクがコピーされました
アップロードしたファイルは、一時保管領域に保存されます。
レコードの登録や更新をするAPIでレコードに添付しない限り、3日間で削除されます。
一時保管領域に保存したファイルは、ディスク使用量に含まれます。
一度に取得できるレコードのコメントは10件までです。