kintone Java Client のサンプルコード集

目次

概要

Javaからkintone REST APIを短いコード量で実行できる、kintone Java Clientがリリースされました。
この記事では、kintone Java Clientを用いてkintoneを操作するサンプルコードを紹介します。

kintone Java Clientの導入方法や、基本的な使い方は、 kintone Java Clientを参照してください。

以降の例では、getKintoneClient()というkintoneClientを生成・取得するメソッドがあるものとします。
kintone クライアントを生成する
また、この記事のkintone Java Clientは、v0.9.0を利用しています。

レコード操作

レコードを操作するには、RecordClientを使います。

レコードの取得

アプリIDが3で、レコード番号が15のレコードを取得する例です。

リクエストクラスを渡す方法
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// Get Record API 用リクエストを作成
GetRecordRequest req = new GetRecordRequest();
req.setApp(3L);
req.setId(15L);

try (KintoneClient client = getKintoneClient()) {
  // Get Record API 呼び出し
  GetRecordResponseBody resp = client.record().getRecord(req);
  Record record = resp.getRecord();
}
簡易メソッドを利用する方法
1
2
3
try (KintoneClient client = getKintoneClient()) {
  Record record = client.record().getRecord(3L, 15L);
}

レコードの作成

数値フィールドに30、文字列(1行)フィールドに「テキスト」という文字列を入れたレコードを作成する例です。

リクエストクラスを渡す方法
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// レコードオブジェクトを作成
Record record = new Record();
record.putField("数値フィールド", new NumberFieldValue(30L));
record.putField("文字列1行フィールド", new SingleLineTextFieldValue("テキスト"));

// Add Record API 用リクエストを作成
AddRecordRequest req = new AddRecordRequest();
req.setApp(40L);
req.setRecord(record);

try (KintoneClient client = getKintoneClient()) {
  // Add Record API 呼び出し
  AddRecordResponseBody resp = client.record().addRecord(req);
}
簡易メソッドを利用する方法
1
2
3
4
5
6
7
Record record = new Record();
record.putField("数値フィールド", new NumberFieldValue(30L));
record.putField("文字列1行フィールド", new SingleLineTextFieldValue("テキスト"));

try (KintoneClient client = getKintoneClient()) {
  long recordId = client.record().addRecord(40L, record);
}

レコードの更新

ドロップダウンフィールドの値を「Apple」に指定してレコードを更新する例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
try (KintoneClient client = getKintoneClient()) {
  // レコードを取得
  Record record = client.record().getRecord(17L, 4L);

  // ビルトインフィールドの情報を落とした新しいレコードオブジェクトを生成する
  Record newRecord = Record.newFrom(record);
  newRecord.putField("ドロップダウンフィールド", new DropDownFieldValue("Apple"));

  // 更新
  long revision = client.record().updateRecord(17L, 4L, newRecord);
}

この例では、kintoneから更新したいレコードを取得して一部を修正した後、RecordClient#updateRecord()に渡してレコードを更新しています。
取得したレコードオブジェクトには、レコード作成者などのビルトインフィールド情報も含まれています。
このビルドインフィールドを含んだ状態でレコードを更新すると、更新に失敗します。
そのため、Record.newFrom(Record)を使って、ビルトインフィールドを含まないレコードに再生成しています。

レコードの一括取得

レコードを一括取得するには、RecordClient#getRecords()を利用します。

以下は、offsetを利用してレコードを取得する例です。
offsetを利用してレコード一括取得する場合、第2引数にlimitを、第3引数にoffsetを指定します。

1
2
3
4
try (KintoneClient client = getKintoneClient()) {
  // アプリID が 10 のレコードのうち、300 件目から 20 件を取得
  List<Record> records = client.record().getRecords(10L, 20, 300);
}

取得するレコード件数が1万件を超える場合、RecordClient#getRecords()にクエリを指定してレコードを取得してください。
詳細は、次の記事を参照してください。

カーソルを用いたレコードの全件取得

カーソル APIを利用して、アプリのレコードを全件取得する例です。
カーソルAPIを利用すると、高速にレコード全件を取得できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
try (KintoneClient client = getKintoneClient()) {
  // カーソルを作成
  String cursorId = client.record().createCursor(10L);

  while (true) {
    // カーソルを元にレコード一覧取得
    GetRecordsByCursorResponseBody resp = client.record().getRecordsByCursor(cursorId);
    List<Record> records = resp.getRecords();

    // 次のデータが無ければループを終了
    if (!resp.hasNext()) {
      break;
    }
  }
}

クエリでレコードを絞り込みたい場合、第3引数にクエリを指定します。

1
2
// カーソルを作成
String cursorId = client.record().createCursor(10L, null, "数値フィールド > 10");

アプリ操作

レコードを操作するには、AppClientを使います。

アプリ情報の取得

アプリIDが30のアプリ情報を取得するサンプルコードです。

1
2
3
4
try (KintoneClient client = getKintoneClient()) {
  // アプリ ID が 30 のアプリ情報を取得
  App app = client.app().getApp(30L);
}

複数のアプリ情報(例では、アプリIDが30と40)を取得できます。

1
2
3
4
5
6
7
8
9
// 取得したいアプリ ID を指定する
List<Long> appIds = new ArrayList<>();
appIds.add(30L);
appIds.add(40L);

try (KintoneClient client = getKintoneClient()) {
  // 指定されたアプリのアプリ情報をすべて取得
  List<App> apps = client.app().getAppsByIds(appIds);
}

アプリの設定の運用環境への反映

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
long app = 30L;

try (KintoneClient client = getKintoneClient()) {
  // App Deploy API を呼び出す
  client.app().deployApp(app);

  // 反映処理が終わるまで待つ
  while (true) {
    DeployStatus status = client.app().getDeployStatus(app);
    if (status != DeployStatus.PROCESSING) {
        break;
    }
    // 処理が進むまで適度に待つ
    Thread.sleep(1000);
  }
}

スペース操作

スペースを操作するには、SpaceClientを使います。

スペース情報の取得

SpaceClient#getSpace()でスペース情報を取得できます。

1
2
3
try (KintoneClient client = getKintoneClient()) {
  GetSpaceResponseBody resp = client.space().getSpace(3L);
}

ファイル操作

ファイルを操作するには、FileClientを使います。

ファイルのアップロード

ファイルをアップロードする場合、ContentTypeの指定が必要です。
Javaではjava.nio.file.Files#probeContentType(Path)を使って自動判定できますが、Mac環境下では動作しないことに注意してください。

アップロードに成功すると、 ファイルキーfileKey)が返却されます。
fileKeyをレコードの添付ファイルに紐付けるには、レコードの登録やレコードの更新を使います。

リクエストクラスを渡す方法
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
UploadFileRequest req = new UploadFileRequest();
req.setFilename("image.png");
req.setContentType("image/png");

try (InputStream input = new FileInputStream("/path/to/file.png")) {
  req.setContent(input);
  try (KintoneClient client = getKintoneClient()) {
    UploadFileResponseBody resp = client.file().uploadFile(req);
    String fileKey = resp.getFileKey();
  }
}
簡易メソッドを利用する方法

簡易メソッドを利用すると、ファイルパスを指定してファイルをアップロードできます。

1
2
3
4
Path path = Paths.get("/path/to/file.png");
try (KintoneClient client = getKintoneClient()) {
  String fileKey = client.file().uploadFile(path, "image/png");
}

ファイルのダウンロード

ファイルをダウンロードする場合、レコードを取得して添付ファイルフィールドからfileKeyを取得します。
この取得したfileKeyFileClient#downloadFile()に指定します。
このときのfileKeyは、ファイルのアップロードで返却されるfileKeyとは異なるので注意してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
try (KintoneClient client = getKintoneClient()) {
  // 対象レコードのダウンロードしたいファイル一覧を取得
  Record record = client.record().getRecord(30L, 1L);
  List<FileBody> files = record.getFileFieldValue("添付ファイルフィールド");

  for (FileBody fileBody : files) {
    String fileKey = fileBody.getFileKey();
    // ダウンロード API を呼び出し、InputStream を取得する
    try (InputStream input = client.file().downloadFile(fileKey)) {
        // ローカルファイルに書き込む
        Files.copy(input, Paths.get("/tmp/", fileBody.getName()));
    }
  }
}

その他

複数アプリへのレコード一括処理

バルクリクエストを利用すると、複数のリクエストを同一トランザクションで実行できます。
例では、レコードを追加した後、レコードのステータスを更新しています。

バルクリクエストで操作できるAPIは次のドキュメントを参照してください。
複数アプリのレコード操作を一括処理する

 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
Record record = new Record();
record.putField("NumberField", new NumberFieldValue(120L));

// Add Record API 用のリクエストを作成
AddRecordRequest addRecordRequest = new AddRecordRequest()
                                      .setApp(10L)
                                      .setRecord(record);

// Update Record Status API 用のリクエストを作成
UpdateRecordStatusRequest updateRecordStatusRequest = new UpdateRecordStatusRequest()
                                                        .setApp(10L)
                                                        .setAssignee("user")
                                                        .setAction("NextAction");

BulkRequestsRequest req = new BulkRequestsRequest();
req.registerAddRecord(addRecordRequest); // レコード更新用リクエストを登録
req.registerUpdateRecordStatus(updateRecordStatusRequest); // ステータス更新用リクエストを登録

try (KintoneClient client = getKintoneClient()) {
  // バルクリクエストを実行
  BulkRequestsResponseBody resp = client.bulkRequests(req);

  for (KintoneResponseBody body : resp.getResults()) {
    // 実行した順にレスポンスを表示
    System.out.println(body);
  }
}
information

このTipsは、2020年2月版cybozu.comで動作を確認しています。