BotRS

简体中文

English

简体中文

English

主题

机器人 API 参考 ​

BotApi 是用于与 QQ 频道 REST API 交互的核心客户端。它提供了完整的 API 端点访问，支持消息发送、频道管理、成员操作等所有功能。

概述 ​

rust
pub struct BotApi {
    http_client: HttpClient,
}

BotApi 封装了所有 QQ 频道机器人 API 端点，提供类型安全的接口和自动的错误处理。所有方法都是异步的，支持高并发操作。

构造函数 ​

new ​

创建新的 BotApi 实例。

rust
pub fn new() -> Self

返回值 ​

返回新的 BotApi 实例，使用默认的 HTTP 客户端配置。

示例 ​

rust
use botrs::BotApi;

let api = BotApi::new();

with_http_client ​

使用自定义 HTTP 客户端创建 BotApi 实例。

rust
pub fn with_http_client(http_client: HttpClient) -> Self

参数 ​

  • http_client: 自定义的 HTTP 客户端

示例 ​

rust
use botrs::{BotApi, HttpClient};
use std::time::Duration;

let http_client = HttpClient::builder()
    .timeout(Duration::from_secs(30))
    .build()?;

let api = BotApi::with_http_client(http_client);

消息 API ​

post_message ​

发送消息到指定频道（旧版 API）。

rust
pub async fn post_message(
    &self,
    token: &Token,
    channel_id: &str,
    content: Option<&str>,
    embed: Option<&Embed>,
) -> Result<Message, BotError>

参数 ​

  • token: 身份验证令牌
  • channel_id: 目标频道 ID
  • content: 消息文本内容（可选）
  • embed: 嵌入内容（可选）

返回值 ​

返回发送成功的消息对象或错误。

示例 ​

rust
let message = api.post_message(
    &token,
    "channel_123",
    Some("你好，世界！"),
    None
).await?;

post_message_with_params ​

使用结构化参数发送消息（推荐）。

rust
pub async fn post_message_with_params(
    &self,
    token: &Token,
    channel_id: &str,
    params: MessageParams,
) -> Result<Message, BotError>

参数 ​

  • token: 身份验证令牌
  • channel_id: 目标频道 ID
  • params: 消息参数结构体

示例 ​

rust
use botrs::{MessageParams, Embed};

// 发送文本消息
let params = MessageParams::new_text("Hello, World!");
let message = api.post_message_with_params(&token, "channel_123", params).await?;

// 发送嵌入消息
let embed = Embed::new()
    .title("标题")
    .description("描述")
    .color(0x3498db);
let params = MessageParams::new_embed(embed);
let message = api.post_message_with_params(&token, "channel_123", params).await?;

// 发送回复消息
let params = MessageParams::new_text("这是回复")
    .with_reply("original_message_id");
let message = api.post_message_with_params(&token, "channel_123", params).await?;

post_message_with_file ​

发送带文件的消息。

rust
pub async fn post_message_with_file(
    &self,
    token: &Token,
    channel_id: &str,
    filename: &str,
    file_data: &[u8],
    file_type: &str,
) -> Result<Message, BotError>

参数 ​

  • token: 身份验证令牌
  • channel_id: 目标频道 ID
  • filename: 文件名
  • file_data: 文件数据
  • file_type: 文件类型（如 "image", "video", "audio"）

示例 ​

rust
let file_data = std::fs::read("image.png")?;
let message = api.post_message_with_file(
    &token,
    "channel_123",
    "image.png",
    &file_data,
    "image"
).await?;

get_message ​

获取指定消息。

rust
pub async fn get_message(
    &self,
    token: &Token,
    channel_id: &str,
    message_id: &str,
) -> Result<Message, BotError>

delete_message ​

删除指定消息。

rust
pub async fn delete_message(
    &self,
    token: &Token,
    channel_id: &str,
    message_id: &str,
    hidetip: Option<bool>,
) -> Result<(), BotError>

频道管理 API ​

get_guild ​

获取频道信息。

rust
pub async fn get_guild(
    &self,
    token: &Token,
    guild_id: &str,
) -> Result<Guild, BotError>

示例 ​

rust
let guild = api.get_guild(&token, "guild_123").await?;
println!("频道名称: {}", guild.name.unwrap_or_default());

get_guild_channels ​

获取频道的子频道列表。

rust
pub async fn get_guild_channels(
    &self,
    token: &Token,
    guild_id: &str,
) -> Result<Vec<Channel>, BotError>

示例 ​

rust
let channels = api.get_guild_channels(&token, "guild_123").await?;
for channel in channels {
    println!("子频道: {} ({})", 
             channel.name.unwrap_or_default(), 
             channel.id);
}

get_channel ​

获取指定子频道信息。

rust
pub async fn get_channel(
    &self,
    token: &Token,
    channel_id: &str,
) -> Result<Channel, BotError>

create_guild_channel ​

创建新的子频道。

rust
pub async fn create_guild_channel(
    &self,
    token: &Token,
    guild_id: &str,
    channel_data: &serde_json::Value,
) -> Result<Channel, BotError>

示例 ​

rust
use serde_json::json;

let channel_data = json!({
    "name": "新子频道",
    "type": 0,  // 文本频道
    "sub_type": 0,  // 聊天频道
    "position": 1
});

let channel = api.create_guild_channel(&token, "guild_123", &channel_data).await?;

modify_guild_channel ​

修改子频道信息。

rust
pub async fn modify_guild_channel(
    &self,
    token: &Token,
    channel_id: &str,
    channel_data: &serde_json::Value,
) -> Result<Channel, BotError>

delete_guild_channel ​

删除子频道。

rust
pub async fn delete_guild_channel(
    &self,
    token: &Token,
    channel_id: &str,
) -> Result<(), BotError>

成员管理 API ​

get_guild_members ​

获取频道成员列表。

rust
pub async fn get_guild_members(
    &self,
    token: &Token,
    guild_id: &str,
    after: Option<&str>,
    limit: Option<u32>,
) -> Result<Vec<Member>, BotError>

参数 ​

  • after: 分页参数，获取此 ID 之后的成员
  • limit: 返回成员数量限制（最大 400）

示例 ​

rust
// 获取前100个成员
let members = api.get_guild_members(&token, "guild_123", None, Some(100)).await?;

// 分页获取
let first_batch = api.get_guild_members(&token, "guild_123", None, Some(400)).await?;
if let Some(last_member) = first_batch.last() {
    let second_batch = api.get_guild_members(
        &token, 
        "guild_123", 
        Some(&last_member.user.id), 
        Some(400)
    ).await?;
}

get_guild_member ​

获取指定成员信息。

rust
pub async fn get_guild_member(
    &self,
    token: &Token,
    guild_id: &str,
    user_id: &str,
) -> Result<Member, BotError>

add_guild_member_role ​

为成员添加身份组。

rust
pub async fn add_guild_member_role(
    &self,
    token: &Token,
    guild_id: &str,
    user_id: &str,
    role_id: &str,
) -> Result<(), BotError>

remove_guild_member_role ​

移除成员的身份组。

rust
pub async fn remove_guild_member_role(
    &self,
    token: &Token,
    guild_id: &str,
    user_id: &str,
    role_id: &str,
) -> Result<(), BotError>

create_guild_member_mute ​

禁言频道成员。

rust
pub async fn create_guild_member_mute(
    &self,
    token: &Token,
    guild_id: &str,
    user_id: &str,
    mute_data: &serde_json::Value,
) -> Result<(), BotError>

示例 ​

rust
use serde_json::json;

// 禁言10分钟
let mute_data = json!({
    "mute_end_timestamp": (chrono::Utc::now() + chrono::Duration::minutes(10)).timestamp().to_string(),
    "mute_seconds": 600
});

api.create_guild_member_mute(&token, "guild_123", "user_456", &mute_data).await?;

私信 API ​

create_direct_message_session ​

创建私信会话。

rust
pub async fn create_direct_message_session(
    &self,
    token: &Token,
    guild_id: &str,
    user_id: &str,
) -> Result<DirectMessageSession, BotError>

post_direct_message_with_params ​

发送私信消息。

rust
pub async fn post_direct_message_with_params(
    &self,
    token: &Token,
    guild_id: &str,
    channel_id: &str,
    params: MessageParams,
) -> Result<DirectMessage, BotError>

示例 ​

rust
// 创建私信会话
let session = api.create_direct_message_session(&token, "guild_123", "user_456").await?;

// 发送私信
let params = MessageParams::new_text("这是一条私信");
let dm = api.post_direct_message_with_params(
    &token,
    "guild_123",
    &session.channel_id,
    params
).await?;

get_direct_messages ​

获取私信历史。

rust
pub async fn get_direct_messages(
    &self,
    token: &Token,
    guild_id: &str,
    channel_id: &str,
    limit: Option<u32>,
) -> Result<Vec<DirectMessage>, BotError>

群组消息 API ​

post_group_message_with_params ​

发送群组消息。

rust
pub async fn post_group_message_with_params(
    &self,
    token: &Token,
    group_id: &str,
    params: MessageParams,
) -> Result<GroupMessage, BotError>

post_c2c_message_with_params ​

发送 C2C（用户对用户）消息。

rust
pub async fn post_c2c_message_with_params(
    &self,
    token: &Token,
    user_id: &str,
    params: MessageParams,
) -> Result<C2CMessage, BotError>

公告 API ​

create_guild_announce ​

创建频道公告。

rust
pub async fn create_guild_announce(
    &self,
    token: &Token,
    guild_id: &str,
    announce_data: &serde_json::Value,
) -> Result<Announce, BotError>

示例 ​

rust
use serde_json::json;

let announce_data = json!({
    "message": "重要通知：系统维护将在今晚进行",
    "channel_id": "channel_123"
});

let announce = api.create_guild_announce(&token, "guild_123", &announce_data).await?;

delete_guild_announce ​

删除频道公告。

rust
pub async fn delete_guild_announce(
    &self,
    token: &Token,
    guild_id: &str,
    announce_id: &str,
) -> Result<(), BotError>

表情回应 API ​

put_message_reaction ​

为消息添加表情回应。

rust
pub async fn put_message_reaction(
    &self,
    token: &Token,
    channel_id: &str,
    message_id: &str,
    emoji: &str,
) -> Result<(), BotError>

示例 ​

rust
// 添加点赞表情
api.put_message_reaction(&token, "channel_123", "message_456", "👍").await?;

delete_message_reaction ​

删除消息的表情回应。

rust
pub async fn delete_message_reaction(
    &self,
    token: &Token,
    channel_id: &str,
    message_id: &str,
    emoji: &str,
) -> Result<(), BotError>

get_message_reaction_users ​

获取对消息添加特定表情的用户列表。

rust
pub async fn get_message_reaction_users(
    &self,
    token: &Token,
    channel_id: &str,
    message_id: &str,
    emoji: &str,
    cookie: Option<&str>,
    limit: Option<u32>,
) -> Result<ReactionUsers, BotError>

身份组 API ​

get_guild_roles ​

获取频道身份组列表。

rust
pub async fn get_guild_roles(
    &self,
    token: &Token,
    guild_id: &str,
) -> Result<GuildRoles, BotError>

create_guild_role ​

创建频道身份组。

rust
pub async fn create_guild_role(
    &self,
    token: &Token,
    guild_id: &str,
    role_data: &serde_json::Value,
) -> Result<GuildRole, BotError>

modify_guild_role ​

修改频道身份组。

rust
pub async fn modify_guild_role(
    &self,
    token: &Token,
    guild_id: &str,
    role_id: &str,
    role_data: &serde_json::Value,
) -> Result<GuildRole, BotError>

delete_guild_role ​

删除频道身份组。

rust
pub async fn delete_guild_role(
    &self,
    token: &Token,
    guild_id: &str,
    role_id: &str,
) -> Result<(), BotError>

音频 API ​

get_channel_audio_members ​

获取音频频道成员列表。

rust
pub async fn get_channel_audio_members(
    &self,
    token: &Token,
    channel_id: &str,
) -> Result<Vec<Member>, BotError>

audio_control ​

控制音频播放。

rust
pub async fn audio_control(
    &self,
    token: &Token,
    channel_id: &str,
    control_data: &serde_json::Value,
) -> Result<AudioControl, BotError>

日程 API ​

get_guild_schedules ​

获取频道日程列表。

rust
pub async fn get_guild_schedules(
    &self,
    token: &Token,
    guild_id: &str,
    since: Option<u64>,
) -> Result<Vec<Schedule>, BotError>

get_guild_schedule ​

获取指定日程信息。

rust
pub async fn get_guild_schedule(
    &self,
    token: &Token,
    guild_id: &str,
    schedule_id: &str,
) -> Result<Schedule, BotError>

create_guild_schedule ​

创建频道日程。

rust
pub async fn create_guild_schedule(
    &self,
    token: &Token,
    guild_id: &str,
    schedule_data: &serde_json::Value,
) -> Result<Schedule, BotError>

modify_guild_schedule ​

修改频道日程。

rust
pub async fn modify_guild_schedule(
    &self,
    token: &Token,
    guild_id: &str,
    schedule_id: &str,
    schedule_data: &serde_json::Value,
) -> Result<Schedule, BotError>

delete_guild_schedule ​

删除频道日程。

rust
pub async fn delete_guild_schedule(
    &self,
    token: &Token,
    guild_id: &str,
    schedule_id: &str,
) -> Result<(), BotError>

论坛 API ​

get_threads ​

获取论坛帖子列表。

rust
pub async fn get_threads(
    &self,
    token: &Token,
    channel_id: &str,
) -> Result<Vec<Thread>, BotError>

get_thread ​

获取指定论坛帖子信息。

rust
pub async fn get_thread(
    &self,
    token: &Token,
    channel_id: &str,
    thread_id: &str,
) -> Result<ThreadInfo, BotError>

create_thread ​

创建论坛帖子。

rust
pub async fn create_thread(
    &self,
    token: &Token,
    channel_id: &str,
    thread_data: &serde_json::Value,
) -> Result<OpenThread, BotError>

delete_thread ​

删除论坛帖子。

rust
pub async fn delete_thread(
    &self,
    token: &Token,
    channel_id: &str,
    thread_id: &str,
) -> Result<(), BotError>

权限 API ​

get_guild_api_permission ​

获取频道 API 权限。

rust
pub async fn get_guild_api_permission(
    &self,
    token: &Token,
    guild_id: &str,
) -> Result<ApiPermission, BotError>

post_guild_api_permission_demand ​

申请频道 API 权限。

rust
pub async fn post_guild_api_permission_demand(
    &self,
    token: &Token,
    guild_id: &str,
    permission_data: &serde_json::Value,
) -> Result<ApiPermissionDemand, BotError>

错误处理 ​

所有 API 方法都返回 Result<T, BotError>，其中 BotError 包含详细的错误信息：

rust
use botrs::BotError;

match api.get_guild(&token, "invalid_guild_id").await {
    Ok(guild) => println!("获取频道成功: {}", guild.id),
    Err(BotError::NotFound) => eprintln!("频道不存在"),
    Err(BotError::Forbidden) => eprintln!("权限不足"),
    Err(BotError::RateLimited(retry_after)) => {
        eprintln!("速率限制，{}秒后重试", retry_after);
    }
    Err(BotError::Authentication(_)) => eprintln!("身份验证失败"),
    Err(BotError::Network(_)) => eprintln!("网络连接错误"),
    Err(e) => eprintln!("其他错误: {}", e),
}

批量操作示例 ​

批量获取频道信息 ​

rust
use futures::future::try_join_all;

async fn get_multiple_guilds(
    api: &BotApi,
    token: &Token,
    guild_ids: &[String]
) -> Result<Vec<Guild>, BotError> {
    let futures: Vec<_> = guild_ids.iter()
        .map(|id| api.get_guild(token, id))
        .collect();
    
    try_join_all(futures).await
}

批量发送消息 ​

rust
async fn broadcast_message(
    api: &BotApi,
    token: &Token,
    channel_ids: &[String],
    content: &str
) -> Result<Vec<Message>, BotError> {
    let mut results = Vec::new();
    
    for channel_id in channel_ids {
        let params = MessageParams::new_text(content);
        match api.post_message_with_params(token, channel_id, params).await {
            Ok(message) => results.push(message),
            Err(e) => eprintln!("发送到频道 {} 失败: {}", channel_id, e),
        }
        
        // 避免速率限制
        tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
    }
    
    Ok(results)
}

最佳实践 ​

  1. 错误处理: 始终处理可能的 API 错误
  2. 速率限制: 在批量操作中添加适当的延迟
  3. 重试机制: 对临时错误实现自动重试
  4. 参数验证: 在调用 API 前验证输入参数
  5. 日志记录: 记录重要的 API 调用和错误

另请参阅 ​

基于 MIT 许可证发布

Copyright © 2024 YinMo19