User API 是用於處理使用者、組、組織和職位等資訊的 API。
本頁介紹User API 的通用規範。
有關每個 API 的規格的更多資訊,請查看相應的 API 頁面。
請求
HTTP 方法
這取決於 API。
URL
RESOURCE
取決於 API。
有關詳細資訊,請查看每個 API 的頁面。
https://sample.cybozu.com/v1/RESOURCE
請求標頭
根據您發送的請求,指定以下請求標頭:
使用kintone REST API請求的API執行User API時,無需指定請求頭。
發送kintone REST API請求API
Host
指定執行Garoon REST API的域和埠號(443),格式為「域:埠號」。
Host為必填項。
Content-Type
指定 application/json。
僅當請求正文的格式為 JSON 字串時才指定。
X-Cybozu-Authorization
「登入名稱:密碼」的Base64編碼值
僅當要使用密碼進行身份驗證時才指定。
密碼認證
Authorization
指定以下值與單位元組空格組合。
- Basic
- 「基本認證使用者名:基本認證密碼」的Base64編碼值
僅在配置基本身份驗證時指定。
具有Basic身分驗證的環境
請求內文
以 JSON 格式指定。字元編碼為UTF-8。
JSON 字串中需要逸出的字元應使用\
進行逸出。
查詢參數
GET 方法 API 允許您發送帶有請求參數的請求,作為 URL 中的查詢參數。
例如,如果 size
請求參數為「100」,則查詢參數將指定如下:
|
|
逸出
根據 URL 規範,查詢參數的鍵和值採用百分比編碼。
查詢參數「code=cybozu#」的百分百編碼示例如下。
|
|
何時指定數位類型參數
將陣列分解為元素並對其進行百分比編碼。
以下示例顯示了在請求參數 codes
中指定 「cybozu#」 和 「sato-noboru」。
-
codes=[cybozu#,sato-noboru]
陣列轉換為元素。1
/v1/users.json?codes[0]=cybozu#&codes[1]=sato-noboru
-
對查詢參數的鍵和值進行百分比編碼。
1
/v1/users.json?codes%5B0%5D=cybozu%23&codes%5B1%5D=sato-noboru
回應
HTTP 狀態代碼
如果請求成功,則返回200~299範圍內的狀態代碼。
如果請求失敗,則返回200~299範圍外的狀態代碼和錯誤回應。
錯誤回應
錯誤回應
具有以下屬性的物件以 JSON 格式傳回:
參數名稱 | 類型 | 說明 |
---|---|---|
id | 字串 | 錯誤ID 使用它來聯繫支持人員。 |
code | 字串 | 表示錯誤類型的代碼 |
message | 字串 | 錯誤訊息 輸出消息的語言取決於執行 API 的使用者的 顯示語言設置。 設置顯示語言 |
錯誤範例
|
|
用於匯入/匯出 CSV 檔案的 API
導入 CSV 檔的步驟
用於導入 CSV 檔的 API 是異步 API。
若要使用 CSV 檔匯入,請按照下列步驟操作:
- 以CSV格式檔準備使用者資訊、組織資訊等。
- 使用上傳 CSV 檔 API 上傳 CSV 檔。
上傳CSV檔案的 API - 檔上傳 API 使用檔鍵進行回應。
- 將文件金鑰指定為請求參數,以執行與要攝取的數據相對應的 API。
例如,如果要導入使用者資訊,請運行匯入使用者資訊API。
匯入用戶資訊API - 執行的 API 的回應是作業編號。
- 在 request 參數中指定作業編號以運行API以確認導入結果。
確認匯入結果API - 處理結果作為對處理結果 API 的回應返回。
如果結果為「處理中」,請再次執行。
確認匯入結果API
「*」(星號)的處理
如果您指定「*」作為使用\上傳檔案 API\上傳的 CSV 的值,則不會更新該專案的值。
但是,以 CSV 格式導入使用者資訊的 API存在以下例外情況。
- 登錄名不能是*。
- 如果為自定義項指定「*」,則字串將「*」設置為項的值。
- 上傳檔案API
- 以CSV格式導入用戶資訊的API
匯出
匯出 CSV 檔的 API 的回應將列印到標準輸出。
如果要將回應的內容寫入檔,請使用shell的重定向函數 (>
)。
如果要使用 JavaScript API 來運行User API
在kintone中,可以使用發送kintone REST API請求的API運行User API。
但是,您不能運行以下 API:
- 發送kintone REST API請求API
- 上傳檔案API
- URL不是
json
的 API
注意事項
- 如果發送的 URL 長度大於 4 KB 的 GET 請求,則會自動附加「X-HTTP-Method-Override」標頭並作為 POST 請求發送。