使用 API 模块

公告

站点迁移啦~！

为什么迁移?

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

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

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

适用场景

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

适用

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

不适用

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

安装

implementation("love.forte.simbot.component:simbot-component-qq-guild-api:4.0.0-beta5")

implementation 'love.forte.simbot.component:simbot-component-qq-guild-api:4.0.0-beta5'

<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <!-- Maven 需要添加 `-jvm` 后缀来选择使用 JVM 平台 -->
    <artifactId>simbot-component-qq-guild-api-jvm</artifactId>
    <version>4.0.0-beta5</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'

使用

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

API封装的命名与API具有一定关联，例如 获取用户（BOT）频道服务器列表：

GET /users/@me/guilds

love.forte.simbot.qguild.api.user.GetBotGuildListApi

API的应用大差不差，因此此处仅使用部分类型作为示例，不会演示所有API。

以获取用户（BOT）频道服务器列表为例。

    // 准备参数
// 用于请求的token
val token = "Bot 123456789.ABABABABABABABABABABABABABABABABAB"
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：[[[Ktor Engines|https://ktor.io/docs/http-client-engines.html]]]
val client = HttpClient()
// 需要请求的环境的服务器地址，比如正式环境或沙箱环境，亦或是某个自己定义代理的第三方环境
// 可以通过 QQGuild 得到一些预定义的常量信息
val server = QQGuild.SANDBOX_URL

// 使用 GetBotGuildListApi 获取频道列表
// 创建了一个参数 limit=100 的 GetBotGuildListApi，并使用上述准备好的参数进行请求。
val resultList = GetBotGuildListApi.create(limit = 100).requestData(client, token, server)

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

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

// 准备参数
// 用于请求的token
val token = "Bot 123456789.ABABABABABABABABABABABABABABABABAB"
// 用于请求的 Ktor HttpClient，如有必要则需要自行引入并选择需要使用的引擎。
// 参考：[[[Ktor Engines|https://ktor.io/docs/http-client-engines.html]]]
val client = HttpClient()
// 需要请求的环境的服务器地址，比如正式环境或沙箱环境，亦或是某个自己定义代理的第三方环境
// 可以通过 QQGuild 得到一些预定义的常量信息
val server = QQGuild.SANDBOX_URL

// 使用 GetBotGuildListApi 获取频道列表
// 创建了一个基于 GetBotGuildListApi 获取全量数据的流，并使用上述准备好的参数进行请求。
val resultFlow = GetBotGuildListApi.createFlow { requestData(client, token, server) }

resultFlow.collect { // it: SimpleGuild
    println(it)
}

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

// 需要请求的环境的服务器地址，比如正式环境或沙箱环境，亦或是某个自己定义代理的第三方环境
// 可以通过 QQGuild 得到一些预定义的常量信息
var server = QQGuild.SANDBOX_URL;

// 使用 GetBotGuildListApi 获取频道列表,
// 创建了一个 limit = 100 的 GetBotGuildListApi
var api = GetBotGuildListApi.create(100);

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

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

// 需要请求的环境的服务器地址，比如正式环境或沙箱环境，亦或是某个自己定义代理的第三方环境
// 可以通过 QQGuild 得到一些预定义的常量信息
var server = QQGuild.SANDBOX_URL;

// 使用 GetBotGuildListApi 获取频道列表,
// 创建了一个 limit = 100 的 GetBotGuildListApi
var api = GetBotGuildListApi.create(100);

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

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

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

// 需要请求的环境的服务器地址，比如正式环境或沙箱环境，亦或是某个自己定义代理的第三方环境
// 可以通过 QQGuild 得到一些预定义的常量信息
var server = QQGuild.SANDBOX_URL;

// 使用 GetBotGuildListApi 获取频道列表,
// 创建了一个 limit = 100 的 GetBotGuildListApi
var api = GetBotGuildListApi.create(100);

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

Last modified: 15 July 2024