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請求的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
  • 「基本認證使用者名:基本認證密碼」的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 請求參數中指定「記錄編號」和「下拉式選單」的範例。

  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~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 的使用者的 顯示語言設置。
設置顯示語言 (External link)
錯誤範例
1
2
3
4
5
{
  "id": "1505999166-897850006",
  "code": "CB_IJ01",
  "message": "無效的 JSON 字串。"
}

日期和時間格式

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

日期

格式
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: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 0點鐘位置的規格。
示例:如果指定了 2024-03-22,則相當於 2024-03-22T00:00:00Z。
如果在寄存器或更新行中指定秒資訊,則將忽略秒資訊。
例如「2019-02-06T12:59:59Z」註冊或更新為「2019-02-06T12:59:00Z」。

注意事項

限制事項

併發連接數

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

每個應用程式一天中可執行的API請求數

每個應用程式可以發出的最大 API 請求數如下:

  • 標準版:10,000
  • WIDE版: 100,000

對於不計入請求數的 API,請查看以下頁面:
每個應用程式一天中可執行的API請求數 (External link)

用於處理記錄的 API

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

上傳檔案的 API

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

用於回覆記錄的 API

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

其他限制