sdk

飞书项目开放接口SDK

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

目录

• 安装

• API Client

  • 创建API Client
  • 配置API Client

• API调用

  • 基本用法
  • 设置请求选项

• 错误自查

• FAQ

安装

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))

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

type Logger interface {
Debug(context.Context, ...interface{})
Info(context.Context, ...interface{})
Warn(context.Context, ...interface{})
Error(context.Context, ...interface{})
}

type Cache interface {
Set(ctx context.Context, key string, value string, expireTime time.Duration) error
Get(ctx context.Context, key string) (string, error)
}

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))
}

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

错误自查

查看错误码

FAQ

project_key如何获取

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

user_key如何获取

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