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

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

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

PC/行動裝置

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

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

PC

• 記錄清單畫面
• 記錄詳情畫面
• 新增記錄畫面
• 編輯記錄畫面
• 記錄列印畫面
• 圖表畫面

行動用戶端

• 記錄清單畫面
• 記錄詳情畫面
• 新增記錄畫面
• 編輯記錄畫面
• 圖表畫面

如何使用回調進行編寫

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 和請求標頭：

  • 設定 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 所需的資訊儲存在外掛程式

  1 2 3

  { "k1": "v1" }

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

  1 2 3

  { "k1": "v2" }

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

1
2
3
4

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

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

如果 HTTP 方法是 POST/PUT

將在此 API 中指定的請求正文中加上符合 在請求中包含存儲信息的條件 的設定資訊。
這與請求標頭相同。
但是，只有當該 API 中指定的請求類型是物件時，才會附加設定資訊，如果是字串，則不附加。

如果 HTTP 方法是 GET/DELETE

將在此 API 中指定的外部 API 的 URL 的查詢字串後面中加上符合 在請求中包含存儲信息的條件 的資訊信息。
如果 URL 中不包含查詢字串的開頭 ?，則會自動追加它。

例如，假設您為每個 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 所需的資訊儲存在外掛程式

  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 所需的資訊儲存在外掛程式

  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 Cache Missing）的錯誤。
• 如果設置了 IP 位址限制，要使用該 JavaScript API 為同一域的其他應用執行 kintone REST API，則必須允許 kintone 的 IP 位址。
  有關 IP 位址的詳細資訊，請參閱 cybozu.com使用的網域及IP位址 。
  但是，從安全角度來看，不建議這樣做，因為它允許通過執行外部 API 的 API 從所有 kintone 環境自由訪問。
  如需向同一域發出請求，請使用 發送 kintone REST API 請求的 API。
• 即使您使用此 API 執行外部 API，也不會自動發出應由執行的 API 目標發出的 cookie。
• 如果 HTTP 的方法指定為 POST 或 PUT，則會自動追"Content-Length"和"Transfer-Encoding"標頭。
  如果在請求裡指定，則會出現錯誤。

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