Skip to content

调用服务端 API ​

本文档介绍如何通过 Java SDK,自行构建 API Client、构造 API 请求、最终成功调用服务端 API。你可前往 API 调试台,直接获取指定服务端 API 相关示例代码,然后参考本文档了解调用 API 的全面流程。

步骤一:构建 API Client ​

通过 SDK 调用飞书开放接口之前,你需要先在代码中创建一个 API Client。该 API Client 支持指定当前使用的应用信息、日志级别、HTTP 请求超时时间等基本信息。以下为支持的配置项及其具体含义。

java
Client client=Client.newBuilder("appId","appSecret") // 默认配置为自建应用
    .marketplaceApp() // 设置应用类型为商店应用
    .openBaseUrl(BaseUrlEnum.FeiShu) // 设置域名,默认为飞书
    .helpDeskCredential("helpDeskId","helpDeskSecret") // 服务台应用才需要设置
    .requestTimeout(3,TimeUnit.SECONDS) // 设置httpclient 超时时间,默认永不超时
    .logReqAtDebug(true) // 在 debug 模式下会打印 http 请求和响应的 headers、body 等信息。
    .build();
配置选项配置方式是否必填描述
app_id 和 app_secretClient.newBuilder("appId","appSecret")是应用凭证 App ID 和 App Secret。可在开发者后台 > 应用详情页 > 凭证与基础信息 > 应用凭证 区域获取。图片名称
appTypeclient.marketplaceApp()否设置 App 类型为商店应用。如果你是 ISV 开发者,则必须设置该选项。关于商店应用的开发指南,可参见 ISV(商店应用)开发指南-oapi-sdk-java。
logReqAtDebugclient.logReqAtDebug(boolean logReqAtDebug)否设置是否开启 HTTP 请求参数和响应参数的日志打印开关。开启后,在 debug 模式下会打印 HTTP 请求和响应的 headers、body 等信息。在排查问题时开启该选项,有利于问题的排查。
BaseUrlclient.openBaseUrl(BaseUrlEnum baseUrl)否设置飞书域名,默认为 FeishuBaseUrl。可用域名如下: java public enum BaseUrlEnum `{ FeiShu("https://open.feishu.cn"), LarkSuite("https://open.larksuite.com"), ; }`
tokenCacheclient.tokenCache(ICache cache)否设置 Token 缓存器,用于缓存 Token 和 appTIcket,默认实现为内存。 java public interface ICache { // 获取缓存值 String get(String key); // 设置缓存值 void set(String key, String value, int expire, TimeUnit timeUnit); } 对于商店应用的开发者而言,如果需要 SDK 来缓存 appTicket,则需要实现该接口,以提供分布式缓存。
disableTokenCacheclient.disableTokenCache()否设置是否开启 TenantAccessToken (应用访问凭证)的自动获取与缓存。 若配置该选项,表示关闭自动获取与缓存 TenantAccessToken;若不配置则为开启。
helpDeskId、helpDeskTokenclient.helpDeskCredential(String helpDeskId, String helpDeskToken)否服务台的 ID 和 token。仅在调用服务台业务的 API 时需要配置。可在服务台管理后台设置中心 > API 凭证 处获取,详情参见 服务台接入指南。 注意:服务台的 ID、Token 只有服务台创建者可以查看到。图片名称
requestTimeoutclient.requestTimeout(long timeout, TimeUnit timeUnit)否设置 SDK 内置的 Http Client 的请求超时时间。默认为 0 表示永不超时。
httpTransportclient.httpTransport(IHttpTransport httpTransport)否设置传输层实现,用于替换 SDK 提供的默认实现。你可通过实现下面的 IHttpTransport 接口来设置自定义的传输实现: java public interface IHttpTransport { RawResponse execute(RawRequest request) throws Exception; } 目前提供了以下两种实现: - 基于 OKhttp 的实现,使用方式参见示例代码。 - 基于 Apache HttpClient 的实现,使用方式参见示例代码。

示例配置:

  • 对于自建应用,使用以下代码创建 API Client。

    java
    Client client=Client.newBuilder("appId","appSecret").build();  // 默认配置为自建应用
  • 对于商店应用,需在创建 API Client 时,使用 marketplaceApp() 方法指定 AppType 为商店应用,代码配置如下。了解更多可参考 ISV(商店应用)开发指南-oapi-sdk-java。

    java
    Client client = Client.newBuilder("appId", "appSecret")
        .marketplaceApp() // 设置应用为商店应用
        .build();

步骤二:构造 API 请求 ​

在项目内创建好一个 API Client 后,即可开始调用飞书开放平台接口。SDK 使用 client. 业务域.版本.资源 .方法名称 来定位具体的 API 方法。如下图示例,你可前往 API 调试台,选择指定 API,在示例代码处直接获取 API 方法。

如下代码示例,你可通过 client 调用文档资源的 create 方法,创建一个文档。

Note 该示例需要你在开发者后台为应用开通[创建及编辑新版文档]或[创建新版文档]权限,否则接口将报 99991672 错误码。

java
import com.lark.oapi.Client;
import com.lark.oapi.core.utils.Jsons;
import com.lark.oapi.service.docx.v1.model.CreateDocumentReq;
import com.lark.oapi.service.docx.v1.model.CreateDocumentReqBody;
import com.lark.oapi.service.docx.v1.model.CreateDocumentResp;
public class DocxSample {
  
  public static void main(String arg[]) throws Exception {
    // 构建client
    Client client = Client.newBuilder("appId", "appSecret").build();
    // 发起请求
    CreateDocumentResp resp = client.docx().document()
        .create(CreateDocumentReq.newBuilder()
            .createDocumentReqBody(CreateDocumentReqBody.newBuilder()
                .title("title")   // 文档标题
                .folderToken("")   // 文件夹 token,传空表示在根目录创建文档
                .build())
            .build()
        );
    // 处理服务端错误
    if (!resp.success()) {
      System.out.println(String.format("code:%s,msg:%s,reqId:%s"
          , resp.getCode(), resp.getMsg(), resp.getRequestId()));
      return;
    }
    // 业务数据处理
    System.out.println(Jsons.DEFAULT.toJson(resp.getData()));
  }
}

其他 API 调用示例请参考 GitHub 代码仓库中的 Im Java 示例。

(可选)步骤三:设置请求选项 ​

在每次发起 API 调用时,你可以设置请求级别的相关参数,例如传递 userAccessToken(用户访问凭证)、自定义 headers 等。所有请求级别可设置的选项如下表所示。

配置选项配置方式描述
headersrequestOptions.headers(Map<String, List<String>> headers)设置自定义请求头。在发起请求时,这些请求头会被透传到飞书开放平台服务端。
userAccessTokenrequestOptions.userAccessToken(String userAccessToken)设置用户 token,当你需要以用户身份发起 API 调用时,需要设置该选项的值。
tenantAccessTokenrequestOptions.tenantAccessToken(String tenantAccessToken)设置企业或组织 token,当你自己维护企业或组织 token 时(即创建 client 时 EnableTokenCache 设置为 false),需通过该选项传递企业或组织 token。
tenantKeyrequestOptions.tenantKey(tenantKey string)设置企业或组织 key, 当你开发商店应用时,必须设置该选项。
requestIdrequestOptions.requestId(requestId string)设置请求 ID,作为请求的唯一标识。该 ID 会被透传到飞书开放平台服务端。

设置自定义请求头的示例代码如下所示。

java
import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.core.utils.Jsons;
import com.lark.oapi.core.utils.Lists;
import com.lark.oapi.service.docx.v1.model.CreateDocumentReq;
import com.lark.oapi.service.docx.v1.model.CreateDocumentReqBody;
import com.lark.oapi.service.docx.v1.model.CreateDocumentResp;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class DocxSample {
  public static void main(String arg[]) throws Exception {
    // 创建 API Client。你需在此传入你的应用的实际 App ID 和 App Secret
    Client client = Client.newBuilder("appId", "appSecret").build();
    // 设置自定义请求头
    Map<String, List<String>> headers = new HashMap<>();
    headers.put("key1", Lists.newArrayList("value1"));
    headers.put("key2", Lists.newArrayList("value2"));
    // 发起请求
    CreateDocumentResp resp = client.docx().document()
        .create(CreateDocumentReq.newBuilder()
                .createDocumentReqBody(CreateDocumentReqBody.newBuilder()
                    .title("title")   // 文档标题
                    .folderToken("")  // 文件夹 token,传空表示在根目录创建文档
                    .build())
                .build()
            , RequestOptions.newBuilder()
                .userAccessToken("u-2GxFH7ysh8E9lj9UJp8XAG0k0gh1h5KzM800khEw2G6e") // 传递用户token
                .headers(headers) // 传递自定义请求头
                .build());
    // 处理服务端错误
    if (!resp.success()) {
      System.out.println(String.format("code:%s,msg:%s,reqId:%s"
          , resp.getCode(), resp.getMsg(), resp.getRequestId()));
      return;
    }
    // 业务数据处理
    System.out.println(Jsons.DEFAULT.toJson(resp.getData()));
  }
}

步骤四:运行代码 ​

完成以上步骤后,即可运行代码调用创建文档 API。若请求成功,预计将返回以下数据。若失败,将返回错误码、错误信息和 Log ID,你可前往开发文档搜索解决方案。

json
{
  Document: {
    DocumentId: "IPI4dqnbfoPxL3xhAEhcjXabcef",
    RevisionId: 1,
    Title: "title"
  }
}

常见问题 ​

如何调用历史版本 API ? ​

服务端 API 中存在部分历史版本的开放接口,由于没有元数据信息,所以不能使用 SDK 内封装好的方法快速调用,此时你可以使用 SDK 提供的原生模式调用 API。以发送消息接口为例,调用示例如下所示:

java
package com.lark.oapi.sample.rawapi;
import com.lark.oapi.Client;
import com.lark.oapi.core.enums.AppType;
import com.lark.oapi.core.response.RawResponse;
import com.lark.oapi.core.token.AccessTokenType;
import com.lark.oapi.core.utils.Jsons;
import java.util.HashMap;
import java.util.Map;
/**
 * 原生http 调用方式
 */
public class RawApiCall {
  public static void main(String arg[]) throws Exception {
    // 构建client
    Client client = Client.newBuilder("appId", "appSecret").build();
    // 构建http body
    Map<String, Object> body = new HashMap<>();
    body.put("receive_id", "ou_c245b0a7dff2725cfa2fb104f8b48b9d");
    body.put("content", MessageText.newBuilder()
        .atUser("ou_155184d1e73cbfb8973e5a9e698e74f2", "Tom")
        .text("test content")
        .build());
    body.put("msg_type", MsgTypeEnum.MSG_TYPE_TEXT);
    // 发起请求
    RawResponse resp = client.post(
        "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id"
        , body
        , AccessTokenType.Tenant);
    // 处理结果
    System.out.println(resp.getStatusCode());
    System.out.println(Jsons.DEFAULT.toJson(resp.getHeaders()));
    System.out.println(new String(resp.getBody()));
    System.out.println(resp.getRequestID());
  }
}

了解更多 API 调用示例,参考 GitHub 代码仓库中的 RawApiCall Java 示例。

如何快速获取接口对应的示例代码? ​

飞书开放平台提供了 API 调试台,通过该平台可以快速调试服务端 API,快速获取资源 ID 及生成多语言示例代码的能力,为您节省开发成本。例如,通过 API 调试台调用 发送消息 接口,在调试台成功完成测试后,可通过 示例代码 页面查阅 Java SDK 对应的接口调用代码。

如何准确选择 API? ​

使用 API Client 调用 API 时,对应的方法建议你借助 API 调试台获取,可通过指定接口的地址栏参数拼接方法,也可以直接参考接口提供的示例代码。以通过手机号或邮箱获取用户 ID 接口为例,获取方式如下图所示。

开放接口的 HTTP GET 请求需要携带请求体 Body 参数,如何传参? ​

由于默认的客户端实现(OkHttp3Client)不支持这种方式,因此你需要切换成 ApacheHttpClient。参考以下代码:

java
Client.newBuilder(appId, appSecret)
      .httpTransport(
          ApacheHttpClientTransport.newBuilder().httpclient(HttpClients.createDefault()).build()
      )

接口超时并报错 ClientTimeoutException,如何解决? ​

该报错是因为构建 API Client 时未配置超时时间引起的,你需要在 Client 内配置超时时间,参考如下代码配置:

java
@Test
void init() {
    Client client = Client.newBuilder("appId", "appSecret")
        .httpTransport(new OkHttpTransport(
            new OkHttpClient().newBuilder()
                .readTimeout(3, TimeUnit.MINUTES)  // 设置超时时间,单位必须为分钟
                .callTimeout(3, TimeUnit.MINUTES)  // 设置超时时间,单位必须为分钟
                .build()
        ))
        .tokenCache(LocalCache.getInstance())      // 默认实现,本地带时间过期的缓存;可以自己实现ICache的接口,例如Redis缓存等
        .logReqAtDebug(true)                       // 在 debug 模式下会打印 http 请求和响应的 headers,body 等信息。 
        .build();
}

示例代码运行后,Client 正常发起请求并返回响应结果,但程序仍然一直运行了一段时间才自动停止是什么原因? ​

在使用 OkHttp 作为 HTTP 客户端库时,OkHttp 会在内部维护一个连接池(Connection Pool),用于复用已经建立的 HTTP 连接,以提高性能。连接池中的连接有 5 分钟的存活时间(TTL),进程可能不会立即结束,而是会保持活跃一段时间,直到所有连接的 TTL 到期或被手动关闭。

如果希望进程立即结束,可以通过设置 Connection: close 请求头来禁用 OkHttp 的连接复用能力,但该方式会导致网络性能下降,请谨慎操作。

MessageCardElement 缺少 tag 为 table 的实现类。 ​

回答:

Java SDK 中的 MessageCardElement 类已停止维护。建议使用 飞书卡片搭建工具 设计卡片,并导出 JSON 模板,直接通过 JSON 字符串或 Map 结构构建卡片内容。

com.lark.oapi.core.exception.IllegalAccessTokenTypeException: null 错误 ​

回答:

先核查接口是否仅支持 UserAccessToken;若为仅支持的类型,需进一步检查调用接口时是否已传入该 Token,未传入则补充传入即可。

本地启动长连接后,没有打印 "connected to wss://xxxxx"信息,也没有其他报错。 ​

回答:

检查 logback.xml 配置文件,确认是否关闭了 oapi 包的日志打印

上传审批文件示例代码报错,或不知道如何构造请求? ​

参考文档:上传审批文件

正确的示例代码:

java
FormData formData = new FormData();
formData.addField("name", file.getName());
formData.addField("type", "attachment");
FormDataFile formDataFile = new FormDataFile();
formDataFile.setFieldName("content");
formDataFile.setFile(file);
formData.addFile("content", formDataFile);

ERROR com.lark.oapi.ws.Listener [Listener.java:83] - java.io.EOFException错误 ​

回答:

该错误通常由网络连接中断或服务端主动断开连接导致。SDK 内部已实现自动重连机制,偶发该错误可忽略;如频繁出现,请检查服务器网络稳定性。

批量请求接口超时、client time out、SocketTimeoutException: timeout、java.io.IOException: Canceled: ​

  • 批量接口超时示例:

image.png

  • Client time out示例:
com.lark.oapi.core.exception.ClientTimeoutException: client time out
at com.lark.oapi.core.Transport.send(Transport.java:189)
at com.lark.oapi.service.contact.v3.resource.User.batchGetId(User.java:162)
  • SocketTimeoutException: timeout 示例:

image.png原因:

OkHttp 中 CallTimeout 未手动设置时理论上无超时限制,但实际请求的connect(连接)、read(读取)、write(写入) 各阶段均有默认超时时间(均为 10s);服务端接口调用的超时问题,一般均发生在 readtimeout(读取)阶段,可通过以下方式调整各阶段超时配置:

java
import com.lark.oapi.Client;
import com.lark.oapi.core.cache.LocalCache;
import com.lark.oapi.core.httpclient.OkHttpTransport;
import com.lark.oapi.okhttp.OkHttpClient;    
import java.net.Proxy;
import java.util.concurrent.TimeUnit;

@Test
void init() {
    Client client = Client.newBuilder("appId", "appSecret")
        .httpTransport(
            new OkHttpTransport(
                new OkHttpClient().newBuilder()
                    .readTimeout(3, TimeUnit.MINUTES) // 等待服务端返回响应数据阶段的超时设置
                    .callTimeout(3, TimeUnit.MINUTES) // 从请求发起到响应完全接收的全生命周期的超时时间设置
                    .build()
        ))
        .tokenCache(LocalCache.getInstance())     // 默认实现,本地带时间过期的缓存;可以自己实现ICache的接口,例如Redis缓存等
        .logReqAtDebug(true)                      // 在 debug 模式下会打印 http 请求和响应的 headers,body 等信息。
        .build();
}

下载素材接口 Java 示例代码运行报错:java.lang.IllegalArgumentException: The result returned by the server is illegal ​

参考文档:下载素材

示例代码:

java
public static void main(String arg[]) throws Exception {
    Client client = Client.newBuilder("xxx", "xxx").build();

    DownloadMediaReq req = DownloadMediaReq.newBuilder()
            .fileToken("xxx")
            .extra("%7B%22bitablePerm%22%3A%7B%22tableId%22%3A%22tblQ7MgglSH9q3NE%22%2C%22rev%22%3A5%7D%7D")
            .build();

    DownloadMediaResp resp = client.drive().v1().media().download(req);

    if(!resp.success()) {
        System.out.println(String.format("code:%s,msg:%s,reqId:%s, resp:%s",
                resp.getCode(), resp.getMsg(), resp.getRequestId(), Jsons.createGSON(true, false).toJson(JsonParser.parseString(new String(resp.getRawResponse().getBody(), StandardCharsets.UTF_8)))));
        return;
    }

    // 业务数据处理
    resp.writeFile("c:/filepath/filename");
}

原因:

用户传入的 extra 为已编码的参数,但 Java SDK 内部会对 extra 字段值自动执行一次编码操作,导致该参数被重复编码,最终引发参数传入异常。

解决方式:

传入 extra 参数时,请直接使用编码前的原始参数,示例传入方式如下:

java
DownloadMediaReq req = DownloadMediaReq.newBuilder()
        .fileToken("xxxx")
        .extra("{\"bitablePerm\":{\"tableId\":\"xxxx\",\"rev\":5}}")
        .build();

内容来源:飞书开放平台 · 自动爬取整理