kintone Java Client は、kintone REST API を Java プログラムから使う際に必要な処理をまとめたライブラリです。
kintoneで利用可能なREST APIのほとんどを網羅しています。
kintone Java Clientを使うと、用意されたメソッドを呼び出すだけでkintone REST APIを実行できるので、コードの記述量を減らすことができます。
また、IntelliJなどのIDEを利用すると、コードの補完ができます。
この記事では、kintone Java Clientの導入方法や基本的な使い方について説明します。
kintone Java Clientが提供するメソッドの使い方の例は、
サンプル集を参照してください。
https://github.com/kintone/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:0.9.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>0.9.0</version>
</dependency>
|
Quickstart
固定リンクがコピーされました
kintoneのレコードを取得し、取得した内容をコンソールに出力する例です。
Gradle プロジェクトの場合
固定リンクがコピーされました
Step1：kintone アプリの準備
-
文字列（1行）フィールドを追加し、kintoneアプリを作成します。
-
作成したアプリでAPIトークンを生成します。
手順の詳細は、
API トークンを生成する
を参照してください。
-
作成したアプリのURLで、アプリIDを確認します。
URLのhttps://sample.cybozu.com/k/123の末尾の数字部分が、アプリIDです。
上記の場合、アプリIDは、「123」です。
-
テストデータとして、1件のレコードを追加します。
-
作成したレコードの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プロパティファイルなどに定義して読み込むようにしてください。
サンプルのため、例外処理を省略しています。実際のプログラムでは、適切にエラーハンドリングしてください。
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
|
plugins {
id 'java'
id 'com.github.johnrengelman.shadow' version '5.2.0'
}
apply plugin: 'java'
apply plugin: 'application'
mainClassName = 'com.cybozu.devnet.App'
repositories {
mavenCentral()
}
jar {
manifest {
attributes 'Main-Class': 'com.cybozu.devnet.App'
}
}
dependencies {
implementation 'com.kintone:kintone-java-client:0.9.0'
}
|
次の構成で、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
|
「build」の「libs」ディレクトリーの下にjava-all.jarが生成されます。
Step4：動作確認
次のコマンドを実行します。
1
|
java -jar build/libs/java-all.jar
|
次の結果が出力されれば、成功です。
1
2
|
Hello, kintone Java Client
1
|
Maven プロジェクトの場合
固定リンクがコピーされました
Step1：kintone アプリの準備
-
文字列（1行）フィールドを追加し、kintoneアプリを作成します。
-
作成したアプリでAPIトークンを生成します。
手順の詳細は、
API トークンを生成する
を参照してください。
-
作成したアプリのURLで、アプリIDを確認します。
URLのhttps://sample.cybozu.com/k/123の末尾の数字部分が、アプリIDです。
上記の場合、アプリIDは、「123」です。
-
テストデータとして、1件のレコードを追加します。
-
作成したレコードの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
|
<?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 http://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>1.0</version>
<name>sample-kintone-java-client</name>
<url>http://www.example.com</url>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>1.7</maven.compiler.source>
<maven.compiler.target>1.7</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>com.kintone</groupId>
<artifactId>kintone-java-client</artifactId>
<version>0.9.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>3.1.0</version>
</plugin>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.0</version>
</plugin>
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<version>3.0.2</version>
</plugin>
<plugin>
<artifactId>maven-install-plugin</artifactId>
<version>2.5.2</version>
</plugin>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.2.0</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」ディレクトリーで次のコマンドを実行します。
「target」ディレクトリーの下にsample-kintone-java-client-1.0-jar-with-dependencies.jarが生成されます。
Step4：動作確認
次のコマンドを実行します。
1
|
java -jar target/sample-kintone-java-client-1.0-jar-with-dependencies.jar
|
次の結果が出力されれば、成功です。
1
2
|
Hello, kintone Java Client
1
|
本 Client による kintone の操作
固定リンクがコピーされました
本Clientによるkintoneの操作は、次の手順で行います。
-
kintone クライアントを生成する
-
操作対象のクライアントを取得する
-
メソッドを呼び出し、kintone を操作する
Step1：kintone クライアントを生成する
KintoneClientBuilderを利用して、kintoneClientを生成します。
このとき、認証情報を設定します。
詳細は、
認証についてを参照してください。
クローズ処理
kintoneClientは内部でHTTPコネクションを保有しています。
処理が終わってkintoneClientの役目が終わったら、close()メソッドを呼び出し、クローズ処理を行ってください。
その他
KintoneClientBuilderでは、コネクションタイムアウトやプロキシ設定など、さまざまな項目を設定できます。setAppendixUserAgent()メソッドによってUser-Agentに追記する文字列を入れることもできます。
プログラム名や、処理内容を識別できる値を設定しておくと、今後、性能問題などが発生した場合にサイボウズ側でも調査しやすくなり、よりスピーディに問題解決できる場合があります。
ぜひご活用ください
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();
}
|
上記コードでは、処理が終わったときに自動でkintoneClient#close()メソッドが呼び出されるようtry-with-resourcesを用いています。
特別な事情のない限り、処理が終わった際にはtry-with-resourcesを利用してください。
close()メソッドが正しく呼び出されます。
Step3：メソッドを呼び出し、kintone を操作する
操作対象のクライアントを生成したら、操作メソッドを呼び出します。
kintoneを操作するには、
kintone REST APIの各APIに対応するメソッドへ、リクエストクラスを渡します。
一部のメソッドでは、それらをラップしたより簡便に利用できるメソッドも利用できます。
方法1：各 API に対応するメソッドにリクエストクラスを渡して、kintone を操作する
「API名 + Request」というリクエストクラスを操作対象のクライアントに渡すと、「API名 + ResponseBody」というレスポンスクラスのインスタンスを取得できます。
下記は、
1 件のレコードを取得する 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 = 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());
|
本Clientでは、
パスワード認証と
API トークン認証に対応しています。
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
// アクセス対象の kintone URL を設定
.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
// アクセス対象の kintone URL を設定
.create(baseUrl)
// 認証用 API トークンを設定
.authByApiToken(apiToken)
.build();
|
セキュリティ設定を行った環境
クライアント証明書やBasic認証情報も設定できます。
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();
|
セキュアアクセスを設定している環境
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の利用方法は、
サンプル集も参照してください。
ライブラリのアップデート情報は、
ライブラリの Releases
を参照してください。
- 2020年6月1日：「導入方法」で、ローカルのjarファイルを利用する方法から、セントラルリポジトリを利用する方法に修正
