kintone Java Clientは、kintone REST APIをJavaプログラムから使う際に必要な処理をまとめたライブラリです。
kintoneで利用できる次のREST APIのほとんどを網羅しています。
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では、次の認証方法に対応しています。
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ファイルを利用する方法から、セントラルリポジトリを利用する方法に修正