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 で動作を確認しています。