kintone REST 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請求的APIkintone.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
「Basic身分驗證使用者名:Basic身分驗證密碼」的Base64編碼值

僅在配置基本身份驗證時指定。
在配置了基本認證的環境中，如何發出請求，請參考以下頁面。
具有Basic身分驗證的環境

X-HTTP-Method-Override

以大寫形式指定要執行的 API 的 HTTP 方法（GET/POST/PUT/DELETE）。
如果使用此頭中指定的 HTTP 方法發送 POST 請求，則將執行指定 HTTP 方法對應的 API。

如果指定請求 URL 大於 8 KB，則可以避免「請求 URL 過大」錯誤。

例如，以下範例請求可以運行獲取多條記錄的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。
但是，當kintone REST API與執行外部API的API一起執行時，它不支援這種行為。
執行外部 API

Accept-Language

指定 cybozu.com 中可用的顯示語言的語言代碼。
如果顯示語言為「與網路瀏覽器設定相同」，則此標頭中指定的語言將反映在回應正文的語言中。

僅當要指定請求結果的顯示語言時才指定。

請求內文

連結已複製

以 JSON 格式指定。字元編碼為UTF-8。
但是，用於上傳檔案的 API 是以分段格式指定的。
上傳檔案的 API

JSON 字串中需要逸出的字元應使用\ 進行逸出。

查詢參數

連結已複製

GET 方法 API 允許您發送帶有請求參數的請求，作為 URL 中的查詢參數。
例如，如果 app 請求參數為「1」，則查詢參數將指定如下：

1

/k/v1/records.json?app=1

逸出

根據 URL 規範，查詢參數的鍵和值採用百分比編碼。
以下是對查詢參數「更新時間 > "2021-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～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 的使用者的顯示語言設置。設置顯示語言

錯誤範例

1
2
3
4
5


{
  "id": "1505999166-897850006",
  "code": "CB_IJ01",
  "message": "Invalid JSON string."
}

日期和時間格式

連結已複製

對於處理日期和時間的欄位，請按以下格式指定字串：

日期

連結已複製

格式

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 Course）： 100,000

不會被計入請求數量的API請求

此外，以下請求不計入一天內可以發出的 API 請求數：

用於處理記錄的 API

連結已複製

選取多條記錄API的offset中可以指定的最大記錄數為 10,000。
獲取多條記錄
您一次最多可以建立/更新/刪除 100 條記錄。
不要向單個表添加大量行。
根據應用的配置方式，它可能會很昂貴，並且會影響記錄的處理，例如查看記錄或使用 REST API 與記錄交互。
關於如何考慮kintone性能的記錄，請參見以下提示。
提高kintone的性能
即使您指定了不存在的域代碼並獲取/創建/更新記錄，也將忽略並處理不存在的域代碼。
以下欄位僅用於值獲取。它不能註冊或更新。
- 由Lookup欄位輸入其值的欄位
- 類別
- 計算
- 狀態
  如果要更新，請使用更新單個記錄的狀態API。
  更新多條記錄的狀態
- 執行者
  如果要更新，請使用更新記錄上的執行者API。
  更新記錄上的執行者
如果要變更 API 中用於註冊或更新記錄的Lookup欄位的值，請將「記錄編號」欄位或帶有「值為唯一」的欄位指定為Lookup欄位的「要複製的欄位」。
如果Lookup欄位的「要複製的欄位」選擇設置為自動計算的「單行文字方塊」欄位，則無法變更Lookup欄位的值。

上傳檔案的 API

連結已複製

上傳的檔存儲在臨時存儲區。
除非您使用 API 將其附加到記錄以註冊或更新記錄，否則它將在 3 天內被刪除。
保存到臨時存儲的檔包含在磁碟使用量中。

用於回覆記錄的 API

連結已複製

您一次只能獲取一條記錄的 10 條回覆。

其他限制

連結已複製

kintone的其他限制
限值一覽
服務的其他限制
- Cybozu Cloud 服務限制

kintone API

kintone API文件