SDK & Tools

kintone JavaScript Client

information

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

目錄

kintone JavaScript用戶端（@kintone/rest-api-client）是什麼？

連結已複製

@kintone/rest-api-client (External link) 是一個庫，匯總了在JavaScript中處理kintone REST API時所需的處理。
通過使用 @kintone/rest-api-client（以下簡稱用戶端），只需調用準備好的方法即可執行kintone REST API，從而減少需要編寫的代碼量。
除了kintone 提供的kintone REST API 外，還有一些有用的方法，例如可以批量處理記錄的方法。

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

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

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

GitHub

連結已複製

https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client (External link)

授權

連結已複製

麻省理工學院許可證 (External link)

公文

連結已複製

如何開始

連結已複製

瀏覽器環境

連結已複製

在瀏覽器環境中使用本用戶端時，請指定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 (External link) 上列出的 CDN 服務 unpkg 的 URL。 *1 在生產環境中，建議載入特定版本的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 (External link) 中的 engines 屬性。
例如，以下要求Node.js版本 14 或更高版本。

1
2
3

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

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

1

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

Quick Start

連結已複製

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

瀏覽器環境

連結已複製

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

步驟一：準備kintone應用

  1. 添加字串（一行）字段，創建kintone應用。

  2. 在您建立的應用中生成 API 令牌。
    有關詳細說明， 請參閱生成 (External link) API 令牌。

  3. 添加一條記錄作為測試數據。

  4. 在您創建的記錄的 URL 中，找到記錄 ID。
    後面的 URL https://sample.cybozu.com/k/123/show#record=1 record= 的數位部分是記錄 ID。
    在上述情況下，記錄 ID 為" 1"

步驟 2：創建範例代碼

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

     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);
    }
  });
})();

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

步驟三：申請kintone應用

將kintone自定義檔應用到步驟1中創建的應用中。
有關詳細說明， 請參閱使用JavaScript和 CSS 自定義 (External link) 應用。

  1. 依以下順序指定 PC 的 JavaScript 檔中的 URL 和檔案：

    1. https://js.cybozu.com/kintone-rest-api-client/1.4.0/KintoneRestAPIClient.min.js
    2. 範例代碼 （kintone-rest-api-sample.js）

  2. 在「應用程式設置」頁面中，按兩下更新應用程式。

Step4：動作確認

  1. 打開已應用自定義的應用程式的清單螢幕。

  2. 打開瀏覽器的開發者工具。

  3. 確認已輸出回應（記錄檢索結果）。

Node.js環境

連結已複製

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

步驟一：準備kintone應用

  1. 添加字串（一行）字段，創建kintone應用。

  2. 在您建立的應用中生成 API 令牌。
    有關詳細說明， 請參閱生成 (External link) API 令牌。

  3. 添加一條記錄作為測試數據。

  4. 在您創建的記錄的 URL 中，找到記錄 ID。
    後面的 URL https://sample.cybozu.com/k/123/show#record=1 record= 的數位部分是記錄 ID。
    在上述情況下，記錄 ID 為" 1"

Step2：安裝所需的套件

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

    1

    mkdir sample

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

    1
2
3

    cd sample
npm init -y
npm install @kintone/rest-api-client
步驟 3：創建範例代碼

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

    • 第 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);
  }
})();

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

Step4：動作確認

  1. 在環境變數中設置 API 令牌。API_TOKEN 使用您在 STEP1 中生成的 API 令牌

    • 在 Windows 命令提示符下

      1

      SET KINTONE_API_TOKEN=API_TOKEN

    • 在macOS上

      1

      export KINTONE_API_TOKEN=API_TOKEN

  2. 在「範例」下，運行以下命令：

    1

    node kintone-rest-api-sample.js

  3. 驗證是否輸出檢索到的記錄的內容。

     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 檔中。
有關詳細資訊， 請參閱安全編碼準則 。

密碼

對於密碼身份驗證，指定 username 和 password 作為 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客戶端並獲取訪問令牌， 請參見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();
具有安全設置的環境

您還可以設置基本憑據和客戶端證書。

在設置了基本身份驗證的環境中

如果您在kintone環境中使用基本認證，請在kintoneRestAPIClient參數物件中添加basicAuth屬性。

1
2
3
4
5
6
7
8

const client = new KintoneRestAPIClient({
  // ... 大約 ...
  basicAuth: { // 設定基本認證
    username: process.env.KINTONE_BASIC_USERNAME,
    password: process.env.KINTONE_BASIC_PASSWORD
  }
  // ... 大約 ...
});
在設置了安全訪問的環境中

如果已在kintone環境中設置了安全訪問，請在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 提供的方法及其使用方法的更多資訊， 請參閱文檔 。

修訂記錄

連結已複製

有關磁帶庫更新資訊， 請參閱磁帶庫的更新日誌 (External link) 。

information

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