kintone REST API是用於操作kintone應用、記錄和空間的API。
本頁將對kintone REST API的通用規範進行說明。
有關每個 API 的規格的更多資訊,請查看相應的 API 頁面。
請求
HTTP 方法
這取決於 API。
URL
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
Host
指定執行Garoon REST API的域和埠號(443),格式為「域:埠號」。
Host為必填項。
Content-Type
指定的值取決於請求內文的格式。
- 對於 JSON 字串:application/json
- 對於多部分:multipart/form-data
僅指定何時要發送請求正文。
X-Cybozu-Authorization
「登入名稱:密碼」的Base64編碼值
僅當要使用密碼進行身份驗證時才指定。
有關詳細的密碼認證,請參閱以下頁面。
密碼認證
X-Cybozu-API-Token
指定kintone API token。
僅指定要使用 API 令牌進行身份驗證的情況。
有關更多資訊,請參閱以下頁面。
API 權杖身分驗證
X-Requested-With
指定「XMLHttpRequest」或非空字串。
僅當要通過會話進行身份驗證時才指定。
有關詳細的會話驗證,請參閱以下頁面。
會話認證
Authorization
指定以下值與單位元組空格組合。
- Basic
- 「基本認證使用者名:基本認證密碼」的Base64編碼值
僅在配置基本身份驗證時指定。
在配置了基本認證的環境中,如何發出請求,請參考以下頁面。
具有Basic身分驗證的環境
X-HTTP-Method-Override
以大寫形式指定要執行的 API 的 HTTP 方法(GET/POST/PUT/DELETE)。
如果使用此頭中指定的 HTTP 方法發送 POST 請求,則將執行指定 HTTP 方法對應的 API。
如果指定請求 URL 大於 8 KB,則可以避免「請求 URL 過大」錯誤。
例如,以下範例請求可以運行獲取多條記錄的API。
|
|
該標頭適用於所有kintone REST API。
但是,當kintone REST API與執行外部API的API一起執行時,它不支援這種行為。
執行外部 API
Accept-Language
指定 cybozu.com 中可用的顯示語言的語言代碼。
如果顯示語言為「與網路瀏覽器設定相同」,則此標頭中指定的語言將反映在回應正文的語言中。
僅當要指定請求結果的顯示語言時才指定。
請求內文
以 JSON 格式指定。字元編碼為UTF-8。
但是,用於上傳檔案的 API 是以分段格式指定的。
上傳檔案的 API
JSON 字串中需要逸出的字元應使用\
進行逸出。
查詢參數
GET 方法 API 允許您發送帶有請求參數的請求,作為 URL 中的查詢參數。
例如,如果 app
請求參數為「1」,則查詢參數將指定如下:
|
|
逸出
根據 URL 規範,查詢參數的鍵和值採用百分比編碼。
以下是對查詢參數「更新時間 > "2021-10-01T09:00:00+0900"」進行百分比編碼的示例。
|
|
何時指定數值類型參數
將陣列分解為元素並對其進行百分比編碼。
下面是在 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~299範圍內的狀態代碼。
如果請求失敗,則返回200~299範圍外的狀態代碼和錯誤回應。
錯誤回應
回應標頭
X-ConcurrencyLimit-Limit
最大併發連接數
返回100。
X-ConcurrencyLimit-Running
當前併發連接數
使用發送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 的使用者的 顯示語言設置。 設置顯示語言 |
錯誤範例
|
|
日期和時間格式
對於處理日期和時間的欄位,請按以下格式指定字串:
日期
- 格式
YYYY-MM-DD
- 補充
- 以下格式也是可以接受的:
YYYY
(例如:2015-7-5)YYYY-MM
(例如:2015-7-5)YYYY-M
(例如:2015-7-5)YYYY-M-D
(例如:2015-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) 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 0點鐘位置的規格。
示例:如果指定了 2024-03-22,則相當於 2024-03-22T00:00:00Z。 - 在用於獲取清單中設置的 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 0點鐘位置的規格。
示例:如果指定了 2024-03-22,則相當於 2024-03-22T00:00:00Z。 - 如果在寄存器或更新行中指定秒資訊,則將忽略秒資訊。
例如「2019-02-06T12:59:59Z」註冊或更新為「2019-02-06T12:59:00Z」。
注意事項
- 請求和回應數據的 JSON 格式可能包括其他欄位、鍵等。
- 運行 REST API 時,它會記錄在審核日誌中。
kintone/日誌清單的審計日誌查詢方法
限制事項
併發連接數
每個域一次最多可以請求 100 個 API。
每個應用程式一天中可執行的API請求數
每個應用程式可以發出的最大 API 請求數如下:
- 標準版:10,000
- WIDE版: 100,000
對於不計入請求數的 API,請查看以下頁面:
每個應用程式一天中可執行的API請求數
用於處理記錄的 API
- 選取多條記錄API的
offset
中可以指定的最大記錄數為 10,000。
獲取多條記錄 - 您一次最多可以建立/更新/刪除 100 條記錄。
- 不要向單個表添加大量行。
根據應用的配置方式,它可能會很昂貴,並且會影響記錄的處理,例如查看記錄或使用 REST API 與記錄交互。
關於如何考慮kintone性能的記錄,請參見以下提示。
提高kintone的性能 - 即使您指定了不存在的域代碼並獲取/創建/更新記錄,也將忽略並處理不存在的域代碼。
- 以下欄位僅用於值獲取。它不能註冊或更新。
- 如果要變更 API 中用於註冊或更新記錄的Lookup欄位的值,請將「記錄編號」欄位或帶有「值為唯一」的欄位指定為Lookup欄位的「要複製的欄位」。
- 如果Lookup欄位的「要複製的欄位」選擇設置為自動計算的「單行文字方塊」欄位,則無法變更Lookup欄位的值。
上傳檔案的 API
上傳的檔存儲在臨時存儲區。
除非您使用 API 將其附加到記錄以註冊或更新記錄,否則它將在 3 天內被刪除。
保存到臨時存儲的檔包含在磁碟使用量中。
用於回覆記錄的 API
您一次只能獲取一條記錄的 10 條回覆。
其他限制
- kintone的其他限制
限值一覽 - 服務的其他限制