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

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

• 將執行外部 API 所需的資訊儲存在外掛程式
• 獲取執行外部 API 所需的資訊

電腦/行動裝置

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

如果指定successCallback ，則沒有返回值。
如果省略successCallback參數，返回kintone.Promise物件。
kintone.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);
});

如何使用 kintone.Promise 物件編寫

1

await kintone.plugin.app.proxy('mjjfipoklghomcgafnajfibfgllhpocm', 'https://api.example.com', 'GET', {}, {});

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

• 使用此 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" }。

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

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

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

• 將執行外部 API 所需的資訊儲存在外掛程式API

  1 2 3

  { "k1": "v1" }

• 從外掛程式執行外部 API（此 API）

  1 2 3

  { "k2": "v2" }

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

1
2
3
4

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

執行外部 API 時發送的請求正文

如果 HTTP 方法是 POST/PUT

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

如果 HTTP 方法是 GET/DELETE

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

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

• 將執行外部 API 所需的資訊儲存在外掛程式API

  1 2 3

  { "k1": "v1" }

• 從外掛程式執行外部 API（此 API）
  url：「https://api.example.com?k=v」

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

多個設定的 key 重複時

如果多個設定資訊同時滿足以下兩個條件，則與外部 API 的 URL 匹配且長度最長的優先。

• 將存儲信息添加到請求中的條件
• 請求標頭的 key 的值重複。

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

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

• 將執行外部 API 所需的資訊儲存在外掛程式API

  1 2 3 4

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

• 從外掛程式執行外部 API（此 API）

  1 2 3 4

  { "k2": "v2-1", "k3": "v3" }

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

1
2
3
4
5

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

當設定資訊與此 API 中指定的請求標頭或請求體的 key 重複時

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

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

• 將執行外部 API 所需的資訊儲存在外掛程式API

  1 2 3 4

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

• 從外掛程式執行外部 API（此 API）

  1 2 3 4

  { "k2": "v2-1", "k3": "v3" }

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

1
2
3
4
5

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

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

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