kintone Java Client

目次

はじめに

kintone Java Client は、 kintone REST API を Java プログラムから使う際に必要な処理をまとめたライブラリです。
kintone で利用可能な REST API のほとんどを網羅しています。

kintone Java Client を使うと、用意されたメソッドを呼び出すだけで kintone REST API を実行できるので、コードの記述量を減らすことができます。
また、IntelliJ などの IDE を利用すると、コードの補完ができます。

この記事では、kintone Java Client の導入方法や基本的な使い方について説明します。
kintone Java Client が提供するメソッドの使い方の例は、 サンプル集 を参照してください。

GitHub

https://github.com/kintone/kintone-java-client (External link)

ライセンス

MIT ライセンス (External link)

制限事項

Android には対応していません。

ドキュメント

https://kintone.github.io/kintone-java-client/javadoc/ (External link)

導入方法

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. 文字列(1 行)フィールドを追加し、kintone アプリを作成します。

  2. 作成したアプリで API トークンを生成します。
    手順の詳細は、 API トークンを生成する (External link) を参照してください。

  3. 作成したアプリの URL で、アプリ ID を確認します。
    URL の https://sample.cybozu.com/k/123 の末尾の数字部分が、アプリ ID です。
    上記の場合、アプリ ID は、「123」です。

  4. テストデータとして、1 件のレコードを追加します。

  5. 作成したレコードの URL で、レコード ID を確認します。
    URL の https://sample.cybozu.com/k/123/show#record=1record= の後の数字部分が、レコード 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.javabuild.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. 文字列(1 行)フィールドを追加し、kintone アプリを作成します。

  2. 作成したアプリで API トークンを生成します。 手順の詳細は、 API トークンを生成する (External link) を参照してください。

  3. 作成したアプリの URL で、アプリ ID を確認します。
    URL の https://sample.cybozu.com/k/123 の末尾の数字部分が、アプリ ID です。
    上記の場合、アプリ ID は、「123」です。

  4. テストデータとして、1 件のレコードを追加します。

  5. 作成したレコードの URL で、レコード ID を確認します。
    URL の https://sample.cybozu.com/k/123/show#record=1record= の後の数字部分が、レコード 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.javapom.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-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 の操作は、次の手順で行います。

  1. kintone クライアントを生成する
  2. 操作対象のクライアントを取得する
  3. メソッドを呼び出し、kintone を操作する
Step1:kintone クライアントを生成する

KintoneClientBuilder を利用して、kintoneClient を生成します。
このとき、認証情報を設定します。 詳細は、 認証について を参照してください。

クローズ処理

kintoneClient は内部で HTTP コネクションを保有しています。
処理が終わり kintoneClient が役目を終えたら、 close() メソッドを呼び出し、クローズ処理を行ってください。

その他
  • KintoneClientBuilder では、コネクションタイムアウトやプロキシ設定など、さまざまな項目を設定できます。
  • setAppendixUserAgent() メソッドによって User-Agent に追記する文字列を入れることもできます。
    プログラム名や、処理内容を識別できる値を設定しておくと、今後、性能問題などが発生した場合にサイボウズ側でも調査しやすくなり、よりスピーディに問題解決できる場合があります。
    ぜひご活用ください
Step2:操作対象のクライアントを取得する

kintoneClient を生成したら、操作したい対象のクライアントを取得します。
操作対象には、 アプリ レコード スペース ファイル、スキーマ( API 情報)があります。

この例では、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 (External link) を参照してください。

  • 2020 年 6 月 1 日:「導入方法」で、ローカルの jar ファイルを利用する方法から、セントラルリポジトリを利用する方法に修正
information

この記事で紹介しているサンプルコードは、2020 年 2 月版 kintone および kintone Java Client v0.9 で動作を確認しています。