SA 会议系统：第三方日历集成 — 接口能力调研与选型

文档状态：V1.0 编写日期：2026-08-04 定位：飞书/钉钉会议室资源接口的能力调研，含分页、过滤、认证、返回字段对比与选型结论。面向后端开发，是《方案》与《架构与流程》的接口依据。

1. 背景与问题

项目楼约 200 间会议室（19 层），但飞书侧会议室资源是全集团范围（可能上千间）。
需求：只导入本项目楼的会议室。因此同步接口是否支持「按楼宇过滤」与「分页」是选型核心。
全部结论经 playwright 渲染官方文档页核实（本机 WebFetch/exa 被网络策略拦截，仅 playwright-cli 可行）。

2. 飞书：两代 API，能力差异大

飞书会议室资源接口存在两代，楼宇/过滤能力差异显著，是本次调研最重要的发现。

维度	旧版 `meeting_room-v1`（历史版本）	新版 `vc-v1`（当前主流）
会议室列表	`GET /open-apis/meeting_room/room/list`，按 `building_id` 过滤	`GET /open-apis/vc/v1/rooms`，仅按 `room_level_id` 过滤
分页上限	page_size 最大 1000	page_size 最大 100
楼宇接口	`GET /meeting_room/building/list`（返回建筑 + `floors`）	无（`vc-v1/building/list` 为死链）
返回字段	自带 `building_name`、`floor_name`、`is_disabled`	`path` 为层级 ID 数组（`omb_xxx`），需另查 room_levels 翻译
排序	`order_by`（name / floor_name）	无
权限	`calendar:room:readonly`	`vc:room:readonly`

2.1 选型推荐：meeting_room-v1

按项目楼圈定范围推荐旧版 meeting_room-v1，原因：

building_id 一步过滤到项目楼，无需遍历层级树；
page_size 最大 1000，200 间一页拉满，无需分页循环；
返回自带 floor_name（楼层匹配的关键输入）与 is_disabled（状态筛选）。

建筑下拉的数据来源：GET /meeting_room/building/list 返回建筑列表，每个建筑同时包含 ID 与名称（label）——下拉框显示 name、携带 building_id，选中后以 building_id 作为 room/list 的过滤条件。无需用户手填 ID。

开发时需核实（字段命名）：官方历史文档中建筑响应字段为 building_id，而官方 SDK 示例（api_meeting_room.py）的 fields 传的是 id。能力上"ID + 名称同一接口返回"是确定的，但真实接入时需用真实凭证调一次确认字段名（building_id 还是 id），并确认 name 字段即下拉框展示的 label。

虽然文档归类为「历史版本」，但能力反而最贴合楼宇场景，且仍在官方文档维护。若团队对使用历史版本有顾虑，可退化为 vc-v1 + 层级树两步过滤（见 2.2），但需分页循环与 level 翻译。

2.2 飞书「按项目楼拉取」链路

方案 A（推荐，meeting_room-v1）

GET /meeting_room/building/list                    → buildings[]（选项目楼拿 building_id）
GET /meeting_room/room/list?building_id=<项目楼>   → rooms[]（自带 floor_name / is_disabled）

方案 B（vc-v1 退化方案）

GET /vc/v1/room_levels                             → 层级树（定位项目楼的 room_level_id）
GET /vc/v1/rooms?room_level_id=<项目楼>            → rooms[]（path 是 level_id 数组，需翻译）
                                                    → 循环 page_token 直到 has_more=false（100/页）

2.3 忙闲/预定（两个版本共用）

创建日程 + 加会议室参与人：POST /calendar/v4/calendars/:calendar_id/events + POST .../attendees（type=resource，resource_id 填 room_id）
事件订阅：calendar.calendar_event.changed_v4，忙闲数据靠推送 + freebusy 增量对账

3. 钉钉：无楼宇过滤，弱筛选

3.1 查询会议室列表

项	官方值
URL	`GET https://api.dingtalk.com/v1.0/rooms/meetingRoomLists`
认证	Header `x-acs-dingtalk-access-token`
权限	视频会议信息读权限
分页	`nextToken`（游标）+ `maxResults`（默认 20，最大 100）
过滤	仅这三个参数，无楼宇/楼层过滤
必填	`unionId`（操作人 unionId，用户维度）

返回字段：roomId、roomStaffId、corpId、roomName、roomStatus（0全员/1仅管理员/2部分权限）、roomLabels（设备标签，枚举 1电视/2电话/3投影仪/4白板/5视频会议）、roomCapacity、roomLocation{title, desc}（自由文本位置）。

3.2 会议室分组（groups）：存在但不可用于过滤

GET /v1.0/rooms/groupLists?unionId= 返回树形分组（groupId/groupName/parentId，可模拟楼宇→楼层）。
创建/更新会议室时可指定 groupId。
但列表接口响应不展示 groupId，且不支持按分组过滤 → 只能拉全量后本地按分组关联，或靠 roomLocation 文本匹配。

3.3 预定 / 忙闲

预定：先建日程事件，再 POST /v1.0/calendar/users/{userId}/calendars/{calendarId}/events/{eventId}/meetingRooms 绑定会议室，一个日程最多 5 间。
忙闲：POST /v1.0/calendar/users/{userId}/meetingRooms/schedules/query，roomIds≤5、时间窗 ≤90天。

4. 平台能力对比与产品化结论

能力	飞书	钉钉	能否统一
分页	page_token（≤100/≤1000）	nextToken（≤100）	✅ 抽象为游标分页
楼宇/楼层过滤	✅ 结构化（building_id）	❌ 仅文本位置	❌ 无法统一
认证维度	企业 token（tenant_access_token）	用户 unionId	⚠️ 需适配
设备信息	device[].name	roomLabels（枚举）	✅ 统一为设备字典
位置/路径	结构化 path / floor_name	roomLocation 自由文本	⚠️ 需存原始值

产品化结论：UI 框架（选平台 → 认证 → 选范围 → 导入）可统一，但「选范围」一步必须平台特化：

飞书：建筑下拉（结构化过滤），体验完整。
钉钉：无结构化过滤，只能全量拉取 + 预览页搜索/筛选/勾选兜底，弱筛选。

若「只导项目楼」是硬需求，须明确：飞书体验完整，钉钉为弱筛选，需要用户手动圈定。

5. 官方文档（证据）

飞书

查询会议室列表（vc-v1）：https://open.feishu.cn/document/server-docs/vc-v1/room/list
查询层级列表（vc-v1）：https://open.feishu.cn/document/server-docs/vc-v1/room_level/list
获取会议室列表（meeting_room-v1，按建筑）：https://open.feishu.cn/document/server-docs/historic-version/meeting_room-v1/api-reference/obtain-meeting-room-list
查询建筑物详情（meeting_room-v1）：https://open.feishu.cn/document/server-docs/historic-version/meeting_room-v1/api-reference/query-building-details
查询会议室列表（meeting_room-v1）：https://open.feishu.cn/document/server-docs/historic-version/meeting_room-v1/api-reference/obtain-meeting-room-list
查询忙闲（calendar-v4）：https://open.feishu.cn/document/server-docs/calendar-v4/calendar/freebusy-list

钉钉

查询会议室列表：https://open.dingtalk.com/document/development/check-the-meeting-room-list
查询会议室分组信息：https://open.dingtalk.com/document/development/query-meeting-room-groups
获取会议室忙闲信息：https://open.dingtalk.com/document/development/queries-free-and-busy-meeting-room-information
预定会议室：https://open.dingtalk.com/document/development/add-a-meeting-room
调用频率限制：https://open.dingtalk.com/document/development/call-frequency-limit

第三方日历集成

访客预约

01-设计

02-知识库

设计方案

语料

03-场景与数据

01-调研

SA 会议系统：第三方日历集成 — 接口能力调研与选型

1. 背景与问题

2. 飞书：两代 API，能力差异大

2.1 选型推荐：meeting_room-v1

2.2 飞书「按项目楼拉取」链路

2.3 忙闲/预定（两个版本共用）

3. 钉钉：无楼宇过滤，弱筛选

3.1 查询会议室列表

3.2 会议室分组（groups）：存在但不可用于过滤

3.3 预定 / 忙闲

4. 平台能力对比与产品化结论

5. 官方文档（证据）

飞书

钉钉

6. 相关文档

设计方案

语料

SA 会议系统：第三方日历集成 — 接口能力调研与选型 ​

1. 背景与问题 ​

2. 飞书：两代 API，能力差异大 ​

2.1 选型推荐：meeting_room-v1 ​

2.2 飞书「按项目楼拉取」链路 ​

2.3 忙闲/预定（两个版本共用） ​

3. 钉钉：无楼宇过滤，弱筛选 ​

3.1 查询会议室列表 ​

3.2 会议室分组（groups）：存在但不可用于过滤 ​

3.3 预定 / 忙闲 ​

4. 平台能力对比与产品化结论 ​

5. 官方文档（证据） ​

飞书 ​

钉钉 ​

6. 相关文档 ​

SA 会议系统：第三方日历集成 — 接口能力调研与选型

1. 背景与问题

2. 飞书：两代 API，能力差异大

2.1 选型推荐：meeting_room-v1

2.2 飞书「按项目楼拉取」链路

2.3 忙闲/预定（两个版本共用）

3. 钉钉：无楼宇过滤，弱筛选

3.1 查询会议室列表

3.2 会议室分组（groups）：存在但不可用于过滤

3.3 预定 / 忙闲

4. 平台能力对比与产品化结论

5. 官方文档（证据）

飞书

钉钉

6. 相关文档