飞书开放平台Go-Sdk使用指南

飞书开放平台提供了Go-Sdk，旨在让开发者便捷的调用飞书开放API、处理订阅的消息事件、处理服务端推送的卡片行为。

安装

go get -u github.com/larksuite/oapi-sdk-go/v3@v3.0.3

API Client

开发者在调用 API 前，需要先创建一个 API Client，然后才可以基于 API Client 发起 API 调用。

创建API Client

• 对于自建应用，可使用下面代码来创建一个 API Client

var client = lark.NewClient("appID", "appSecret") // 默认配置为自建应用

• 对于商店应用，需在创建 API Client 时，使用 lark.WithMarketplaceApp 方法指定 AppType 为商店应用

var client = lark.NewClient("appID", "appSecret",lark.WithMarketplaceApp()) // 设置App为商店应用

配置API Client

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

1.  
   var client = lark.NewClient("appID", "appSecret",
2.  
   lark.WithLogLevel(larkcore.LogLevelDebug),
3.  
   lark.WithReqTimeout(3*time.Second),
4.  
   lark.WithEnableTokenCache(true),
5.  
   lark.WithHelpdeskCredential("id", "token"),
6.  
   lark.WithHttpClient(http.DefaultClient))

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

API调用

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

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

基本用法

如下示例我们通过 client 调用文档业务的 Create 方法，创建一个文档：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
   "os"
6.  
    
7.  
   "github.com/larksuite/oapi-sdk-go/v3"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
9.  
   "github.com/larksuite/oapi-sdk-go/v3/service/docx/v1"
10.  
    )
11.  
     
12.  
     
13.  
    func main() {
14.  
    // 创建 client
15.  
    client := lark.NewClient("appID", "appSecret")
16.  
     
17.  
    // 发起请求
18.  
    resp, err := client.Docx.Document.Create(context.Background(), larkdocx.NewCreateDocumentReqBuilder().
19.  
    Body(larkdocx.NewCreateDocumentReqBodyBuilder().
20.  
    FolderToken("token").
21.  
    Title("title").
22.  
    Build()).
23.  
    Build())
24.  
     
25.  
    //处理错误
26.  
    if err != nil {
27.  
    // 处理err
28.  
    return
29.  
    }
30.  
     
31.  
    // 服务端错误处理
32.  
    if !resp.Success() {
33.  
    fmt.Println(resp.Code, resp.Msg, resp.RequestId())
34.  
    return
35.  
    }
36.  
     
37.  
    // 业务数据处理
38.  
    fmt.Println(larkcore.Prettify(resp.Data))
39.  
    }

更多 API 调用示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/api/im.go

设置请求选项

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

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
   "os"
6.  
    
7.  
   "github.com/larksuite/oapi-sdk-go/v3"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
9.  
   "github.com/larksuite/oapi-sdk-go/v3/service/docx/v1"
10.  
    )
11.  
     
12.  
    func main() {
13.  
    // 创建client
14.  
    client := lark.NewClient("appID", "appSecret")
15.  
     
16.  
    // 自定义请求headers
17.  
    header := make(http.Header)
18.  
    header.Add("k1", "v1")
19.  
    header.Add("k2", "v2")
20.  
     
21.  
    // 发起请求
22.  
    resp, err := client.Docx.Document.Create(context.Background(), larkdocx.NewCreateDocumentReqBuilder().
23.  
    Body(larkdocx.NewCreateDocumentReqBodyBuilder().
24.  
    FolderToken("token").
25.  
    Title("title").
26.  
    Build(),
27.  
    ).
28.  
    Build(),
29.  
    larkcore.WithHeaders(header), // 设置自定义headers
30.  
    )
31.  
     
32.  
    //处理错误
33.  
    if err != nil {
34.  
    // 处理err
35.  
    return
36.  
    }
37.  
     
38.  
    // 服务端错误处理
39.  
    if !resp.Success() {
40.  
    fmt.Println(resp.Code, resp.Msg, resp.RequestId())
41.  
    return
42.  
    }
43.  
     
44.  
    // 业务数据处理
45.  
    fmt.Println(larkcore.Prettify(resp.Data))
46.  
    }

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

原生API调用方式

有些老版本的开放接口，不能生成结构化的 API， 导致 SDK 内无法提供结构化的使用方式，这时可使用原生模式进行调用：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "os"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
8.  
   )
9.  
    
10.  
    func main() {
11.  
    // 创建 API Client
12.  
    var appID, appSecret = os.Getenv("APP_ID"), os.Getenv("APP_SECRET")
13.  
    var cli = lark.NewClient(appID, appSecret, lark.WithLogReqAtDebug(true), lark.WithLogLevel(larkcore.LogLevelDebug))
14.  
     
15.  
    // 发起请求
16.  
    resp, err := cli.Do(context.Background(),
17.  
    &larkcore.ApiReq{
18.  
    HttpMethod: http.MethodGet,
19.  
    ApiPath: "https://open.feishu.cn/open-apis/contact/v3/users/:user_id",
20.  
    Body: nil,
21.  
    QueryParams: larkcore.QueryParams{"user_id_type": []string{"open_id"}},
22.  
    PathParams: larkcore.PathParams{"user_id": "ou_c245b0a7dff2725cfa2fb104f8b48b9d"},
23.  
    SupportedAccessTokenTypes: []larkcore.AccessTokenType{larkcore.AccessTokenTypeUser},
24.  
    },
25.  
    larkcore.WithUserAccessToken("u-3Sr1oTO4V1FWxTFTFYuFCqhk2Vs4h5IbhMG00gmw0CXh"),
26.  
    )
27.  
     
28.  
    // 错误处理
29.  
    if err != nil {
30.  
    fmt.Println(err)
31.  
    return
32.  
    }
33.  
     
34.  
    // 获取请求 ID
35.  
    fmt.Println(resp.RequestId())
36.  
     
37.  
    // 处理请求结果
38.  
    fmt.Println(resp.StatusCode) // http status code
39.  
    fmt.Println(resp.Header) // http header
40.  
    fmt.Println(string(resp.RawBody)) // http body
41.  
    }

更多 API 调用示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/api/api.go

处理消息事件回调

关于消息订阅相关的知识，可以点击这里查看

飞书开放平台开放的所有事件列表，可点击这里查看

基本用法

开发者订阅消息事件后，可以使用下面代码，对飞书开放平台推送的消息事件进行处理，如下代码基于 go-sdk 原生 http server 启动一个 httpServer：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/event"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
9.  
   "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext"
10.  
    "github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
11.  
    "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
12.  
    )
13.  
     
14.  
    func main() {
15.  
    // 注册消息处理器
16.  
    handler := dispatcher.NewEventDispatcher("verificationToken", "eventEncryptKey").OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
17.  
    // 处理消息 event，这里简单打印消息的内容
18.  
    fmt.Println(larkcore.Prettify(event))
19.  
    fmt.Println(event.RequestId())
20.  
    return nil
21.  
    }).OnP2MessageReadV1(func(ctx context.Context, event *larkim.P2MessageReadV1) error {
22.  
    // 处理消息 event，这里简单打印消息的内容
23.  
    fmt.Println(larkcore.Prettify(event))
24.  
    fmt.Println(event.RequestId())
25.  
    return nil
26.  
    })
27.  
     
28.  
    // 注册 http 路由
29.  
    http.HandleFunc("/webhook/event", httpserverext.NewEventHandlerFunc(handler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
30.  
     
31.  
    // 启动 http 服务
32.  
    err := http.ListenAndServe(":9999", nil)
33.  
    if err != nil {
34.  
    panic(err)
35.  
    }
36.  
    }

其中 NewEventDispatcher 方法的参数用于签名验证和消息解密使用，默认可以传递为空串；但是如果开发者的应用在 控制台 的【事件订阅】里面开启了加密，则必须传递控制台上提供的值。

需要注意的是注册处理器时，比如使用 OnP2MessageReceiveV1 注册接受消息事件回调时，其中的P2为消息协议版本，当前飞书开放平台存在 两种消息协议 ，分别为1.0和2.0。

如下图开发者在注册消息处理器时，需从 事件列表 中查看自己需要的是哪种协议的事件。如果是1.0的消息协议，则注册处理器时，需要找以OnP1xxxx开头的。如果是2.0的消息协议，则注册处理器时，需要找以OnP2xxxx开头的。

更多事件订阅示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/event/event.go

消息处理器内给对应租户发消息

针对 ISV 开发者，如果想在消息处理器内给对应租户的用户发送消息，则需先从消息事件内获取租户 key,然后使用下面方式调用消息 API 进行消息发送：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/event"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
9.  
   "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext"
10.  
    "github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
11.  
    "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
12.  
    )
13.  
     
14.  
    func main() {
15.  
    // 注册消息处理器
16.  
    handler := dispatcher.NewEventDispatcher("verificationToken", "eventEncryptKey").OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
17.  
    // 处理消息 event，这里简单打印消息的内容
18.  
    fmt.Println(larkcore.Prettify(event))
19.  
    fmt.Println(event.RequestId())
20.  
     
21.  
    // 获取租户 key 并发送消息
22.  
    tenanKey := event.TenantKey()
23.  
     
24.  
    // ISV 给指定租户发送消息
25.  
    resp, err := client.Im.Message.Create(context.Background(), larkim.NewCreateMessageReqBuilder().
26.  
    ReceiveIdType(larkim.ReceiveIdTypeOpenId).
27.  
    Body(larkim.NewCreateMessageReqBodyBuilder().
28.  
    MsgType(larkim.MsgTypePost).
29.  
    ReceiveId("ou_c245b0a7dff2725cfa2fb104f8b48b9d").
30.  
    Content("text").
31.  
    Build(), larkcore.WithTenantKey(tenanKey)).
32.  
    Build())
33.  
     
34.  
    // 发送结果处理，resp,err
35.  
     
36.  
    return nil
37.  
    })
38.  
     
39.  
    // 注册 http 路由
40.  
    http.HandleFunc("/webhook/event", httpserverext.NewEventHandlerFunc(handler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
41.  
     
42.  
    // 启动 http 服务
43.  
    err := http.ListenAndServe(":9999", nil)
44.  
    if err != nil {
45.  
    panic(err)
46.  
    }
47.  
    }

更多事件订阅示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/event/event.go

集成Gin框架

如果开发者当前应用使用的是 Gin Web 框架，并且不想要使用 Go-Sdk 提供的原生的 Http Server，则可使用下面方式，把当前应用的 Gin 服务与 SDK进行集成。

要想把 SDK 集成已有 Gin 框架，开发者需要引入集成包 oapi-sdk-gin

安装集成包

go get -u github.com/larksuite/oapi-sdk-gin

集成示例

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
    
5.  
   "github.com/gin-gonic/gin"
6.  
   "github.com/larksuite/oapi-sdk-gin"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/card"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
9.  
   "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
10.  
    "github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
11.  
    "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
12.  
    )
13.  
     
14.  
    func main() {
15.  
    // 注册消息处理器
16.  
    handler := dispatcher.NewEventDispatcher("verificationToken", "eventEncryptKey").OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
17.  
    fmt.Println(larkcore.Prettify(event))
18.  
    fmt.Println(event.RequestId())
19.  
    return nil
20.  
    }).OnP2MessageReadV1(func(ctx context.Context, event *larkim.P2MessageReadV1) error {
21.  
    fmt.Println(larkcore.Prettify(event))
22.  
    fmt.Println(event.RequestId())
23.  
    return nil
24.  
    }).OnP2UserCreatedV3(func(ctx context.Context, event *larkcontact.P2UserCreatedV3) error {
25.  
    fmt.Println(larkcore.Prettify(event))
26.  
    fmt.Println(event.RequestId())
27.  
    return nil
28.  
    })
29.  
     
30.  
    ...
31.  
     
32.  
    // 在已有 Gin 实例上注册消息处理路由
33.  
    gin.POST("/webhook/event", sdkginext.NewEventHandlerFunc(handler))
34.  
    }

处理卡片行为回调

关于卡片行为相关的知识，可点击这里查看

基本用法

开发者配置消息卡片回调地址后，可以使用下面代码，对飞书开放平台推送的卡片行为进行处理，如下代码基于go-sdk原生http server启动一个httpServer：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3/card"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext"
9.  
   )
10.  
     
11.  
    func main() {
12.  
    // 创建 card 处理器
13.  
    cardHandler := larkcard.NewCardActionHandler("v", "", func(ctx context.Context, cardAction *larkcard.CardAction) (interface{}, error) {
14.  
    // 处理 cardAction, 这里简单打印卡片内容
15.  
    fmt.Println(larkcore.Prettify(cardAction))
16.  
    fmt.Println(cardAction.RequestId())
17.  
    // 无返回值示例
18.  
    return nil, nil
19.  
    })
20.  
     
21.  
    // 注册处理器
22.  
    http.HandleFunc("/webhook/card", httpserverext.NewCardActionHandlerFunc(cardHandler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
23.  
     
24.  
    // 启动 http 服务
25.  
    err := http.ListenAndServe(":9999", nil)
26.  
    if err != nil {
27.  
    panic(err)
28.  
    }
29.  
    }

如上示例，如果不需要处理器内返回业务结果给飞书服务端，则直接使用这种无返回值用法

更多卡片行为处理示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/card/card.go

返回卡片消息

如开发者需要卡片处理器内同步返回用于更新消息卡片的消息体，则可使用下面方法方式进行处理：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3/card"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext"
9.  
   )
10.  
     
11.  
    func main() {
12.  
    // 创建card处理器
13.  
    cardHandler := larkcard.NewCardActionHandler("v", "", func(ctx context.Context, cardAction *larkcard.CardAction) (interface{}, error) {
14.  
    fmt.Println(larkcore.Prettify(cardAction))
15.  
    fmt.Println(cardAction.RequestId())
16.  
     
17.  
    // 创建卡片信息
18.  
    messageCard := larkcard.NewMessageCard().
19.  
    Config(config).
20.  
    Header(header).
21.  
    Elements([]larkcard.MessageCardElement{divElement, processPersonElement}).
22.  
    CardLink(cardLink).
23.  
    Build()
24.  
     
25.  
    return messageCard, nil
26.  
    })
27.  
     
28.  
    // 注册处理器
29.  
    http.HandleFunc("/webhook/card", httpserverext.NewCardActionHandlerFunc(cardHandler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
30.  
     
31.  
    // 启动http服务
32.  
    err := http.ListenAndServe(":9999", nil)
33.  
    if err != nil {
34.  
    panic(err)
35.  
    }
36.  
    }

更多卡片行为处理示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/card/card.go

返回自定义消息

如开发者需卡片处理器内返回自定义内容，则可以使用下面方式进行处理：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3/card"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext"
9.  
   )
10.  
     
11.  
    func main() {
12.  
    // 创建 card 处理器
13.  
    cardHandler := larkcard.NewCardActionHandler("v", "", func(ctx context.Context, cardAction *larkcard.CardAction) (interface{}, error) {
14.  
    fmt.Println(larkcore.Prettify(cardAction))
15.  
    fmt.Println(cardAction.RequestId())
16.  
     
17.  
    // 创建 http body
18.  
    body := make(map[string]interface{})
19.  
    body["content"] = "hello"
20.  
     
21.  
    i18n := make(map[string]string)
22.  
    i18n["zh_cn"] = "你好"
23.  
    i18n["en_us"] = "hello"
24.  
    i18n["ja_jp"] = "こんにちは"
25.  
    body["i18n"] = i18n
26.  
     
27.  
    // 创建自定义消息：http状态码，body内容
28.  
    resp := &larkcard.CustomResp{
29.  
    StatusCode: 400,
30.  
    Body: body,
31.  
    }
32.  
     
33.  
    return resp, nil
34.  
    })
35.  
     
36.  
    // 注册处理器
37.  
    http.HandleFunc("/webhook/card", httpserverext.NewCardActionHandlerFunc(cardHandler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
38.  
     
39.  
    // 启动 http 服务
40.  
    err := http.ListenAndServe(":9999", nil)
41.  
    if err != nil {
42.  
    panic(err)
43.  
    }
44.  
    }

更多卡片行为处理示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/card/card.go

卡片行为处理器内给对应租户发消息

针对 ISV 开发者，如果想在卡片行为处理器内给对应租户的用户发送消息，则需先从卡片行为内获取租户 key ,然后使用下面方式调用消息 API 进行消息发送：

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
   "net/http"
5.  
    
6.  
   "github.com/larksuite/oapi-sdk-go/v3/card"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext"
9.  
   )
10.  
     
11.  
    func main() {
12.  
    // 创建 card 处理器
13.  
    cardHandler := larkcard.NewCardActionHandler("v", "", func(ctx context.Context, cardAction *larkcard.CardAction) (interface{}, error) {
14.  
     
15.  
    // 处理 cardAction, 这里简单打印卡片内容
16.  
    fmt.Println(larkcore.Prettify(cardAction))
17.  
    fmt.Println(cardAction.RequestId())
18.  
     
19.  
    // 获取租户 key 并发送消息
20.  
    tenanKey := cardAction.TenantKey
21.  
     
22.  
    // ISV 给指定租户发送消息
23.  
    resp, err := client.Im.Message.Create(context.Background(), larkim.NewCreateMessageReqBuilder().
24.  
    ReceiveIdType(larkim.ReceiveIdTypeOpenId).
25.  
    Body(larkim.NewCreateMessageReqBodyBuilder().
26.  
    MsgType(larkim.MsgTypePost).
27.  
    ReceiveId("ou_c245b0a7dff2725cfa2fb104f8b48b9d").
28.  
    Content("text").
29.  
    Build(), larkcore.WithTenantKey(tenanKey)).
30.  
    Build())
31.  
     
32.  
    // 发送结果处理，resp,err
33.  
     
34.  
    return nil, nil
35.  
    })
36.  
     
37.  
    // 注册处理器
38.  
    http.HandleFunc("/webhook/card", httpserverext.NewCardActionHandlerFunc(cardHandler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
39.  
     
40.  
    // 启动 http 服务
41.  
    err := http.ListenAndServe(":9999", nil)
42.  
    if err != nil {
43.  
    panic(err)
44.  
    }
45.  
    }

更多卡片行为处理示例：https://github.com/larksuite/oapi-sdk-go/tree/v3_main/sample/api/card/card.go

集成gin框架

如果开发者当前应用使用的是 Gin Web 框架，并且不想要使用 Go-Sdk 提供的原生的 Http Server，则可使用下面方式，把当前应用的 Gin 服务与 SDK进行集成。

要想把 SDK 集成已有 Gin 框架，开发者需要引入集成包 oapi-sdk-gin

安装集成包

go get -u github.com/larksuite/oapi-sdk-gin

集成示例

1.  
   import (
2.  
   "context"
3.  
   "fmt"
4.  
    
5.  
   "github.com/gin-gonic/gin"
6.  
   "github.com/larksuite/oapi-sdk-gin"
7.  
   "github.com/larksuite/oapi-sdk-go/v3/card"
8.  
   "github.com/larksuite/oapi-sdk-go/v3/core"
9.  
   )
10.  
     
11.  
     
12.  
    func main() {
13.  
    // 创建 card 处理器
14.  
    cardHandler := larkcard.NewCardActionHandler("v", "", func(ctx context.Context, cardAction *larkcard.CardAction) (interface{}, error) {
15.  
    fmt.Println(larkcore.Prettify(cardAction))
16.  
    fmt.Println(cardAction.RequestId())
17.  
     
18.  
    return nil, nil
19.  
    })
20.  
    ...
21.  
    // 在已有的 Gin 实例上注册卡片处理路由
22.  
    gin.POST("/webhook/card", sdkginext.NewCardActionHandlerFunc(cardHandler))
23.  
    ...
24.  
    }

GitHub地址

https://github.com/larksuite/oapi-sdk-go