使用 API

公告

站点迁移啦~！

为什么迁移?

作为由我们官方维护的组件库，分散在各自的文档站点中的确有好处：它们可以各自维护自己所需的东西、互不干扰。

但是缺点也很明显：太过分散。

组件库与核心库之间的关系是比较紧密的，我们希望你能够在一个站点内就可以查阅或搜索到所有你想要得知的信息。

适用场景

当你不确定自己的应用场景是否应该选择直接使用 API 模块时，这里为你提供了一些参考：

适用

你的应用只需要一个 API 实现库，你希望使用更原始的风格调用API。
你的应用不需要、或希望自行处理对事件的订阅与解析。（包括一切工作，例如建立网络连接）

不适用

你希望库实现事件订阅能力，可以替你处理网络连接、事件调度等。
你希望有一个 Bot 实现，它可以管理网络连接的生命周期、可以注册事件处理逻辑、替你接收事件，并进行处理。

安装

implementation("love.forte.simbot.component:simbot-component-kook-api:4.0.0-beta4")

implementation 'love.forte.simbot.component:simbot-component-kook-api:4.0.0-beta4'

<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <!-- Maven 需要添加 `-jvm` 后缀来选择使用 JVM 平台 -->
    <artifactId>simbot-component-kook-api-jvm</artifactId>
    <version>4.0.0-beta4</version>
</dependency>

引擎选择

Ktor引擎: 你可以前往 Ktor文档处选择一个对应所用平台下合适的 Client Engine。这里会根据不同平台提供几个示例，你可以选择其他可用目标。

CIO 是一个比较通用的引擎。在不知道选什么的情况下，可以考虑使用它。
runtimeOnly("io.ktor:ktor-client-cio-jvm:$ktor_version")
runtimeOnly 'io.ktor:ktor-client-cio-jvm:$ktor_version'
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

如果你打算使用 Java11+，也可以选择 Java 引擎。

runtimeOnly("io.ktor:ktor-client-java:$ktor_version")

如果你想要显式配置引擎，那么就不能使用 runtimeOnly 了。
runtimeOnly 'io.ktor:ktor-client-java:$ktor_version'

如果你想要显式配置引擎，那么就不能使用 runtimeOnly 了。
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

如果你想要显式配置引擎，那么就不能使用 runtime scope 了。

JavaScript 平台下可以选择 Js 引擎。
implementation("io.ktor:ktor-client-js:$ktor_version")
implementation 'io.ktor:ktor-client-js:$ktor_version'

native 平台目标下，可能需要根据不同的平台类型选择不同的引擎。

可以选择 WinHttp 引擎。
implementation("io.ktor:ktor-client-winhttp:$ktor_version")
implementation 'io.ktor:ktor-client-winhttp:$ktor_version'

Linux 下依旧可以选择 CIO 引擎。
implementation("io.ktor:ktor-client-cio:$ktor_version")
implementation 'io.ktor:ktor-client-cio:$ktor_version'

可以选择 Darwin 引擎。
implementation("io.ktor:ktor-client-darwin:$ktor_version")
implementation 'io.ktor:ktor-client-darwin:$ktor_version'

使用

KOOK组件的API模块提供了针对 KOOK API 的基本对应封装。

API封装的命名与API具有一定关联，例如获取当前用户加入的服务器列表：

GET /api/v3/guild/list

love.forte.simbot.kook.api.guild.GetGuildListApi

API的应用大差不差，因此此处仅使用部分类型作为示例，不会演示所有API。如果想浏览或寻找需要的 API，可前往 API定义列表或 APIDoc引导中进入KOOK组件的 KDoc 查阅，也可以简单的借助IDE的智能提示进行寻找。

此处仅以获取当前用户加入的服务器列表为例。

// 准备参数
// 用于请求的 authorization，參考 [[[KOOK开发者文档|https://developer.kookapp.cn/doc/reference]]]
val authorization = "Bot 1111222233334444"
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：[[[Ktor Engines|https://ktor.io/docs/http-client-engines.html]]]
val client = HttpClient()

// 使用 GetGuildListApi 获取频道列表
// 创建了一个参数 page = 1, pageSize = 20 的 GetGuildListApi，并使用上述准备好的参数进行请求。
val api = GetGuildListApi.create(page = 1, pageSize = 20)
val resultList = api.requestData(client, authorization)

resultList.forEach { // it: SimpleGuild
    ...
}

也可以通过额外的扩展函数来获得一个全量数据的数据流。

// 准备参数
// 用于请求的 authorization，參考 [[[KOOK开发者文档|https://developer.kookapp.cn/doc/reference]]]
val authorization = "Bot 1111222233334444"
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：[[[Ktor Engines|https://ktor.io/docs/http-client-engines.html]]]
val client = HttpClient()

// 使用 GetGuildListApi 获取频道列表
// 创建了一个基于 GetGuildListApi 获取全量数据的流，并使用上述准备好的参数进行请求。
val resultFlow = GetGuildListApi.createItemFlow { page ->
    create(page = page, pageSize = 20).requestData(client, authorization)
}
resultFlow.collect { // it: SimpleGuild
    println(it)
}

// 准备参数
// 用于请求的 authorization，參考 [[[KOOK开发者文档|https://developer.kookapp.cn/doc/reference]]]
var authorization = "Bot 1111222233334444";
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：https://ktor.io/docs/http-client-engines.html
var client = HttpClientJvmKt.HttpClient(($1) -> Unit.INSTANCE);
// 或者通过jvm平台库提供的工具类来构建一个默认的 client。（需要环境中存在一种引擎）
var newClient = ApiRequests.createHttpClient();

// 使用 GetGuildListApi 获取频道列表,
// 创建了一个 page = 1, pageSize = 20 的 GetGuildListApi
var api = GetGuildListApi.create(1, 20);

ApiRequests.requestDataAsync(api, client, authorization)
        .thenAccept(guildList -> {
            for (var guild : guildList) {
                // ...
            }
        });

// 准备参数
// 用于请求的 authorization，參考 [[[KOOK开发者文档|https://developer.kookapp.cn/doc/reference]]]
var authorization = "Bot 1111222233334444";
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：https://ktor.io/docs/http-client-engines.html
var client = HttpClientJvmKt.HttpClient(($1) -> Unit.INSTANCE);
// 或者通过jvm平台库提供的工具类来构建一个默认的 client。（需要环境中存在一种引擎）
var newClient = ApiRequests.createHttpClient();

// 使用 GetGuildListApi 获取频道列表,
// 创建了一个 page = 1, pageSize = 20 的 GetGuildListApi
var api = GetGuildListApi.create(1, 20);

// 发起请求并得到结果
var guildList = ApiRequests.requestDataBlocking(api, client, authorization);

for (var guild : guildList) {
    // ...
}

// 准备参数
// 用于请求的 authorization，參考 [[[KOOK开发者文档|https://developer.kookapp.cn/doc/reference]]]
var authorization = "Bot 1111222233334444";
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：https://ktor.io/docs/http-client-engines.html
var client = HttpClientJvmKt.HttpClient(($1) -> Unit.INSTANCE);
// 或者通过jvm平台库提供的工具类来构建一个默认的 client。（需要环境中存在一种引擎）
var newClient = ApiRequests.createHttpClient();

// 使用 GetGuildListApi 获取频道列表,
// 创建了一个 page = 1, pageSize = 20 的 GetGuildListApi
var api = GetBotGuildListApi.create(1. 20);

// 发起请求并得到结果
ApiRequests.requestDataReserve(api, client, authorization)
        // 使用此转化器需要确保运行时环境中存在 
        // [[[kotlinx-coroutines-reactor|https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive]]] 的相关依赖。
        .transform(SuspendReserves.mono())
        .subscribe(guildList -> {
            for (var guild : guildList) {
                // ...
            }
        });

Last modified: 07 August 2024