Index

• 概要

• 导入方法

• 使用方法

• 最后

• 更新记录

概要

kintone Java Client是指对使用Java语言进行kintone REST API自定义时的一些必要处理进行了封装的库。
基本上涵盖了kintone中可使用的REST API。 

有了kintone Java Client，您只要调用此库提供的方法，即可执行kintone REST API，可以大大减少代码量。
另外，使用IntelliJ等 IDE还可以自动补全代码。

此篇文档介绍kintone Java Client（以下简称本Client）的导入方法和基本的使用方法。关于kintone Java Client所提供的方法的使用范例，请参考范例代码合集。

关于此客户端库的技术支持方针请参考这里。

GitHub

https://github.com/kintone/kintone-java-client 

许可证

MIT 许可证

限制事项

不支持安卓。

文档

https://kintone.github.io/kintone-java-client/javadoc/

导入方法

Gradle项目的情况

在build.gradle内添加以下内容。
※ 第2行的版本改为要导入的kintone Java Client的版本。

dependencies {    
  implementation 'com.kintone:kintone-java-client:0.9.0'    
}

Maven项目的情况

在pom.xml内添加以下内容。
※ 第4行的version请输入要导入的kintone Java Client的版本。

<dependency>    
    <groupId>com.kintone</groupId>    
    <artifactId>kintone-java-client</artifactId>    
    <version>0.9.0</version>    
</dependency>

使用方法

以下介绍本Client的使用方法。另外，还可参考Javadoc。

以下例子是获取kintone记录，将记录ID输出到console。

package hello;

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://{your-domain}.cybozu.cn";
    String apiToken = "token";
    long appId = 1L;
    long recordId = 10L;

    System.out.println("Hello, kintone Java Client");

    // 用户API令牌验证
    try (KintoneClient client = KintoneClientBuilder.create(baseUrl).authByApiToken(apiToken).build()) {
      // 获取用于操作记录的client
      RecordClient recordClient = client.record();
      // 从kintone获取记录
      Record record = recordClient.getRecord(appId, recordId);
      // 输出记录ID
      System.out.println(record.getId());
    }
  }
}

※ 实际编程时，请不要将域名及验证信息等直接写在代码中，而是在Java属性文件等中进行定义后再读入。

※ 以上只是作为示范用的代码，因此省略了抛出例外时的处理。在实际的程序里，请务必要采取适当的错误处理。

请根据以下步骤来使用本Client对kintone进行操作。

• 步骤1. 生成kintone Client

• 步骤2.获取操作对象的Client

• 步骤3. 调用方法，操作kintone

步骤1. 生成kintone Client

使用KintoneClientBuilder生成KintoneClient。

设置验证信息

本Client支持密码验证和 API令牌验证。

用密码验证创建 kintone Client

String baseUrl = "https://{your-domain}.cybozu.cn";    
String username = "username";    
String password = "password";    

KintoneClient client = KintoneClientBuilder    
                       // 设置访问对象的kintone URL    
                       .create(baseUrl)    
                       // 设置验证所需的用户名和密码    
                       .authByPassword(username, password)    
                       .build();

用API令牌验证创建 kintone Client

String baseUrl = "https://{your-domain}.cybozu.cn";    
String apiToken = "token";  
  
KintoneClient client = KintoneClientBuilder    
                       // 设置访问对象的kintone URL    
                       .create(baseUrl)    
                       // 设置验证时所需的API令牌    
                       .authByApiToken(apiToken)    
                       .build();

也可设置客户证书和Basic验证信息。

设置客户证书

// 使用客户证书时，请在域名后加上.s    
String baseUrl = "https://{your-domain}.s.cybozu.cn";    
String apiToken = "token";

KintoneClient client = KintoneClientBuilder    
                       .create(baseUrl)    
                       .authByApiToken(apiToken)    
                       // 设置客户证书和密码    
                       .withClientCertificate(Paths.get("/path/to/ file"), "password")    
                       .build();

设置Basic验证

String baseUrl = "https://{your-domain}.cybozu.cn";    
String apiToken = "token";
 
KintoneClient client = KintoneClientBuilder    
                       .create(baseUrl)    
                       .authByApiToken(apiToken)    
                       // 设置Basic验证所需的用户名和密码    
                       .withBasicAuth("basic", "password")    
                       .build();

如除了kintone的URL和验证信息之外，其他没有需要设置的项目，使用defaultClient方法可以更加简单地创建KintoneClient。

关闭处理

KintoneClient内部带有HTTP连接。
处理结束后，KintoneClient的任务就完成了，这时请调用close()方法关闭处理。

其他

• KintoneClientBuilder中还可以设置连接超时以及代理等各项目。

• 还可以使用setAppendixUserAgent方法向 User-Agent添加字符。
  如设置了用于识别程序名称及处理内容的值，以后发生性能等问题时，才望子将可更加方便地进行调查，加快问题的解决。请务必设置一下。
  

步骤2.获取操作对象的Client

生成KintoneClient后，获取要进行操作的对象的Client。
操作对象里有[应用]、[记录]、[空间]、[文件]、[schema（API的schema信息）]。

try (KintoneClient client = getKintoneClient()) {    
  //获取操作应用时所需的Client    
  AppClient appClient = client.app();  
    
  // 获取操作记录所需的Client    
  RecordClient recordClient = client.record(); 
     
  // 获取操作空间所需的Client    
  SpaceClient spaceClient = client.space(); 
     
  // 获取操作文件所需的Client    
  FileClient fileClient = client.file(); 
     
  //获取操作schema所需的Client    
  SchemaClient schemaClient = client.schema();    
}

上面代码中用到了 try-with-resources ，可以在处理结束时自动调用KintoneClient#close()方法。

如果没有什么特别的理由，推荐使用 try-with-resources ，以确保处理结束后能正确调用close()。

※ 本例的前提是存在一个名称为getKintoneClient()、用于获取KintoneClient的方法。

步骤3. 调用方法，操作kintone

创建好操作对象的Client之后，调用操作方法。

操作kintone时，将请求参数传给kintone REST API各API相对应的方法。部分方法可以用更加简单的方法。

方法1:将请求类传递给各API相对应的方法，操作kintone

将请求类“API 名 + Request”传递给操作对象的Client，然后获取应答类的实例“API 名 + ResponseBody”。

下面是获取记录 API（get record）的例子。
请求类：GetRecordRequest
应答类：GetRecordResponseBody

// 生成获取记录的请求类的实例    
GetRecordRequest req = new GetRecordRequest();    
req.setApp(3L); // 设置获取对象的应用ID （应用ID为long类型）    
req.setId(15L); // 设置获取对象的记录ID （记录ID为long类型）
 
// 传递给记录client，调用API    
GetRecordResponseBody resp = client.record().getRecord(req); 

// 从应答中获取记录对象    
Record record = resp.getRecord();    

// 显示记录ID    
System.out.println(record.getId());

方法2: 使用更加方便的方法，操作kintone

使用getRecord方法更方便，上面的代码可精简如下：

// 使用更改简单的方法获取记录信息    
Record record = client.record().getRecord(3L, 15L);

// 显示记录ID    
System.out.println(record.getId());

最后

通过使用kintone Java Client，在使用Java进行批处理或手机应用开发时，可更轻松地执行kintone REST API。

关于kintone Java Client的使用方法请参考范例代码合集。

更新记录

请参考此页面以获取库的更新信息。

• 2020年6月1日将导入方法由使用本地的jar文件的方法改成使用中央仓库的方法
  

此Tips在2020年2月版 kintone以及 kintone Java Client v0.9中确认过。