kintone REST API常用規範

information

本頁面使用機器翻譯而成。
機器翻譯免責聲明 (External link)

目錄

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 REST API時,無需指定請求標頭。

標頭名稱 必須 內容
Host 必須 sample.cybozu.com:443
Content-Type 條件必填項 僅指定何時要發送請求正文
指定的值取決於請求內文的格式。
  • 對於 JSON 字串:application/json
  • 對於多部分:multipart/form-data
X-Cybozu-Authorization 條件必填項 “登入名稱:密碼”的Base64編碼值
如果要使用密碼進行身份驗證,則為必填項。
有關詳細資訊,請參閱 密碼身份驗證
X-Cybozu-API-Token 條件必填項 kintone API Token
如果要使用 API 權杖進行身份驗證,則為必填項。
有關更多資訊,請參閱 API權杖認證
Authorization 條件必填項 將“Basic ”和“Basic身分驗證使用者名:Basic身分驗證密碼”的“Base64 編碼值”組合在一起的值
如果已設置Basic身分驗證,則為必填項。
有關詳細資訊,請參閱 具有Basic身分驗證的環境
X-HTTP-Method-Override 可省略 HTTP 方法 (GET/POST/PUT/DELETE)
使用此標頭可避免在請求URL大於8 KB時出現請求URL過大錯誤。

當您使用“X-HTTP-Method-Override“中指定的 HTTP 方法發送 POST 請求時,將執行指定 HTTP 方法對應的 API。
以下是使用標頭運行 選取多條記錄API 時的範例:
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": "更新時間 > \"2012-02-03T09:00:00Z\"" }'
該頭在所有kintone REST API中均可用,但在 執行外部 API中執行時,不支援該行為。
“X-HTTP-Method-Override“中指定的 HTTP 方法必須為大寫。
如果在 發送kintone REST API請求的API中發送URL長度大於4KB的GET請求時,會自動添加“X-HTTP-Method-Override”標頭,並將其作為POST請求發送。
Accept-Language 可省略 語言代碼
如果顯示語言為”與網路瀏覽器的設定相同”,則此標頭中指定的語言將反映在回應正文的語言中。

請求內文

以 JSON 格式指定。字元編碼為UTF-8。
但是,用於 上傳檔案的 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%222021-10-01T09%3A00%3A00%2B0900%22%20
何時指定數值類型參數

將陣列分解為元素並對其進行百分比編碼。

下面是在 fields 請求參數中指定“記錄編號“和“下拉式選單“的範例。

  1. fields=[記錄編號,下拉式選單] 陣列轉換為元素。

    1
    
    /k/v1/records.json?app=1&fields[0]=記錄編號&fields[1]=下拉式選單
  2. 對查詢參數的鍵和值進行百分比編碼。

    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 系列以外的狀態代碼和具有以下屬性的物件:

參數名稱 類型 說明
id 字串 錯誤ID
使用它來聯繫支持人員。
code 字串 表示錯誤類型的代碼
message 字串 錯誤訊息
輸出消息的語言取決於執行 API 的使用者的 顯示語言設置 (External link)
錯誤範例
1
2
3
4
5
{
  "id": "1505999166-897850006",
  "code": "CB_IJ01",
  "message": "無效的 JSON 字串。"
}

回應標頭

參數名稱 類型 說明
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 格式返回。字元編碼為UTF-8。
但是, 下載檔案的 API 會返回二進位數據。

日期和時間格式

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

日期

格式
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:MMYYYY-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”。

注意事項

限制

併發連接數

每個域一次最多可以請求 100 個 API。

用於處理記錄的 API

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

上傳檔案的 API

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

用於回覆記錄的 API

您一次只能檢索一條記錄的 10 條回覆。

其他限制