kintone API文件

從外掛程式執行外部API

information

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

目錄

從外掛程式執行外部API

連結已複製

從外掛程式執行外部服務的API。
此API允許您繞過跨域限制並向外部API發送請求。

如果要使用要保密的資訊（例如身份驗證資訊）執行外部API，請在執行API之前提前將必要的資訊存儲在外掛程式中。
有關如何在外掛程式中保存和獲取資訊的詳細資訊，請參閱以下頁面。

函數

連結已複製

電腦版/行動裝置版

kintone.plugin.app.proxy(pluginId, url, method, headers, data, successCallback, failureCallback)

參數

連結已複製

參數 類型 必須 說明
pluginId 字串 必須 執行API的外掛程式的外掛程式ID
URL 字串 必須 要執行的API的URL
method 字串 必須 用於執行API的HTTP方法
指定以下值之一：
  • GET
  • POST
  • PUT
  • DELETE
headers 物件 必須 請求標頭
實際的請求頭包含headers中指定的參數，以及使用以下API在外掛程式中保存的參數。
將執行外部API所需的資訊儲存在外掛程式API
如果不指定任何內容，請指定 {}。
data 物件或字串 必須 請求正文
實際的請求正文包含data中指定的參數，以及使用以下API儲存在外掛程式中的數據：
將執行外部API所需的資訊儲存在外掛程式API
僅當method為「POST」或「PUT」時才使用指定的值。
對於「GET」或「DELETE」，請在URL的查詢字串中指定參數。
successCallback 函數 可省略 請求完成後要執行的函數
在函數的引數中傳遞以下三條資訊：
  • 第一個引數：回應正文（字串）
  • 第二個引數：狀態代碼（數值）
  • 第三個引數：回應標頭（物件）
如果省略，則返回Promise物件，將解析為包含上述回應正文、狀態代碼和響應標頭的陣列。
failureCallback 函數 可省略 請求失敗時要執行的函數
已執行API的回應正文（字串）作為參數傳遞給函數。
如果省略，返回`物件，並在執行的API的回應正文（字串）中廢棄。

返回值

連結已複製

如果指定successCallback，則沒有返回值。
如果省略successCallback參數，返回Promise物件。

可使用的畫面

連結已複製

電腦版
  • 記錄清單畫面
  • 記錄詳情畫面
  • 新增記錄畫面
  • 編輯記錄畫面
  • 記錄列印畫面
  • 圖表畫面
行動裝置版
  • 記錄清單畫面
  • 記錄詳情畫面
  • 新增記錄畫面
  • 編輯記錄畫面
  • 圖表畫面

示例代碼

連結已複製

如何使用回調進行編寫
1
2
3
4
5
6
7

kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'GET', {}, {}, (body, status, headers) => {
  // success
  console.log(status, JSON.parse(body), headers);
}, (error) => {
  // error
  console.log(error);
});
如何使用async/await編寫
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

(async () => {
  try {
    const resp = await kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'GET', {}, {});
    // success
    console.log(resp);
  } catch (error) {
    // error
    console.log(error);
  }
})();

補充

連結已複製

在請求中包含存儲信息的條件

  • 使用此API發出請求時，當滿足以下所有條件時，外掛程式中儲存的資訊將新增到請求中：

    • 同一應用程式
    • 同一外掛程式
    • 同一HTTP方法
    • 要執行的API的URL的前面部分相同 *1
      URL區分大小寫。

  • 如果在外掛程式中存儲了多個設定，則優先使用與執行API時指定的URL匹配度較高的URL。
    例如，“將執行外部API所需的資訊儲存在外掛程式”這個API中，指定如下URL和請求標頭：
    將執行外部API所需的資訊儲存在外掛程式API

    • 設定1
      • URL：https://api.example.com/
      • 標頭：{ "Content-Type": "application/x-www-form-urlencoded" }
    • 設定2
      • URL：https://api.example.com/foo/
      • 標頭：{ "Content-Type": "application/json" }

    使用以下值執行此API：

    • URL：https://api.example.com/foo/operate.json
    • 標頭：{}

    在這種情況下，執行API時送出的請求的標頭是{ "Content-Type": "application/json" }。

*1

例如，如果在每個函數中指定以下URL，因URL的開頭部分匹配，存儲在外掛程式中的資訊將添加到請求中。

^

執行外部API時發送的請求標頭

執行外部API時指定的請求標頭包含，在該API中指定的標頭，以及滿足以下條件的設定資訊的請求標頭。
將存儲信息添加到請求中的條件

例如，假設您為每個API指定以下請求標頭：

在這種情況下，實際上會發送以下請求標頭：

1
2
3
4

{
  "k1": "v1",
  "k2": "v2"
}
執行外部API時發送的請求正文
如果HTTP方法是POST/PUT

此API指定的請求體將包含滿足以下條件的設置信息的資訊。
將存儲信息添加到請求中的條件
這與請求標頭相同。
但是，只有當該API中指定的請求類型是物件時，才會附加設定資訊，如果是字串，則不附加。

如果HTTP方法是GET/DELETE

將滿足以下條件的設置資訊將追加到此API中指定的外部API的URL的查詢字串末尾，作為查詢字串。
將存儲信息添加到請求中的條件
如果URL中不包含表示查詢字串的開頭的?，則會自動追加。

例如，假設您為每個API指定如下請求正文和請求參數：

在這種情況下，請求將發送到以下URL：
https://api.example.com?k=v&k1=v1&k2=v2

多個設定的key重複時

如果多個配置同時滿足以下條件，則與API執行時指定的URL匹配字元較多的外部API的URL優先使用。

如果HTTP方法是POST/PUT，則請求標頭中指定的值是物件，如果是GET/DELETE，則將其套用於查詢字串。

例如，假設您為每個API指定以下請求標頭：

如果後者優先，實際上會發送以下請求標頭：

1
2
3
4
5

{
  "k1": "v1",
  "k2": "v2-1",
  "k3": "v3"
}
當設定資訊與此API中指定的請求標頭或請求體的key重複時

如果從設定的請求資訊中獲取的請求標頭的key也包含在該API的請求頭中，則前者值優先。
HTTP方法為POST/PUT時的請求體（僅當類型為物件時）。
對於GET/DELETE，不確認key是否重複。

例如，假設您為每個API指定以下請求標頭：

在這種情況下，實際上會發送以下請求標頭：

1
2
3
4
5

{
  "k1": "v1",
  "k2": "v2",
  "k3": "v3"
}

注意事項

連結已複製

  • 如果指定的伺服器url不存在，則返回狀態代碼為「503」（DNS Cache Missing）的錯誤。
  • 如果設置了IP位址限制，要使用該JavaScript API為同一域的其他應用執行kintone REST API，則必須允許kintone的IP位址。
    有關詳細的IP地址，請參閱以下頁面。
    cybozu.com使用的域和IP位址 (External link)
    但是，從安全角度來看，不建議這樣做，因為它允許通過執行外部API的API從所有kintone環境自由訪問。 對於對同一域的請求，請使用以下API。
    發送kintone REST API請求API
  • 即使您使用此API執行外部API，也不會自動發出應由執行的API目標發出的cookie。
  • 如果為HTTP方法指定POST或PUT，則會自動追加「Content-Length」和「Transfer-Encoding」標頭。
    如果在請求裡指定，則會出現錯誤。

限制事項

連結已複製

  • 以下是對執行的外部API回應的限制：
    • 響應標頭的最大為100行，每行的最大長度為8,180位元組。
    • 回應正文的上限為10MB。如果超過限制，則會發生錯誤。
    • 回應正文僅支援字串。無法獲取二進位數據，例如圖像。
  • 不能使用自證書與伺服器通信。