sdk

package module

v1.0.9 Latest Latest Go to latest Published: Jan 16, 2025 License: Apache-2.0 Imports: 18 Imported by: 1

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/larksuite/project-oapi-sdk-golang

README ¶

飞书项目开放接口SDK

旨在让开发者便捷的调用飞书项目OPEN API

安装

go get -u github.com/larksuite/project-oapi-sdk-golang

API Client

开发者在调用 API 前，需要先创建一个 API Client，然后才可以基于 API Client 发起 API 调用，Client对象线程安全，全局初始化一次即可。

创建API Client

import sdk "github.com/larksuite/project-oapi-sdk-golang"

var client = sdk.NewClient("PluginID", "PluginSecret") //默认插件身份凭证

配置API Client

创建 API Client 时，可对 API Client 进行一定的配置，比如我们可以在创建 API Client 时设置日志级别、设置 http 请求超时时间等等：

import sdk "github.com/larksuite/project-oapi-sdk-golang"

var client = sdk.NewClient("PluginID", "PluginSecret",
sdk.WithLogLevel(core.LogLevelDebug),
sdk.WithReqTimeout(3*time.Second),
sdk.WithEnableTokenCache(true),
sdk.WithHttpClient(http.DefaultClient))

每个配置选项的具体含义，如下表格：

配置选项	配置方式	描述
`LogLevel`	`sdk.WithLogLevel(logLevel projectcore.LogLevel)`	设置 API Client 的日志输出级别(默认为 Info 级别)，枚举值如下： LogLevelDebug LogLevelInfo LogLevelWarn LogLevelError
`Logger`	`sdk.WithLogger(logger projectcore.Logger)`	设置API Client的日志器，默认日志输出到标准输出。开发者可通过实现下面的 Logger 接口，来设置自定义的日志器: `type Logger interface { Debug(context.Context, ...interface{}) Info(context.Context, ...interface{}) Warn(context.Context, ...interface{}) Error(context.Context, ...interface{}) }`
`LogReqAtDebug`	`sdk.WithLogReqAtDebug(printReqRespLog bool)`	设置是否开启 Http 请求参数和响应参数的日志打印开关；开启后，在 debug 模式下会打印 http 请求和响应的 headers,body 等信息。在排查问题时，开启该选项，有利于问题的排查。
`BaseUrl`	`sdk.WithOpenBaseUrl(baseUrl string)`	设置飞书项目域名，默认为https://project.feishu.cn
`AccessTokenType`	`sdk.WithAccessTokenType(accessTokenType projectcore.AccessTokenType)`	设置 plugin_token 类型，枚举值如下： AccessTokenTypePlugin（插件身份凭证） AccessTokenTypeVirtualPlugin（虚拟plugin_token） AccessTokenTypeUserPlugin（用户身份凭证）
`TokenCache`	`sdk.WithTokenCache(cache projectcore.Cache)`	设置 token 缓存器，用来缓存 token, 默认实现为内存。如开发者想要定制 token 缓存器，需实现下面 Cache 接口: `type Cache interface { Set(ctx context.Context, key string, value string, expireTime time.Duration) error Get(ctx context.Context, key string) (string, error) }`
`EnableTokenCache`	`sdk.WithEnableTokenCache(enableTokenCache bool)`	设置是否开启 Token 的自动获取与缓存。默认开启，如需要关闭可传递 false。
`ReqTimeout`	`sdk.WithReqTimeout(time time.Duration)`	设置 SDK 内置的 Http Client 的请求超时时间，默认为0代表永不超时。
`HttpClient`	`sdk.WithHttpClient(httpClient projectcore.HttpClient)`	设置 HttpClient，用于替换 SDK 提供的默认实现。开发者可通过实现下面的 HttpClient 接口来设置自定义的 HttpClient: `type HttpClient interface { Do(http.Request) (http.Response, error) }`

API调用

创建完毕 API Client，我们可以使用 Client.业务域.方法名称 来定位具体的 API 方法，然后对具体的 API 发起调用。

飞书项目开放平台开放的所有 API 列表，可点击这里查看

基本用法

如下示例我们通过 client 调用空间业务的 ListProjectWorkItemType 方法，获取空间下的工作项类型列表：

import (
	"context"
	"fmt"
	"net/http"

	sdk "github.com/larksuite/project-oapi-sdk-golang"
	sdkcore "github.com/larksuite/project-oapi-sdk-golang/core"
	"github.com/larksuite/project-oapi-sdk-golang/service/project"
)


func main() {
	// 创建 client
	client := sdk.NewClient("PluginID", "PluginSecret")

	// 发起请求
	resp, err := client.Project.ListProjectWorkItemType(context.Background(), project.NewListProjectWorkItemTypeReqBuilder().
		ProjectKey("project_key").
		Build(),
		sdkcore.WithUserKey("user_key"),
	)

	//处理错误
	if err != nil {
           // 处理err
           return
	}

	// 服务端错误处理
	if !resp.Success() {
           fmt.Println(resp.Code(), resp.ErrMsg, resp.RequestId())
	   return 
	}

	// 业务数据处理
	fmt.Println(sdkcore.Prettify(resp.Data))
}

更多 API 调用示例：./sample/demo.go

设置请求选项

开发者在每次发起 API 调用时，可以设置请求级别的一些参数，比如传递 UserPluginAccessToken ,自定义 Headers 等：

import (
"context"
"fmt"

sdk "github.com/larksuite/project-oapi-sdk-golang"
sdkcore "github.com/larksuite/project-oapi-sdk-golang/core"
"github.com/larksuite/project-oapi-sdk-golang/service/project"
)

func main() {
// 创建 client
client := sdk.NewClient("PluginID", "PluginSecret", sdk.WithAccessTokenType(sdkcore.AccessTokenTypeUserPlugin))
header := make(http.Header)
header.Add("k1", "v1")
// 发起请求
resp, err := client.Project.ListProjectWorkItemType(context.Background(), project.NewListProjectWorkItemTypeReqBuilder().
ProjectKey("project_key").
Build(),
sdkcore.WithAccessToken("user_plugin_token"), //设置用户身份凭证
sdkcore.WithHeaders(header), //设置head
)

//处理错误
if err != nil {
// 处理err
return
}

// 服务端错误处理
if !resp.Success() {
fmt.Println(resp.Code(), resp.ErrMsg, resp.RequestId())
return
}

// 业务数据处理
fmt.Println(sdkcore.Prettify(resp.Data))
}

如下表格，展示了所有请求级别可设置的选项：

配置选项	配置方式	描述
`Header`	`sdkcore.WithHeaders(header http.Header)`	设置自定义请求头，开发者可在发起请求时，这些请求头会被透传到飞书项目开放平台服务端。
`AccessToken`	`sdkcore.WithAccessToken(accessToken string)`	设置token，当开发者自己维护token 时（即创建Client时EnableTokenCache设置为了false），需通过该选项传递 token。
`UserKey`	`sdkcore.WithUserKey(userKey string)`	设置请求头X-USER-KEY，可以通过添加header的方式在请求头添加X-USER-KEY，或通过该方式便捷添加X-USER-KEY到请求头中。
`IdemUUID`	`sdkcore.WithIdemUUID(uuid string)`	设置请求头X-IDEM-UUID, 可以通过添加header的方式在请求头添加X-IDEM-UUID，或通过该方式便捷添加X-IDEM-UUID到请求头中。

错误自查

查看错误码

FAQ

project_key如何获取

飞书项目中双击空间名称，如下图所示

user_key如何获取

飞书项目左下角双击个人头像，如下图所示

Documentation ¶

Index ¶

type Client
- func NewClient(appId, appSecret string, options ...ClientOptionFunc) *Client
type ClientOptionFunc

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Client ¶

type Client struct {
	View            *view.ViewService                        // 视图
	Attachment      *attachment.AttachmentService            // 附件
	Field           *field.FieldService                      // 字段
	WorkItemConf    *workitem_conf.WorkItemConfService       // 工作项配置
	Chat            *chat.ChatService                        // 群组
	Comment         *comment.CommentService                  // 评论
	WorkItem        *workitem.WorkItemService                // 工作项
	User            *user.UserService                        // 用户
	Project         *project.ProjectService                  // 空间
	Task            *task.TaskService                        // 子任务
	RoleConf        *role_conf.RoleConfService               // 流程角色
	ProjectRelation *project_relation.ProjectRelationService // 空间关联
	Plugin          *plugin.PluginService                    // token
	Measure         *measure.MeasureService                  // 度量
	WbsViewDraft    *wbs_view_draft.WbsViewDraftService      // 计划表草稿
	// contains filtered or unexported fields
}

func NewClient ¶

func NewClient(appId, appSecret string, options ...ClientOptionFunc) *Client

type ClientOptionFunc ¶

type ClientOptionFunc func(config *core.Config)

func WithAccessTokenType ¶

func WithAccessTokenType(accessTokenType core.AccessTokenType) ClientOptionFunc

func WithEnableTokenCache ¶

func WithEnableTokenCache(enableTokenCache bool) ClientOptionFunc

func WithHeaders ¶

func WithHeaders(header http.Header) ClientOptionFunc

设置每次请求都会携带的 header

func WithHttpClient ¶

func WithHttpClient(httpClient core.HttpClient) ClientOptionFunc

func WithLogLevel ¶

func WithLogLevel(logLevel core.LogLevel) ClientOptionFunc

func WithLogReqAtDebug ¶

func WithLogReqAtDebug(printReqRespLog bool) ClientOptionFunc

func WithLogger ¶

func WithLogger(logger core.Logger) ClientOptionFunc

func WithOpenBaseUrl ¶

func WithOpenBaseUrl(baseUrl string) ClientOptionFunc

func WithReqTimeout ¶

func WithReqTimeout(reqTimeout time.Duration) ClientOptionFunc

func WithTokenCache ¶

func WithTokenCache(cache core.Cache) ClientOptionFunc

Source Files ¶

View all Source files

client.go

Directories ¶

Path	Synopsis
core
model
sample
service
attachment
chat
comment
common
field
measure
plugin
project
project_relation
role_conf
task
user
view
wbs_view_draft
workitem
workitem_conf

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

飞书项目开放接口SDK

目录

安装

API Client

创建API Client

配置API Client

API调用

基本用法

设置请求选项

错误自查

FAQ

project_key如何获取

user_key如何获取

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type Client ¶

func NewClient ¶

type ClientOptionFunc ¶

func WithAccessTokenType ¶

func WithEnableTokenCache ¶

func WithHeaders ¶

func WithHttpClient ¶

func WithLogLevel ¶

func WithLogReqAtDebug ¶

func WithLogger ¶

func WithOpenBaseUrl ¶

func WithReqTimeout ¶

func WithTokenCache ¶

Source Files ¶

Directories ¶