kintone JavaScript Client

連結已複製

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

關於kintone JavaScript Client（@kintone/rest-api-client）

連結已複製

@kintone/rest-api-client是一個庫，匯總了在JavaScript中處理kintone REST API時所需的處理。
它支援 Web 瀏覽器和 Node.js 環境。
詳情請參閱以下頁面。
kintone/rest-api-client

使用此用戶端，只需調用準備好的方法即可執行kintone REST API，從而減少了需要編寫的代碼量。
除了kintone提供的kintone REST API外，還有一些有用的方法，例如可以批量處理記錄的方法。
kintone REST API

此用戶端是在 TypeScript 中實現的，可以使用高性能編輯器（如 Visual Studio Code）完成代碼。

代碼完成的示意圖

當您編寫一段代碼時，它會自動建議您可以使用的方法。
還會顯示有關傳遞給方法的參數的資訊。

本文介紹了如何安裝此用戶端以及如何基本使用它。
有關用戶端提供的每種方法的詳細資訊，請參閱文件。

GitHub

連結已複製

https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client

授權

連結已複製

MIT 授權

文件

連結已複製

如何開始

連結已複製

瀏覽器環境

連結已複製

在瀏覽器環境中使用本用戶端時，請指定Cybozu CDN的URL並載入該本用戶端。
如需應用於kintone應用，請在「使用JavaScript/CSS進行自定義」頁面中指定。

例如，對於版本 1.4.0，請指定以下 URL：
https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js

關於在Cybozu CDN上發佈的版本，請參考以下頁面。
Cybozu CDN

Cybozu CDN會定期更新，因此可能與最新版本的庫不匹配。
如果要使用最新版本，請指定GitHub上列出的 CDN 服務 unpkg ^*1 的 URL。
README

在生產環境中，建議載入特定版本的URL，以避免新版本導致的意外錯誤或規範變更。

導入CDN時，kintoneRestAPIClient會添加為全域物件。

^*1 unpkg不是Cybozu提供的CDN服務。 ^

Node.js環境

連結已複製

如果要將其與Node.js一起使用，請在專案的根目錄下運行以下命令。

1

npm install @kintone/rest-api-client

要瞭解您需要的 Node.js 版本，請確認存儲庫的packages/rest-api-client/package.json中的 engines 屬性。
package.json

例如，以下要求Node.js版本 14 或更高版本。

1
2
3


"engines": {
  "node": ">=14"
},

在原始程式碼中，使用 require 進行載入。

1

const {KintoneRestAPIClient} = require('@kintone/rest-api-client');

Quick Start

連結已複製

這是在瀏覽器環境和 Node.js 環境中使用此用戶端的方法。
有關方法的詳細資訊，請參閱文件。

瀏覽器環境
Node.js環境

瀏覽器環境

連結已複製

打開記錄清單介面時，獲取kintone記錄，並將獲取到的內容輸出到主控台的範例。

Step1：準備kintone應用

添加單行文字方塊，創建kintone應用。
在您建立的應用中生成 API 權杖。
有關詳細說明，請參閱以下頁面。
生成 API 令牌
添加一條記錄作為測試數據。
在您創建的記錄的 URL 中，找到記錄 ID。
網址https://sample.cybozu.com/k/123/show#record=1之record=是記錄ID。
在上述情況下，記錄 ID 為「1」。

Step2：創建範例代碼

將以下內容貼上到文字編輯器中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


/*
* kintone JavaScript Client sample program (for kintone environment)
* Copyright (c) 2020 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/

(() => {
  'use strict';
  kintone.events.on('app.record.index.show', async (event) => {
    try {
      // 創建用戶端
      const client = new KintoneRestAPIClient();

      // 設置請求參數
      const APP_ID = kintone.app.getId();
      const RECORD_ID = 1;
      const params = {
        app: APP_ID,
        id: RECORD_ID
      };

      // 獲取記錄
      const resp = await client.record.getRecord(params);
      console.log(resp.record);
    } catch (err) {
      console.log(err);
    }
  });
})();

將字元編碼設置為「UTF-8」，將檔擴展名設置為「. js」並保存檔。
在本文中，檔名為「kintone-rest-api-sample.js」。

Step3：申請kintone應用

將kintone自定義檔應用到STEP1中創建的應用中。
詳情請參閱以下頁面。
使用 JavaScript 和 CSS 自定義應用

依以下順序指定「PC用的JavaScript / CSS檔案」中的 URL 和檔案：
1. https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js
2. 範例代碼（kintone-rest-api-sample.js）
在「應用程式設置」頁面中，點擊【更新應用程式】。

Step4：動作確認

打開已應用自定義的應用程式的清單畫面。
打開瀏覽器的開發者工具。
確認已輸出回應（記錄獲取結果）。

Node.js環境

連結已複製

這是獲取kintone記錄並將獲取到的內容輸出到控制台的範例。

Step1：準備kintone應用

添加單行文字方塊，創建kintone應用。
在您建立的應用中生成 API 權杖。
有關詳細說明，請參閱以下頁面。
生成 API 令牌
添加一條記錄作為測試數據。
在您創建的記錄的 URL 中，找到記錄 ID。
網址https://sample.cybozu.com/k/123/show#record=1之record=是記錄ID。
在上述情況下，記錄 ID 為「1」。

Step2：安裝所需的套件

為專案創建目錄。在此示例中，目錄名稱為「sample」。
1

mkdir sample

進入專案目錄，安裝kintone JavaScript用戶端。

1
2
3


cd sample
npm init -y
npm install @kintone/rest-api-client

Step3：創建範例代碼

將以下內容貼上到文字編輯器中：根據您的環境重寫以下內容。

第 16 行：網域名稱
第 23 行：您建立的應用的應用 ID

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


/*
* kintone JavaScript Client sample program (for Node.js)
* Copyright (c) 2020 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/

'use strict';
const {KintoneRestAPIClient} = require('@kintone/rest-api-client');

(async () => {
  try {
    // 創建用戶端
    const client = new KintoneRestAPIClient({
      baseUrl: 'https://sample.cybozu.com',
      auth: {
        apiToken: process.env.KINTONE_API_TOKEN
      }
    });

    // 設置請求參數
    const APP_ID = 1;
    const RECORD_ID = 1;
    const params = {
      app: APP_ID,
      id: RECORD_ID
    };

    // 獲取記錄
    const resp = await client.record.getRecord(params);
    console.log(resp.record);
  } catch (err) {
    console.log(err);
  }
})();

將字元編碼設置為「UTF-8」，將檔擴展名設置為「. js」，並將檔保存在「sample」目錄下。
在本文中，檔名為「kintone-rest-api-sample.js」

Step4：動作確認

在環境變數中設置 API 權杖。
API_TOKEN 使用您在 STEP1 中生成的 API 權杖
- 在 Windows 命令提示符下
  1
  
  SET KINTONE_API_TOKEN=API_TOKEN
- 在macOS上
  1
  
  export KINTONE_API_TOKEN=API_TOKEN
在「範例」下，運行以下命令：
1

node kintone-rest-api-sample.js

驗證是否輸出獲取到的記錄的內容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
  "記錄號碼": { "type": "RECORD_NUMBER", "value": "1" },
  "更新人": {
    "type": "MODIFIER",
    "value": { "code": "yamda", "name": "山田太郎" }
  },
  "建立人": {
    "type": "CREATOR",
    "value": { "code": "yamada", "name": "山田太郎" }
  },
  "$revision": { "type": "REVISION", "value": "2" },
  "更新時間": { "type": "UPDATED_TIME", "value": "2020-05-13T04:24:00Z" },
  "建立時間": { "type": "CREATED_TIME", "value": "2020-02-28T04:13:00Z" },
  "$id": { "type": "ID", "value": "1" }
}

補充說明

連結已複製

驗證

連結已複製

此用戶端支援密碼驗證、API 權杖驗證、使用 OAuth 用戶端的驗證和會話驗證。

驗證資訊在kintoneRestAPIClient參數物件的auth屬性中設置。

在以下範例中，從環境變數中讀取身份驗證資訊，假設它將與Node.js一起使用（會話身份驗證除外）。
如果您在瀏覽器環境中使用它，請不要將憑據硬編碼到 JavaScript 檔中。
有關說明，請參閱以下頁面。
安全編碼準則

密碼身分認證

對於密碼身份驗證，請指定 auth 屬性的使用者名和密碼。

1
2
3
4
5
6
7


const client = new KintoneRestAPIClient({
  auth: {
    username: process.env.KINTONE_USERNAME,
    password: process.env.KINTONE_PASSWORD
  },
  // ... 大約 ...
});

API 權杖身分驗證

對於 API 權杖身分驗證，請為 auth 屬性指定 apiToken。

1
2
3
4
5
6


const client = new KintoneRestAPIClient({
  auth: {
    apiToken: process.env.KINTONE_API_TOKEN
  },
  // ... 大約 ...
});

使用 OAuth 用戶端進行驗證

如果要使用 OAuth 用戶端進行驗證，請在 oAuthToken 屬性中指定訪問令牌。
關於如何創建OAuth客戶端並獲取訪問Token，請參考以下頁面。
OAuth用戶端

1
2
3
4
5
6


const client = new KintoneRestAPIClient({
  auth: {
    oAuthToken: process.env.KINTONE_OAUTH_TOKEN
  },
  // ... 大約 ...
});

會話認證

對於會話認證，請省略 auth屬性。
僅當將自定義檔應用於kintone環境時，會話認證才可用。

1

const client = new KintoneRestAPIClient();

具有安全設置的環境

您還可以設置Basic身分驗證和用戶端憑證的檔案。

在設置了Basic身分驗證的環境中

如果您在kintone環境中使用Basic身分驗證，請在kintoneRestAPIClient參數物件中添加basicAuth屬性。

1
2
3
4
5
6
7
8


const client = new KintoneRestAPIClient({
  // ... 大約...,
  basicAuth: { // Basic身分驗證設定
    username: process.env.KINTONE_BASIC_USERNAME,
    password: process.env.KINTONE_BASIC_PASSWORD
  },
  // ... 大約 ...
});

在設置了SecureAccess的環境中

如果已在kintone環境中設置了SecureAccess，請在kintoneRestAPIClient參數物件中添加clientCertAuth屬性來指定用戶端憑證的檔案。

有兩種方法可以指定用戶端憑證的檔案pfx 屬性中的二進位數據或 pfxFilePath 屬性中的文件路徑。

如何使用二進位數據進行指定

1
2
3
4
5
6
7
8


const client = new KintoneRestAPIClient({
  // ... 大約...,
  clientCertAuth: {
    pfx: certData,
    password: process.env.KINTONE_CLIENT_CERTIFICATE_PASSWORD
  },
  // ... 大約 ...
});

如何按檔案路徑指定

1
2
3
4
5
6
7
8


const client = new KintoneRestAPIClient({
  // ... 大約...,
  clientCertAuth: {
    pfxFilePath: './cert.pfx',
    password: process.env.KINTONE_CLIENT_CERTIFICATE_PASSWORD
  },
  // ... 大約 ...
});

結論

連結已複製

@kintone/rest-api-client使JavaScript程序能夠更輕鬆地使用kintone REST API。
有關 @kintone/rest-api-client 提供的方法及其使用方法的更多資訊，請參閱文件。

修訂記錄

連結已複製

有關庫更新資訊，請參閱以下頁面。
庫變更紀錄

本文示例代碼已使用kintone2020年7月版本和@kintone/rest-api-client v1.4.0進行測試。

SDK & Tools