# oapi-sdk-java
**Repository Path**: larksuite/oapi-sdk-java
## Basic Information
- **Project Name**: oapi-sdk-java
- **Description**: larksuite oapi sdk by java
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: v2_main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 5
- **Forks**: 0
- **Created**: 2022-09-06
- **Last Updated**: 2024-08-15
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 飞书开放接口SDK
旨在让开发者便捷的调用飞书开放API、处理订阅的消息事件、处理服务端推送的卡片行为。
## 目录
- [安装](#安装)
- [API Client](#api-client)
- [创建API Client](#创建api-client)
- [配置API Client](#配置api-client)
- [API调用](#api调用)
- [基本用法](#基本用法)
- [设置请求选项](#设置请求选项)
- [原生API调用方式](#原生api调用方式)
- [处理消息事件回调](#处理消息事件回调)
- [概要](#概要)
- [集成 servlet 容器](#集成-servlet-容器)
- [安装集成包](#安装集成包)
- [集成示例](#集成示例)
- [消息处理器内给对应租户发消息](#消息处理器内给对应租户发消息)
- [处理卡片行为回调](#处理卡片行为回调)
- [集成 servlet 容器](#集成-servlet-容器-1)
- [安装集成包](#安装集成包-1)
- [集成示例](#集成示例-1)
- [返回卡片消息](#返回卡片消息)
- [返回自定义消息](#返回自定义消息)
- [卡片行为处理器内给对应租户发消息](#卡片行为处理器内给对应租户发消息)
- [License](#License)
## 安装
- 运行环境:JDK 1.8及以上
- 最新版本 maven 坐标
```shell
配置选项 | 配置方式 | 描述 |
---|---|---|
appType
|
client.marketplaceApp()
|
设置 App 类型为商店应用,ISV 开发者必须要设置该选项。 |
logReqAtDebug
|
client.logReqAtDebug(boolean logReqAtDebug)
|
设置是否开启 Http 请求参数和响应参数的日志打印开关; 开启后,在 debug 模式下会打印 http 请求和响应的 headers,body 等信息。 在排查问题时,开启该选项,有利于问题的排查。 |
BaseUrl
|
client.openBaseUrl(BaseUrlEnum baseUrl)
|
设置飞书域名,默认为FeishuBaseUrl,可用域名列表为: ```java public enum BaseUrlEnum { FeiShu("https://open.feishu.cn"), LarkSuite("https://open.larksuite.com"), ; } ``` |
tokenCache
|
client.tokenCache(ICache cache)
|
设置 token 缓存器,用来缓存 token 和 appTicket, 默认实现为内存。 如开发者想要定制 token 缓存器,需实现下面 Cache 接口: ```Java public interface ICache { // 获取缓存值 String get(String key); // 设置缓存值 void set(String key, String value, int expire, TimeUnit timeUnit); } ``` 对于 ISV 开发者来说,如需要 SDK 来缓存 appTicket,需要实现该接口,实现提供分布式缓存。 |
disableTokenCache
|
client.disableTokenCache()
|
设置是否开启 TenantAccessToken 的自动获取与缓存。 默认开启,如需要关闭可传递 false。 |
helpDeskId、helpDeskToken
|
client.helpDeskCredential(String helpDeskId, String helpDeskToken)
|
该选项仅在调用服务台业务的 API 时需要配置。 |
requestTimeout
|
client.requestTimeout(long timeout, TimeUnit timeUnit)
|
设置 SDK 内置的 Http Client 的请求超时时间,默认为0代表永不超时。 |
httpTransport
|
client.httpTransport(IHttpTransport httpTransport)
|
设置传输层实现,用于替换 SDK 提供的默认实现。 开发者可通过实现下面的 IHttpTransport 接口来设置自定义的 传输实现: ```Java public interface IHttpTransport { RawResponse execute(RawRequest request) throws Exception; } ``` 目前提供了两种实现: 1. 基于 [OKhttp](./larksuite-oapi/src/main/java/com/lark/oapi/core/httpclient/OkHttpTransport.java) 的实现,使用 [demo](./sample/src/main/java/com/lark/oapi/sample/api/ClientSample.java) 2. 基于 [Apache HttpClient](https://github.com/larksuite/oapi-sdk-java-ext) 的实现,使用 [demo](./sample/src/main/java/com/lark/oapi/sample/api/ClientSample.java) |
配置选项 | 配置方式 | 描述 |
---|---|---|
headers
|
requestOptions.headers(Map<String, List<String>> headers)
|
设置自定义请求头,开发者可在发起请求时,这些请求头会被透传到飞书开放平台服务端。 |
userAccessToken
|
requestOptions.userAccessToken(String userAccessToken)
|
设置用户token,当开发者需要以用户身份发起调用时,需要设置该选项的值。 |
tenantAccessToken
|
requestOptions.tenantAccessToken(String tenantAccessToken)
|
设置租户 token,当开发者自己维护租户 token 时(即创建Client时EnableTokenCache设置为了false),需通过该选项传递 租户 token。 |
tenantKey
|
requestOptions.tenantKey(tenantKey string)
|
设置租户 key, 当开发者开发商店应用时,必须设置该选项。 |
requestId
|
requestOptions.requestId(requestId string)
|
设置请求 ID,用来做请求的唯一标识,该 ID 会被透传到飞书开放平台服务端。 |