ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Zoom Docs API 端点全览与集成实战:基于 knowledge-work-plugins zoom-plugin rest-api 技能库的权威接口清单解析

Zoom Docs API 端点全览与集成实战:基于 knowledge-work-plugins zoom-plugin rest-api 技能库的权威接口清单解析 Zoom Docs API 端点全览与集成实战基于 knowledge-work-plugins zoom-plugin rest-api 技能库的权威接口清单解析【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本篇指南以 partner-built/zoom-plugin/skills/rest-api/references/zoom-docs.md 为核心骨架系统讲解 Zoom DocsZoom 文档REST API 的完整端点清单、六大功能标签、异步导入/导出流程与协作/访问控制配置方式。读完本文你将能够在后端服务中基于 Server-to-Server OAuth 完成 Zoom Docs 文件的创建、导入、导出、协作者管理与通用访问权限设置并知晓如何在仓库的 rest-api 技能库中快速定位与验证每一个端点。文档定位Zoom Docs 产品域的权威端点清单在 knowledge-work-plugins 仓库的 Zoom 插件体系中zoom-docs.md是一份特殊的参考文档它不是教程而是Zoom Docs 产品域的权威端点清单authoritative endpoint inventory。该文件镜像了 Zoom 官方 API Hub 中该产品域的 OpenAPI 文档结构直接对应官方 OpenAPI 文档的paths对象生成用于端点发现endpoint discovery与存量盘点inventory。整个 rest-api 技能库的设计原则是references/下的各域参考文件与官方 API Hub 的endpoints.json清单对齐作为「本地路径/方法发现的事实来源local source of truth」而可执行的业务流程编排模式则统一放在examples/目录中。这一点在原文档中有明确说明Use this file for endpoint discovery and inventory. Use../examples/for orchestration patterns, not as the canonical source of path names.翻译成实践建议即查端点、比对路径以本文件为准写业务流程以 examples 目录 中的编排范例为准不要在 examples 中把路径名当作权威来源。调用前置Base URL 与认证方式所有 Zoom Docs API 调用遵循 Zoom REST API v2 的通用约定Base URL 为https://api.zoom.us/v2认证细节可查阅仓库内的完整认证指南 references/authentication.md。对于后端自动化场景推荐使用Server-to-Server OAuth通过一次令牌请求获取有效期 1 小时的 access tokencurl -X POST https://zoom.us/oauth/token \ -H Authorization: Basic $(echo -n CLIENT_ID:CLIENT_SECRET | base64) \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeaccount_credentialsaccount_idACCOUNT_ID响应示例{ access_token: eyJhbGciOiJIUzI1NiJ9..., token_type: bearer, expires_in: 3600, scope: docs:write:import docs:read:export }申请应用所需的 Client ID / Client Secret / Account ID 等凭据以及标准化的.env键名约定参见 references/environment-variables.md涉及ZOOM_CLIENT_ID、ZOOM_CLIENT_SECRET、ZOOM_ACCOUNT_ID等。关于 Scope 的重要提醒原文档特别强调每个操作operation都定义了各自的 scope且 Zoom Docs 经常使用细粒度granular的 scope 名称。实现前务必在官方 API Hub 对应操作页面确认精确的 scope。仓库内已有两个经过验证的 Docs 相关 scopedocs:write:import—— 用于创建/导入 Zoom Docs 文档见 zoom-mcp 工具参考docs:read:export—— 用于读取/导出 Zoom Docs 文档内容同样见上述工具参考。这两者与下文 Import / Export 标签下的端点语义完全对应可作为申请权限时的起点。端点覆盖概览原文档给出的覆盖度统计如下指标数值端点操作Endpoint operations16路径模板Path templates11标签Tags6六个标签及其操作数分布标签操作数Collaborator协作者4Export导出2File Management文件管理5File Uploads文件上传1General Access通用访问2Import导入2文件管理File ManagementDocs 资源的 CRUD 核心该标签覆盖了 Zoom Docs 文件本身的生命周期管理共 5 个操作方法端点摘要操作 IDPOST/docs/files创建新文件CreateDocDELETE/docs/files/{fileId}删除文件DeleteFileGET/docs/files/{fileId}获取文件元数据QueryFileMetadataPATCH/docs/files/{fileId}修改文件元数据ModifyMetadataGET/docs/files/{fileId}/children列出文件的所有子项ListAllChildren这是整个 Docs API 的入口层。典型用法是先通过POST /docs/files创建一个空文档拿到fileId随后用PATCH /docs/files/{fileId}调整标题等元数据用GET /docs/files/{fileId}查询元数据用GET /docs/files/{fileId}/children遍历文档树Zoom Docs 支持层级结构文档可以挂在文件夹/父对象之下。不再需要时调用DELETE /docs/files/{fileId}清理。一个创建文件的请求示例curl -X POST https://api.zoom.us/v2/docs/files \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { name: Q1 Planning — Action Items }在仓库的 MCP 实践范例 zoom-mcp/examples/create-zoom-doc.md 中可以看到这一思路的落地通过create_file_with_content对应docs:write:importscope创建文档成功响应会返回file_id与file_link且支持可选的parent_id参数把新文档挂到指定文件夹或父对象之下——这与ListAllChildren所描述的层级关系一致。导入Import从外部内容批量生成 Docs方法端点摘要操作 IDPOST/docs/imports通过导入创建新文件CreateanewfilebyimportGET/docs/imports/{importId}/status获取文件导入状态GetdocsfileimportstatusImport 是「把既有内容Markdown、会议纪要、上传的文件等变成 Zoom Docs 文档」的主路径也是创建 Docs 最常用的方式之一对应docs:write:importscope。由于导入是异步操作其编排模式固定为两段式POST /docs/imports提交导入任务获得importId轮询GET /docs/imports/{importId}/status直到导入完成。# 步骤 1提交导入 curl -X POST https://api.zoom.us/v2/docs/imports \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { file_name: Q1 Planning Notes, content: # Q1 Planning\n\n- Owner: Alice\n- Deadline: 2026-03-31 } # 步骤 2轮询状态 curl https://api.zoom.us/v2/docs/imports/{importId}/status \ -H Authorization: Bearer ACCESS_TOKEN值得注意的是仓库中 MCP 层的create_file_with_content正是 Import 语义的实现将 Markdown 内容直接转换为 Zoom Docs 文档。这意味着业务上「把 Markdown 笔记变成 Zoom 文档」的需求底层走的就是 Import 这一组端点。导出Export异步获取文档内容方法端点摘要操作 IDPOST/docs/exports创建文件导出任务CreateafileexportGET/docs/exports/{exportId}/status获取文件导出状态GetfileexportstatusExport 与 Import 对称是读取 Docs 内容的异步通道对应docs:read:exportscope。同样遵循「提交任务 → 轮询状态」的两段式模式curl -X POST https://api.zoom.us/v2/docs/exports \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { file_id: {fileId} } curl https://api.zoom.us/v2/docs/exports/{exportId}/status \ -H Authorization: Bearer ACCESS_TOKEN从源码结构看MCP 层的get_file_content以 Markdown 形式检索 Docs 文档内容scope 为docs:read:export对应的正是 Export 这条链路。因此「把 Zoom 文档读出来转成 Markdown 给下游使用」的需求应路由到本组端点。文件上传File Uploads为导入与附件提供素材方法端点摘要操作 IDPOST/docs/file_uploads为 Docs 导入或附件创建文件上传Uploadfilefordocsimportorattachments该标签下唯一的端点是上传入口语义上服务于两种场景docs import 的源文件以及文档附件。它与 Import 端点协同先上传文件拿到可用的文件标识再通过/docs/imports以该文件为内容源创建文档。协作者Collaborator文档共享与权限管理方法端点摘要操作 IDGET/docs/files/{fileId}/collaborators列出文件的协作者ListCollaboratorsPOST/docs/files/{fileId}/collaborators为文件添加协作者AddCollaboratorsDELETE/docs/files/{fileId}/collaborators/{collaboratorId}从文件中移除协作者RemoveACollaboratorPATCH/docs/files/{fileId}/collaborators/{collaboratorId}修改协作者在文件上的角色ModifyCollaboratorRole协作者管理是对单个文件粒度的共享控制四个端点构成了完整的「查询 → 添加 → 改角色 → 移除」生命周期# 列出协作者 curl https://api.zoom.us/v2/docs/files/{fileId}/collaborators \ -H Authorization: Bearer ACCESS_TOKEN # 添加协作者 curl -X POST https://api.zoom.us/v2/docs/files/{fileId}/collaborators \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { collaborators: [ { email: colleagueexample.com, role: editor } ] } # 修改角色 curl -X PATCH https://api.zoom.us/v2/docs/files/{fileId}/collaborators/{collaboratorId} \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { role: viewer } # 移除协作者 curl -X DELETE https://api.zoom.us/v2/docs/files/{fileId}/collaborators/{collaboratorId} \ -H Authorization: Bearer ACCESS_TOKEN注意ModifyCollaboratorRole使用 PATCH部分更新这与 Zoom API 中「修改资源用 PATCH 传变更字段」的通用约定一致详见 concepts/api-architecture.md。通用访问General Access文件级共享开关方法端点摘要操作 IDGET/docs/files/{fileId}/general_access_setting获取文件的通用访问设置GetFileGeneralAccessPATCH/docs/files/{fileId}/general_access_setting修改文件的通用访问设置ModifyFileGeneralAccess如果说 Collaborator 控制的是「指定的人」General Access 控制的就是「默认情况下谁能访问」。通过GET读取当前通用访问设置通过PATCH调整例如在组织内共享、按链接共享等策略之间切换curl -X PATCH https://api.zoom.us/v2/docs/files/{fileId}/general_access_setting \ -H Authorization: Bearer ACCESS_TOKEN \ -H Content-Type: application/json \ -d { access_level: organization }在开放共享文档给团队时通常先用 General Access 打开基础可达性再用 Collaborator 组端点精确授予编辑/查看角色。典型业务编排一次完整的 Docs 自动化流程结合以上六大标签一个典型的后端自动化链路可以是导入POST /docs/imports提交内容或先POST /docs/file_uploads上传源文件轮询GET /docs/imports/{importId}/status直到成功拿到fileId共享POST /docs/files/{fileId}/collaborators添加协作者必要时PATCH /docs/files/{fileId}/general_access_setting调整默认访问策略维护GET /docs/files/{fileId}/children遍历层级、PATCH /docs/files/{fileId}更新元数据导出POST /docs/exports创建导出任务轮询GET /docs/exports/{exportId}/status获取文档内容供下游消费清理DELETE /docs/files/{fileId}删除不再需要的文档。编写此类编排代码时请以 examples 目录 中的完整范例为参考本文件仅用于端点发现与路径核对。同时注意 Zoom 通用 API 陷阱路径参数如fileId若包含/或//需要双重 URL 编码时间类参数遵循 ISO 8601UTC 以Z结尾限流是按账号而非按应用计算的详见 concepts/rate-limiting-strategy.md。与 rest-api 技能库的协作方式在仓库的 rest-api 技能体系中本文件references/zoom-docs.md承担的是「Docs 域端点事实源」角色与技能库其他组成部分配合使用入口与导航SKILL.md 提供整体速查、Base URL、快速开始与「按场景找文档」索引认证concepts/authentication-flows.md 与 references/authentication.md 覆盖 S2S / User OAuth / PKCE / Device Code 全部流程架构约定concepts/api-architecture.md 解释 Base URL、区域路由、me关键字、ID vs UUID 与时间格式MCP 落地zoom-mcp 工具参考 与 create-zoom-doc 范例 展示了 Docs 能力在 Agent 场景中的封装方式。使用注意事项Scope 精确性每个操作都有各自的细粒度 scope不要凭docs:read/docs:write之类的宽泛名称推断实现前务必核对官方 API Hub 对应操作页本文已验证的两个 scopedocs:write:import、docs:read:export仅覆盖导入/导出链路。异步操作必须轮询Import 与 Export 均为「提交 查状态」模式不要期望一次性同步返回内容。本文件是清单而非规范路径与方法以官方 OpenAPI 为准本文件是对其结构的本地镜像若发现清单与官方 API Hub 不一致应以官方为准并同步更新本文件。区分清单与编排端点发现用本文件业务流程参考 examples避免在编排代码中把本文件的路径当作出处引用。至此Zoom Docs API 的 16 个操作、11 个路径模板、6 大功能标签已全部覆盖。无论你是要构建「会议纪要 → Zoom 文档」的自动化流水线还是要在产品中嵌入文档协作与权限管理都可以把本清单作为开发与排障的起点。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表