联机大厅开发文档站

主题

v2 版接口指南 ​

基岩版联机大厅 API v2 文档
基础域名：https://api.miaaoo.com
请求头：Content-Type: application/json

目录 ​

1. 概述 ​

1.1 基础信息 ​

项目说明
基础 URLhttps://api.miaaoo.com
请求头Content-Type: application/json
响应格式JSON
成功状态码2xx
错误状态码4xx、5xx

1.2 Nginx 映射对照 ​

接口对外路径
房间列表GET /v2/list
加入房间POST /v2/join
账号信息GET /v2/account
刷新粉丝GET /refreshFollowers

2. /v2/list（获取房间列表） ​

2.1 请求方式 ​

GET https://api.miaaoo.com/v2/list

2.2 请求参数 ​

参数位置类型必需说明
langQuerystring否按世界名称语言筛选。传单个值（?lang=zh）或传多个值（?lang=zh&lang=en）。不传时返回全部房间。

2.3 成功响应（HTTP 200） ​

json
{
  "results": [
    {
      "sessionRef": {
        "name": "00000000-0000-0000-0000-000000000000"
      },
      "ownerXuid": "2535408433750813",
      "createTime": "2025-01-01T02:06:09.1234569Z",
      "id": "00000000-0000-0000-0000-000000000000",
      "customProperties": {
        "hostName": "Steven",
        "ownerId": "2535408433750813",
        "version": "1.21.69",
        "worldName": "My World",
        "worldType": "Survival",
        "protocol": 0,
        "MemberCount": 1,
        "MaxMemberCount": 30,
        "BroadcastSetting": 3,
        "isEditorWorld": false,
        "isHardcore": false,
        "RealmId": "",
        "worldNameLang": "zh"
      },
      "relatedInfo": {
        "maxMembersCount": 30,
        "membersCount": 1
      },
      "roomfrom": "6"
    }
  ]
}

字段说明 ​

字段类型说明
sessionRef.namestring会话 UUID，用于 /v2/join 的 sessionname 参数
ownerXuidstringhandle创建者 XUID
createTimestring创建时间（ISO 8601 UTC）
idstringhandle ID，用于 /v2/join 的 handleid 参数
customProperties.hostNamestring房主名称（纯英文，≤16 字符）
customProperties.ownerIdstring房主 XUID（16 位数字字符串）
customProperties.versionstring游戏版本号（如 1.21.113）
customProperties.worldNamestring世界名称
customProperties.worldTypestring游戏模式：Survival / Creative / Spectator
customProperties.MemberCountnumber游戏内当前玩家数
customProperties.MaxMemberCountnumber游戏内最大玩家数
customProperties.BroadcastSettingnumber广播设置：3=好友的好友（可加入）2=仅好友 1=仅邀请
customProperties.isEditorWorldboolean是否为编辑器世界
customProperties.isHardcoreboolean是否为极限模式
customProperties.worldNameLangstring世界名称的语言代码（如 zh、en），由后端语言检测服务自动识别
relatedInfo.maxMembersCountnumberXbox会话最大成员数
relatedInfo.membersCountnumberXbox会话当前成员数
roomfromstring房间来源的账号 ID，用于 /v2/join 的 roomfrom 参数

2.4 错误响应 ​

HTTP 500 - Redis 无数据

json
{
  "status": "500",
  "code": 1,
  "message": "No data found for redis.",
  "message_zh_CN": "未在redis找到数据。"
}

HTTP 500 - 数据格式异常

json
{
  "status": "500",
  "code": 2,
  "message": "Invalid data format.",
  "message_zh_CN": "Redis数据格式异常。"
}

HTTP 500 - Redis 读取错误

json
{
  "status": "500",
  "code": 2,
  "message": "Error fetching data from Redis.",
  "message_zh_CN": "从Redis获取数据时出错。"
}

2.5 请求示例 ​

bash
# 获取全部房间
curl https://api.miaaoo.com/v2/list

# 筛选中文房间
curl https://api.miaaoo.com/v2/list?lang=zh

# 筛选中文和英文房间
curl https://api.miaaoo.com/v2/list?lang=zh&lang=en

2.6 注意事项 ​

  • 数据每 30 秒 由后端定时任务刷新一次，存入 Redis 后 TTL 为 60 秒。
  • BroadcastSetting 为 3 的房间才能被外部玩家加入。

3. /v2/join（加入房间） ​

3.1 请求方式 ​

POST https://api.miaaoo.com/v2/join

3.2 协议版本 ​

v2 支持两种协议版本：

  • 旧版协议（version: "1.0.0"）：向后兼容，内部透传至旧后端处理
  • 新版协议（apiversion: 2）：推荐使用，拥有完整的权限校验和自动化流程

3.3 新版协议（apiversion=2，推荐） ​

请求体 ​

json
{
  "apiversion": 2,
  "joininformation": {
    "addid": "6",
    "roomfrom": "6",
    "handleid": "00000000-0000-0000-0000-000000000000",
    "sessionname": "00000000-0000-0000-0000-000000000000",
    "userxuid": "2535408433750813"
  }
}

字段说明 ​

字段类型必需说明
apiversionnumber是固定为 2
joininformation.addidstring是发起者已添加哪个账号就输入那个账号在/v2/account中的 ID
joininformation.roomfromstring是房间数据来源的账号 ID（如 "6"），取自 /v2/list 的 roomfrom
joininformation.handleidstring是目标会话的 handle ID，取自 /v2/list 的 id 字段
joininformation.sessionnamestring是目标会话名称，取自 /v2/list 的 sessionRef.name
joininformation.userxuidstring是发起加入玩家的 16 位 XUID，v2 协议中为必需项

3.4 旧版协议（version: "1.0.0"，向后兼容） ​

请求体 ​

json
{
  "version": "1.0.0",
  "joininformation": {
    "addid": "6",
    "roomfrom": "6",
    "roomid": "00000000-0000-0000-0000-000000000000",
    "sessionname": "00000000-0000-0000-0000-000000000000"
  },
  "invitecontrol": {
    "userxuid": "2535408433750813"
  }
}

注意：旧版协议的 roomid 字段对应 /list 中的 id，新版协议的 handleid 也对应同一字段。只是字段名不同，值相同。

差异 ​

项目旧版协议新版协议
版本字段version: "1.0.0"apiversion: 2
userxuid可选（缺失仍可成功）必需（缺失返回 400）
权限校验仅参数格式校验校验 followers + people
处理方式透传至旧后端本后端直接处理
roomid 字段名roomidhandleid
支持ID=8的账号不支持支持

3.5 响应说明 ​

新版协议成功（HTTP 200） ​

json
{
  "status": "200",
  "code": "1",
  "message": "Success.",
  "message_zh_CN": "成功。"
}

新版协议错误码 ​

HTTP 状态码code说明
4001缺少 joininformation 或参数不完整
4002addid 或 roomfrom 不允许
4003userxuid 缺失或格式非法（非 16 位数字）
4034userxuid 不在任何 followers 缓存中
4040查询 addid 的会话句柄无结果
5xx0加入流程中 XBL 操作失败
xxx5自动添加关注失败

旧版协议响应 ​

条件HTTP 状态码code说明
成功且邀请已发送200"2"userxuid 有效且邀请成功
成功但无邀请200"1"userxuid 缺失或非法
参数无效4001缺少必需参数
addid 类型错误4002addid/roomid 为 number 类型
发送邀请失败400undefinedXbox 邀请接口返回错误
会话不存在404undefined多人游戏可能未开启
加入会话失败500undefinedPUT session 失败
服务器错误500undefined内部错误

3.6 请求示例 ​

bash
curl -X POST https://api.miaaoo.com/v2/join \
  -H "Content-Type: application/json" \
  -d '{
    "apiversion": 2,
    "joininformation": {
      "addid": "8",
      "roomfrom": "8",
      "handleid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sessionname": "00000000-0000-0000-0000-000000000000",
      "userxuid": "1234567890123456"
    }
  }'

3.7 注意事项 ​

  • addid 和 handleid 必须为字符串类型，不要以数字类型发送。
  • 新版协议中 userxuid 是必需项，且必须是 16 位纯数字。
  • 后端会自动将 userxuid 添加到对应账号的关注列表（若尚未关注），以便 Xbox 的"好友的好友"机制生效。所以请用户注意自己账号的粉丝数量不要达到1000上限，以及不要在隐私设置中关闭“允许他人关注我”。

4. /v2/account（获取账号信息） ​

4.1 请求方式 ​

GET https://api.miaaoo.com/v2/account

4.2 请求参数 ​

无。

4.3 成功响应（HTTP 200） ​

json
[
  {
    "id": "8",
    "name": "MCLobby26",
    "canaddfriends": true
  }
]

字段说明 ​

字段类型说明
idstring账号数字 ID，用于 /v2/join 的 addid
namestringXbox Gamertag
canaddfriendsboolean是否可在Xbox关注或在Minecraft中加好友（true 表示可）

canaddfriends字段命名是为了兼容已有前端的解析，故导致现在看起来意思有点不一样了，以前确实可以在Xbox加好友，但现在后端改了一些机制，从粉丝中获取房间数据。

4.4 错误 ​

正常情况下不会出现错误响应。

4.5 请求示例 ​

bash
curl https://api.miaaoo.com/v2/account

5. /refreshFollowers（刷新粉丝缓存） ​

5.1 请求方式 ​

GET https://api.miaaoo.com/refreshFollowers

5.2 请求参数 ​

无。

5.3 功能说明 ​

手动触发后端拉取指定 Xbox 账号的 followers（粉丝）列表，并刷新本地缓存。

5.4 响应状态码 ​

由于后端设计仍有缺陷，请求后请无视响应代码。

状态码条件说明
200至少有一个账号重新拉取了 followers刷新成功
206所有账号的缓存都在 10 秒内，无需刷新已是最新
502至少有一个账号拉取失败部分失败
500服务器内部错误异常错误

5.5 全局限流 ​

由于后端设计仍有缺陷，请求后请无视响应代码。 在 10 秒内 重复调用此接口，后续请求直接返回 206，不会触发真实的 Xbox API 调用。

5.6 请求示例 ​

bash
curl https://api.miaaoo.com/refreshFollowers

5.7 注意事项 ​

  • 调用此接口不会立即更新房间列表，需要等下次定时任务（每 30 秒）执行后才会体现在 /v2/list 中。
  • 后端同时有定时任务每 5 分钟则自动刷新，手动调用主要用于调试或即时更新场景。
  • 由于后端设计仍有缺陷，请求后请无视响应代码。

6. 附录：响应码速查 ​

全局状态码 ​

状态码含义通常原因
200成功请求处理完成
206无需处理缓存未过期或限流跳过
400请求参数错误缺少参数、参数格式非法、类型错误
403权限不足userxuid 不在 followers 中
404未找到会话不存在、用户未找到
500服务器内部错误Redis 异常、XBL API 错误、代码异常
502上游服务错误refresh 时部分账号拉取失败

/v2/join 错误码对照 ​

code含义
0通用内部错误或 XBL 操作失败
1参数不完整或缺失
2addid / roomfrom 不允许
3userxuid 缺失或格式错误
4userxuid 不在 followers 中
5自动添加关注失败

文档版本：v2.0.0 · 最后更新：2026-06-02

MIT License

Copyright © 2025 mc-miaaoo-docs