kintone Java Client

連結已複製

概述

連結已複製

kintone Java Client是一個「匯總了在Java程式中使用kintone REST API所需的處理」的函數庫。
它涵蓋了kintone中提供的大部分REST API。
kintone REST API

使用kintone Java Client，只需調用提供的方法即可執行kintone REST API，從而減少需要編寫的代碼量。
還可以使用IDE（如IntelliJ）來完成代碼。

本文將對kintone Java Client的安裝方法和基本使用方法進行說明。
kintone Java Client提供的方法使用方法，請參閱以下頁面。
kintoneJava用戶端的示例代碼

GitHub

連結已複製

kintone-java-client

授權

連結已複製

MIT授權

限制事項

連結已複製

不支援Android。

文件

連結已複製

https://kintone.github.io/kintone-java-client/javadoc/

如何導入函數庫

連結已複製

對於Gradle專案

連結已複製

在build.gradle新增以下內容。
在第2行：指定要使用的kintone Java Client的版本。

1
2
3


dependencies {
  implementation 'com.kintone:kintone-java-client:2.4.0'
}

對於Maven專案　

連結已複製

在pom.xml新增以下內容。
在第4行中，version指定要使用的kintone Java Client版本。

1
2
3
4
5


<dependency>
    <groupId>com.kintone</groupId>
    <artifactId>kintone-java-client</artifactId>
    <version>2.4.0</version>
</dependency>

Quickstart

連結已複製

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

對於Gradle專案

連結已複製

Step1：準備kintone應用程式

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

Step2：創建範例代碼

建立包含以下內容的檔案，檔案名為App.java：根據您的環境重寫以下內容。

第10行：網域名稱
第11行：您建立的應用程式的API權杖
第12行：您建立的應用程式ID
第13行：添加的測試資料的記錄ID

在實際的程式中，請避免將網域名稱或認證資訊等硬編碼，建議定義於Java屬性檔（Java Properties）等設定檔中，並在程式中讀取使用
以下僅僅是示例，省略了異常處理。
在實際程式中，適當地處理錯誤。

 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


package com.cybozu.devnet;

import com.kintone.client.KintoneClient;
import com.kintone.client.KintoneClientBuilder;
import com.kintone.client.RecordClient;
import com.kintone.client.model.record.Record;

public class App {
  public static void main(String[] args) throws Exception {
    String baseUrl = "https://sample.cybozu.com"; // 網域名稱
    String apiToken = "API_TOKEN"; // API權杖
    long appId = 1L; // 應用程式ID
    long recordId = 1L; // 記錄ID

    System.out.println("Hello, kintone Java Client");

    // 執行API權杖驗證
    try (KintoneClient client = KintoneClientBuilder.create(baseUrl).authByApiToken(apiToken).build()) {
      // 獲取用於處理記錄的用戶端
      RecordClient recordClient = client.record();
      // 從kintone選取記錄
      Record record = recordClient.getRecord(appId, recordId);
      // 列印記錄ID
      System.out.println(record.getId());
    }
  }
}

建立包含以下內容的檔案，檔案名為build.gradle：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


plugins {
    id 'java'
    id 'application'
    id 'com.gradleup.shadow' version '9.1.0'
}

application {
    mainClass = 'com.cybozu.devnet.App'
}

repositories {
    mavenCentral()
}

jar {
    manifest {
        attributes 'Main-Class': 'com.cybozu.devnet.App'
    }
}

dependencies {
    implementation 'com.kintone:kintone-java-client:2.4.0'
    implementation 'org.slf4j:slf4j-simple:1.7.36'  // 添加日誌
}

使用以下設定部署App.java和build.gradle：

1
2
3
4
5
6
7
8
9


sample
├── build.gradle
└── src
    └── main
        └── java
            └── com
                └── cybozu
                    └── devnet
                        └── App.java

Step3：編譯

在「sample」目錄下執行以下命令。

1
2


gradle clean
gradle build

sample-all.jar在「build」的「libs」目錄下生成。

Step4：確認動作

執行以下命令：

1

java -jar build/libs/sample-all.jar

如果列印了以下結果，則表示列印成功。

1
2


Hello, kintone Java Client
1

對於Maven專案　

連結已複製

Step1：準備kintone應用程式

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

Step2：創建範例代碼

同“如果是Gradle項目 - Step2：範例代碼"一樣，創建App.java。

建立包含以下內容的檔案，檔案名為pom.xml：

 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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.cybozu.devnet</groupId>
  <artifactId>sample-kintone-java-client</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>sample-kintone-java-client</name>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <maven.compiler.source>22</maven.compiler.source>
    <maven.compiler.target>22</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
     <groupId>com.kintone</groupId>
     <artifactId>kintone-java-client</artifactId>
     <version>2.4.0</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>1.7.36</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>1.7.36</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>3.4.0</version>
      </plugin>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
      </plugin>
      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.4.2</version>
      </plugin>
      <plugin>
        <artifactId>maven-install-plugin</artifactId>
        <version>3.1.3</version>
      </plugin>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.1</version>
        <configuration>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
          <archive>
            <manifest>
              <mainClass>com.cybozu.devnet.App</mainClass>
            </manifest>
          </archive>
        </configuration>
        <executions>
          <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

使用以下設定部署App.java和pom.xml：

1
2
3
4
5
6
7
8
9


sample
├── pom.xml
└── src
    └── main
        └── java
            └── com
                └── cybozu
                    └── devnet
                        └── App.java

Step3：編譯

在「sample」目錄下執行以下命令。

1

mvn clean package

在「target」目錄下產生sample-kintone-java-client-0.0.1-SNAPSHOT-jar-with-dependencies.jar。

Step4：確認動作

執行以下命令：

1

java -jar target/sample-kintone-java-client-0.0.1-SNAPSHOT-jar-with-dependencies.jar

如果列印了以下結果，則表示列印成功。

1
2


Hello, kintone Java Client
1

補充說明

連結已複製

使用此用戶端操作kintone。

連結已複製

使用kintone用戶端操作時，請按照以下步驟操作。

生成kintone用戶端
獲取您想要合作的客戶
調用方法操作kintone

Step1：創建kintone用戶端

使用KintoneClientBuilder創建kintoneClient。
此時，設置身份驗證資訊。
有關說明，請參閱以下頁面。
關於身份驗證

關閉處理

kintoneClient有內部HTTP連接。
當進程完成且kintoneClient完成工作后，調用close()方法執行關閉進程。

其他

KintoneClientBuilder允許您設定各種設置，例如連接超時和代理設置。
您還可以使用setAppendixUserAgent()方法插入要新增到User-Agent的字串。
只要設定了程式名稱和可以識別處理內容的值，則將來發生性能問題時，Cybozu可更容易進行調查，並且可能能夠更快地解決問題。
請好好利用它

Step2：獲取要操作的用戶端

創建kintoneClient后，獲取要使用的目標用戶端。
該操作通過以下方式執行：

此示例假設您有一個名為getkintoneClient()的方法來獲取kintoneClient。

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


try (KintoneClient client = getKintoneClient()) {
  // 獲取用戶端以與應用交互
  AppClient appClient = client.app();

  // 獲取用於處理記錄的用戶端
  RecordClient recordClient = client.record();

  // 獲取用於處理空間的用戶端
  SpaceClient spaceClient = client.space();

  // 獲取用於檔案操作的用戶端
  FileClient fileClient = client.file();

  // 獲取用戶端以進行架構獲取
  SchemaClient schemaClient = client.schema();
}

在上面的代碼中，使用了try-with-resources，以便在進程完成時自動調用kintoneClient#close()方法。
除非有特殊情況，否則請在完成後使用try-with-resources。
正確調用close()方法。

Step3：調用方法並操作kintone

生成要使用的用戶端后，調用操作方法。

如需操作kintone，請將請求類傳遞給各kintone REST API的對應方法。
有些方法也有更簡單的方法來包裝它們。

方法1：將請求類傳遞給各API對應的方法，操作kintone

如果將請求類「API名+Request」傳遞給要操作的用戶端，則可以獲取回應類「API名+ResponseBody」的實例。

以下是獲取單個記錄的API示例。

請求類：GetRecordRequest
回應類：GetRecordResponseBody

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


// 創建用於記錄獲取的請求類的實例
GetRecordRequest req = new GetRecordRequest();
req.setApp(3L); // 設定要提取的應用程式ID（應用程式ID為long型）
req.setId(15L); // 設定要獲取的記錄ID（記錄ID類型為long）

// 將其傳遞給記錄用戶端並調用API
GetRecordResponseBody resp = client.record().getRecord(req);

// 從回應中獲取Record物件
Record record = resp.getRecord();

// 顯示記錄ID
System.out.println(record.getId());

方法2：使用更簡單的方法操作kintone

getRecord方法具有更方便的方法。使用它，您可以按如下方式編寫上述過程：

1
2
3
4
5


// 使用更方便的方法來獲取記錄資訊
Record record = client.record().getRecord(3L, 15L);

// 顯示記錄ID
System.out.println(record.getId());

關於身份驗證

連結已複製

此用戶端支援以下身份驗證方法。

如果除了kintone的URL和認證資訊之外沒有其他設置，則只需使用defaultClient方法創建kintoneClient即可。

密碼身分認證

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


String baseUrl = "https://sample.cybozu.com";
String username = "username";
String password = "password";

KintoneClient client = KintoneClientBuilder
                        // 設置要訪問的kintoneURL
                        .create(baseUrl)
                        // 設置用於身份驗證的使用者名和密碼
                        .authByPassword(username, password)
                        .build();

API權杖驗證

1
2
3
4
5
6
7
8
9


String baseUrl = "https://sample.cybozu.com";
String apiToken = "token";

KintoneClient client = KintoneClientBuilder
                        // 設置要訪問的kintoneURL
                        .create(baseUrl)
                        // 設置用於身份驗證的API權杖
                        .authByApiToken(apiToken)
                        .build();

具有安全設置的環境

還可以設置用戶端憑證和基本身份驗證資訊。

具有Basic身分驗證的環境

1
2
3
4
5
6
7
8
9


String baseUrl = "https://sample.cybozu.com";
String apiToken = "token";

KintoneClient client = KintoneClientBuilder
                        .create(baseUrl)
                        .authByApiToken(apiToken)
                        // 設置Basic身分驗證的使用者名和密碼
                        .withBasicAuth("basic", "password")
                        .build();

設定了SecureAccess的環境

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 如使用用戶端憑證，請在子域后添加.s
String baseUrl = "https://sample.s.cybozu.com";
String apiToken = "token";

KintoneClient client = KintoneClientBuilder
                        .create(baseUrl)
                        .authByApiToken(apiToken)
                        // 設置用戶端憑證和密碼
                        .withClientCertificate(Paths.get("/path/to/ file"), "password")
                        .build();

結語

連結已複製

使用kintone Java Client，在開發Java批處理程式和移動應用時，可以輕鬆執行kintone REST API。

kintone Java Client的使用方法請參考示例。
kintoneJava用戶端的示例代碼

更新資訊

連結已複製

有關庫更新資訊，請參閱以下頁面。
函數庫的Releases

2020年6月1日：「如何導入函數庫」中，將使用本地jar檔案變更為使用中央存儲庫。

本文範例已在2025年9月版的kintone和kintone Java Clientv2.4.0中完成測試。

kintone API

SDK & Tools