kintone JavaScript Client

連結已複製

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

什麼是kintone JavaScriptClient（@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 License

文件

連結已複製

如何導入

連結已複製

瀏覽器環境

連結已複製

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

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

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

由於Cybozu CDN會定期更新，可能與函式庫的最新版本不一致。

在正式環境中，為避免因新版本造成預期外的錯誤或規格變更，建議明確指定版本號的URL。

當從CDN載入後，會新增一個全域物件kintone REST APIClient。

Node.js環境

連結已複製

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

1

npminstall@kintone/rest-api-client

所需的Node.js版本，請參考官方儲存庫中packages/rest-api-client/package.json內的engines屬性：
package.json

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

1
2
3


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

在原始碼中可依以下方式匯入：

1
2
3
4


// CommonJS
const {KintoneRestAPIClient} = require('@kintone/rest-api-client');
// ES modules
import {KintoneRestAPIClient} from '@kintone/rest-api-client';

Quick Start

連結已複製

以下說明在瀏覽器環境與Node.js環境中使用本用戶端的基本方法。
有關方法的詳細資訊，請參閱文件。

瀏覽器環境
Node.js環境

瀏覽器環境

連結已複製

此範例說明在開啟kintone的紀錄清單畫面時，如何取得紀錄並在瀏覽器主控台輸出內容。

Step1：準備kintone應用程式

添加單行文字方塊，創建kintone應用程式。
新增1筆測試紀錄作為資料。
在您創建的記錄的URL中，找到記錄ID。
如過紀錄URL為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應用程式

將在Step 1中建立的應用程式套用此自訂程式檔案。

詳情請參閱以下頁面。
使用JavaScript和CSS自訂應用程式

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

Step4：執行確認

開啟套用自訂的kintone應用程式列表畫面。
打開瀏覽器的開發者工具。
確認主控台中輸出了取得的紀錄內容。

Node.js環境

連結已複製

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

Step1：準備kintone應用程式

添加單行文字方塊，創建kintone應用程式。
於該應用程式中產生API Token，並確認已勾選「查看記錄」。
有關詳細說明，請參閱以下頁面。
產生API權杖
新增1筆測試紀錄作為資料。
在您創建的記錄的URL中，找到記錄ID。
如過紀錄URL為https://sample.cybozu.com/k/123/show#record=1時，record=後的數字為記錄ID。
在上述例子中，紀錄ID為「1」。

Step2：安裝所需的套件

為專案創建目錄。
建立專案目錄，例如「sample」。
開啟終端並鍵入以下命令，然後按「Enter」：
1

mkdir sample

移動至該目錄並安裝kintone JavaScript Client。

1
2
3


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

Step3：建立範例程式

將以下範例代碼粘貼到文字編輯器中。
根據您的環境重寫以下內容。

第16行：網域名稱
第23行：您建立的應用的應用ID
您添加的記錄的記錄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 Token。
API_TOKEN替換為Step 1中產生的API Token。
- Windows（命令提示字元）
  1
  
  SET KINTONE_API_TOKEN=API_TOKEN
- macOS
  1
  
  export KINTONE_API_TOKEN=API_TOKEN
在「samples」下，運行以下命令：
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用戶端的驗證和Session驗證。

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

以下範例假設在Node.js環境中使用（不包含Session認證），並從環境變數中讀取認證資訊。
若從瀏覽器環境使用，請不要將認證資訊硬編碼（hardcode）在JavaScript檔案中。
有關說明，請參閱以下頁面。
kintone安全編碼指南

密碼認證

若使用密碼認證，請在auth屬性中指定username與password。

1
2
3
4
5
6
7


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

API權杖驗證

若使用API Token認證，請在auth屬性中指定apiToken。

1
2
3
4
5
6


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

使用OAuth用戶端進行驗證

若使用OAuth用戶端進行認證，請在oAuthToken屬性中指定存取權杖（Access Token）。
有關建立OAuth用戶端與取得Access Token的方法，請參考下列文件。
OAuth用戶端

1
2
3
4
5
6


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

Session認證

若使用Session認證，可省略auth屬性。
Session認證僅能在將自訂檔案套用至kintone環境時使用。

1

const client = new KintoneRestAPIClient();

已設定安全性設定的環境

可額外設定Basic認證資訊與用戶端憑證（Client Certificate）。

在設置了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所提供的方法與使用方式的詳細說明，請參考官方文件。

修訂記錄

連結已複製

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

本文示例代碼已在2020年7月版的kintone和@kintone/rest-api-clientv5.6.0中完成測試。

SDK & Tools