User API通用規範

information

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

目錄

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」,則查詢參數將指定如下:

1
/v1/users.json?size=100
逸出

根據 URL 規範,查詢參數的鍵和值採用百分比編碼。
查詢參數「code=cybozu#」的百分百編碼示例如下。

1
/v1/user/organizations.json?code=cybozu%23
何時指定數位類型參數

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

以下示例顯示了在請求參數 codes 中指定 「cybozu#」 和 「sato-noboru」。

  1. codes=[cybozu#,sato-noboru] 陣列轉換為元素。

    1
    
    /v1/users.json?codes[0]=cybozu#&codes[1]=sato-noboru
  2. 對查詢參數的鍵和值進行百分比編碼。

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

用於匯入/匯出 CSV 檔案的 API

導入 CSV 檔的步驟

用於導入 CSV 檔的 API 是異步 API。
若要使用 CSV 檔匯入,請按照下列步驟操作:

  1. 以CSV格式檔準備使用者資訊、組織資訊等。
  2. 使用上傳 CSV 檔 API 上傳 CSV 檔。
    上傳CSV檔案的 API
  3. 檔上傳 API 使用檔鍵進行回應。
  4. 將文件金鑰指定為請求參數,以執行與要攝取的數據相對應的 API。
    例如,如果要導入使用者資訊,請運行匯入使用者資訊API。
    匯入用戶資訊API
  5. 執行的 API 的回應是作業編號。
  6. 在 request 參數中指定作業編號以運行API以確認導入結果。
    確認匯入結果API
  7. 處理結果作為對處理結果 API 的回應返回。

如果結果為「處理中」,請再次執行。
確認匯入結果API

「*」(星號)的處理

如果您指定「*」作為使用\上傳檔案 API\上傳的 CSV 的值,則不會更新該專案的值。
但是,以 CSV 格式導入使用者資訊的 API存在以下例外情況。

匯出

匯出 CSV 檔的 API 的回應將列印到標準輸出。
如果要將回應的內容寫入檔,請使用shell的重定向函數 (>)。

如果要使用 JavaScript API 來運行User API

在kintone中,可以使用發送kintone REST API請求的API運行User API。
但是,您不能運行以下 API:

注意事項

  • 如果發送的 URL 長度大於 4 KB 的 GET 請求,則會自動附加「X-HTTP-Method-Override」標頭並作為 POST 請求發送。