# oapi-sdk-go **Repository Path**: larksuite/oapi-sdk-go ## Basic Information - **Project Name**: oapi-sdk-go - **Description**: larksuite oapi sdk by golang - **Primary Language**: Go - **License**: MIT - **Default Branch**: v3_main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2022-09-05 - **Last Updated**: 2024-03-05 ## 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调用方式) - [处理消息事件回调](#处理消息事件回调) - [基本用法](#基本用法-1) - [消息处理器内给对应租户发消息](#消息处理器内给对应租户发消息) - [集成gin框架](#集成gin框架) - [安装集成包](#安装集成包) - [集成示例](#集成示例) - [处理卡片行为回调](#处理卡片行为回调) - [基本用法](#基本用法-2) - [返回卡片消息](#返回卡片消息) - [返回自定义消息](#返回自定义消息) - [卡片行为处理器内给对应租户发消息](#卡片行为处理器内给对应租户发消息) - [集成gin框架](#集成gin框架) - [安装集成包](#安装集成包) - [集成示例](#集成示例) ## 安装 ```go go get -u gitee.com/larksuite/oapi-sdk-go/v3@v3.0.3 ``` ## API Client 开发者在调用 API 前,需要先创建一个 API Client,然后才可以基于 API Client 发起 API 调用。 ### 创建API Client - 对于自建应用,可使用下面代码来创建一个 API Client ```go var client = lark.NewClient("appID", "appSecret") // 默认配置为自建应用 ``` - 对于商店应用,需在创建 API Client 时,使用 lark.WithMarketplaceApp 方法指定 AppType 为商店应用 ```go var client = lark.NewClient("appID", "appSecret",lark.WithMarketplaceApp()) // 设置App为商店应用 ``` ### 配置API Client 创建 API Client 时,可对 API Client 进行一定的配置,比如我们可以在创建 API Client 时设置日志级别、设置 http 请求超时时间等等: ```go var client = lark.NewClient("appID", "appSecret", lark.WithLogLevel(larkcore.LogLevelDebug), lark.WithReqTimeout(3*time.Second), lark.WithEnableTokenCache(true), lark.WithHelpdeskCredential("id", "token"), lark.WithHttpClient(http.DefaultClient)) ``` 每个配置选项的具体含义,如下表格:
配置选项 | 配置方式 | 描述 |
---|---|---|
AppType
|
lark.WithMarketplaceApp()
|
设置 App 类型为 商店应用 ,ISV 开发者必须要设置该选项。 |
LogLevel
|
lark.WithLogLevel(logLevel larkcore.LogLevel)
|
设置 API Client 的日志输出级别(默认为 Info 级别),枚举值如下: - LogLevelDebug - LogLevelInfo - LogLevelWarn - LogLevelError |
Logger
|
lark.WithLogger(logger larkcore.Logger)
|
设置API Client的日志器,默认日志输出到标准输出。 开发者可通过实现下面的 Logger 接口,来设置自定义的日志器: ```go type Logger interface { Debug(context.Context, ...interface{}) Info(context.Context, ...interface{}) Warn(context.Context, ...interface{}) Error(context.Context, ...interface{}) } ``` |
LogReqAtDebug
|
lark.WithLogReqAtDebug(printReqRespLog bool)
|
设置是否开启 Http 请求参数和响应参数的日志打印开关;开启后,在 debug 模式下会打印 http 请求和响应的 headers,body 等信息。 在排查问题时,开启该选项,有利于问题的排查。 |
BaseUrl
|
lark.WithOpenBaseUrl(baseUrl string)
|
设置飞书域名,默认为FeishuBaseUrl,可用域名列表为: ```go // 飞书域名 var FeishuBaseUrl = "https://open.feishu.cn" // Lark域名 var LarkBaseUrl = "https://open.larksuite.com" ``` |
TokenCache
|
lark.WithTokenCache(cache larkcore.Cache)
|
设置 token 缓存器,用来缓存 token 和 appTicket, 默认实现为内存。 如开发者想要定制 token 缓存器,需实现下面 Cache 接口: ```go type Cache interface { Set(ctx context.Context, key string, value string, expireTime time.Duration) error Get(ctx context.Context, key string) (string, error) } ``` 对于 ISV 开发者来说,如需要 SDK 来缓存 appTicket,需要实现该接口,实现提供分布式缓存。 |
EnableTokenCache
|
lark.WithEnableTokenCache(enableTokenCache bool)
|
设置是否开启 TenantAccessToken 的自动获取与缓存。 默认开启,如需要关闭可传递 false。 |
HelpDeskId、HelpDeskToken
|
lark.WithHelpdeskCredential(helpdeskID, helpdeskToken string)
|
该选项仅在调用服务台业务的 API 时需要配置。 |
ReqTimeout
|
lark.WithReqTimeout(time time.Duration)
|
设置 SDK 内置的 Http Client 的请求超时时间,默认为0代表永不超时。 |
HttpClient
|
lark.WithHttpClient(httpClient larkcore.HttpClient)
|
设置 HttpClient,用于替换 SDK 提供的默认实现。 开发者可通过实现下面的 HttpClient 接口来设置自定义的 HttpClient: ```go type HttpClient interface { Do(*http.Request) (*http.Response, error) } ``` |
配置选项 | 配置方式 | 描述 |
---|---|---|
Header
|
larkcore.WithHeaders(header http.Header)
|
设置自定义请求头,开发者可在发起请求时,这些请求头会被透传到飞书开放平台服务端。 |
UserAccessToken
|
larkcore.WithUserAccessToken(userAccessToken string)
|
设置用户token,当开发者需要以用户身份发起调用时,需要设置该选项的值。 |
TenantAccessToken
|
larkcore.WithTenantAccessToken(tenantAccessToken string)
|
设置租户 token,当开发者自己维护租户 token 时(即创建Client时EnableTokenCache设置为了false),需通过该选项传递 租户 token。 |
TenantKey
|
larkcore.WithTenantKey(tenantKey string)
|
设置租户 key, 当开发者开发商店应用时,必须设置该选项。 |
RequestId
|
larkCore.WithRequestId(requestId string)
|
设置请求 ID,用来做请求的唯一标识,该 ID 会被透传到飞书开放平台服务端。 |