第 20 章 OpenAPI 客户端
本章面向平台管理员与集成对接负责人。所有操作都在「OpenAPI 客户端」页完成，菜单路径：左侧菜单「OpenAPI 客户端」，路由
/#/gb28181/openapi-client。 本章涉及密钥与授权，属高危配置：每一个破坏性操作都给出确认框原文与影响面，请逐条对照后再点。
20.1 功能说明
OpenAPI 客户端是给第三方系统发的一张「门禁卡」。第三方不必使用本平台的账号密码，而是拿一对密钥（AK/SK）调用平台开放出去的能力，例如查询设备列表、查询通道状态、按需点播。
平台对这张卡设了三道约束，缺一不可：
| 约束 | 在哪配 | 作用 |
|---|---|---|
| 数据范围 | 新建客户端时选定，之后不可改 | 决定这个客户端能看到哪个部门的设备（本部门／本部门及以下） |
| 能力授权 | 详情页「能力授权」逐项开关 | 决定这个客户端能调用哪些接口；新建后默认为空，必须显式授权 |
| 调用与观看限制 | 新建客户端时设定 | 每秒调用次数、突发容量、同时观看路数，防止第三方把平台打满 |
三者是与关系：数据范围管「哪批设备」，能力授权管「哪些动作」，限速配额管「多快、多少路」。任何一项为「无」，对应请求就会被拒。
注意 - 本页只管「客户端凭据与授权」，不负责网络可达性、证书、防火墙。第三方连不上时先确认网络与地址，再回来看本章。 - AK 是公开标识，可以出现在日志里；SK 是密码，只能展示一次，平台不保存明文，遗失只能轮换（见 20.5）。
20.2 页面结构
OpenAPI 功能由一个列表页 + 一个详情页 + 三个弹窗组成。
| 界面 | 打开方式 | 用途 |
|---|---|---|
| 客户端列表 | 左侧菜单「OpenAPI 客户端」 | 检索、新建、对单个客户端做凭据与状态管理 |
| 客户端概览弹窗 | 列表行操作「概览」 | 只读查看一个客户端的全部登记信息 |
| 新建客户端弹窗 | 列表右上「新建客户端」 | 登记名称、归属部门、数据范围、限制、负责人 |
| 一次性密钥弹窗 | 创建成功／轮换成功后自动弹出 | 唯一一次显示 SK 的窗口 |
| 客户端详情页 | 行操作「配置能力」「调用记录」 | 能力授权、调用记录两块内容 |
列表页自上而下：检索区 → 表格 → 分页。检索区左侧三个筛选控件，右侧「查询」「重置」，最右一组是「刷新」与「新建客户端」。
界面如图 20-1 所示。
图 20-1 OpenAPI 客户端列表
20.3 检索
| 控件 | 类型 | 说明 |
|---|---|---|
| 「归属部门」 | 部门树选择，可清空、可搜索 | 选中某个部门后只显示归属该部门的客户端 |
| 「客户端名称」 | 文本框，可清空 | 按名称过滤 |
| 「客户端状态」 | 下拉，选项：启用／停用／已撤销 | 按认证状态过滤 |
| 按钮 | 点了会怎样 |
|---|---|
| 「查询」 | 回到第 1 页，带上当前三个条件重新取数；结果为空时表格显示「暂无 OpenAPI 客户端」 |
| 「重置」 | 清空三个条件并回到第 1 页重新取数 |
| 「刷新」（圆形箭头图标，悬浮提示「刷新 OpenAPI 客户端」） | 保持当前条件与页码，只重新取一次数。用于别人刚改过数据时同步 |
回车键在「客户端名称」框内等同点击「查询」。
20.4 表格列
| 列 | 内容 | 读法 |
|---|---|---|
| 「客户端」 | 第一行客户端名称，第二行灰色等宽字体的 AK | AK 是给对接方核对身份用的，不是密码 |
| 「归属部门与数据范围」 | 部门名称 + 一个小标签（「本部门」或「本部门及以下」） | 这个客户端能摸到的设备边界 |
| 「负责人」 | 第一行「组织 / 公司名称」，第二行「姓名 · 联系方式」 | 未填组织名显示 -；只填了联系方式时姓名位显示「未填写姓名」 |
| 「调用 / 观看限制」 | 第一行「{每秒次数} / 秒 · 突发 {次数}」，第二行「观看 {路数} 路并发」 | 与新建时填的一致 |
| 「认证状态」 | 彩色标签「启用」（绿）／「停用」（橙）／「已撤销」（红） | 决定这个客户端此刻能不能认证 |
| 「密钥版本」 | 整数 | 每轮换一次 SK 加 1。对接方报「密钥失效」时，用这个数字快速确认是不是我方轮换过 |
| 「操作」 | 7 个动作，按状态显示其中一部分 | 见 20.5 |
分页在表格下方，可切换每页条数；翻页会保留当前筛选条件。
20.5 行操作
行操作从左到右固定为「概览」「配置能力」「调用记录」，其后三个是状态相关动作，按当前状态出现：
| 动作 | 何时出现 | 点了会怎样 |
|---|---|---|
| 「概览」（眼睛图标） | 始终出现 | 打开「客户端概览」弹窗，只读展示 12 项登记信息 |
| 「配置能力」（盾牌勾图标） | 始终出现 | 跳到详情页的能力授权区域 |
| 「调用记录」（卷轴图标） | 始终出现 | 跳到详情页的调用记录区域 |
| 「轮换 SK」（钥匙图标） | 状态不是「已撤销」时出现 | 先弹确认框，确认后作废旧 SK 并弹一次性密钥窗 |
| 「停用」（盾牌关闭图标） | 状态为「启用」时出现 | 先弹确认框，确认后立即阻断新请求 |
| 「启用」（圆形勾图标） | 状态为「停用」时出现 | 先弹确认框，确认后恢复认证 |
| 「撤销」（禁止图标） | 状态不是「已撤销」时出现 | 先弹确认框，确认后进入不可恢复状态 |
各动作的二次确认原文与结果提示：
| 动作 | 确认框标题 | 确认框正文 | 确认按钮 | 成功提示 |
|---|---|---|---|---|
| 轮换 SK | 「轮换 OpenAPI 客户端 SK」 | 「轮换会立即使旧 SK 失效，新的 SK 只展示一次。确认继续吗？」 | 「确认轮换 SK」 | 「SK 已轮换，请安全保存新的密钥」 |
| 停用 | 「停用 OpenAPI 客户端」 | 「停用会立即阻止新请求；观看连接清退由服务端异步处理。」 | 「确认停用」（危险色） | 「客户端认证已停用，清退进度另行确认」 |
| 启用 | 「启用 OpenAPI 客户端」 | 「启用不会恢复旧的播放授权，请确认客户端仍属于有效部门。」 | 「确认启用」 | 「客户端已启用」 |
| 撤销 | 「撤销 OpenAPI 客户端」 | 「撤销不可恢复，认证会立即失败；观看连接清退需以服务端进度确认，不会自动误伤其他客户端。」 | 「确认撤销」（危险色） | 「客户端已撤销，清退进度另行确认」 |
注意 - 轮换 SK 是立即失效：确认的一瞬间旧 SK 就不能用了。若对接方正在跑批处理任务，先约好切换窗口再点。 - 停用不等于断开正在看的视频。停用只拦「新请求」，已经建立的观看连接由服务端异步清退，因此出现「已停用但仍能看到画面几十秒」属正常。 - 撤销不可逆。撤销后该行不再出现「轮换 SK」「停用」「撤销」，只剩「概览」「配置能力」「调用记录」。如确需继续使用，只能按 20.7 重新建一个客户端并重做授权。
冲突与失败 - 两位管理员同时改同一个客户端时，后提交的一方会收到「客户端状态已变化，列表已刷新，请重新确认后操作。」，此时列表已自动刷新为最新状态，按新状态重新点一次即可。 - 权限不足时按钮变灰（见下表），强行点击不会发请求。
| 动作 | 需要的权限码 |
|---|---|
| 查看列表、概览 | gb28181:openapi:client:read |
| 新建客户端 | gb28181:openapi:client:create |
| 配置能力（能力授权） | gb28181:openapi:client:grant |
| 调用记录 | gb28181:openapi:client:audit（同时还需要 read） |
| 轮换 SK | gb28181:openapi:client:rotate |
| 停用／启用／撤销 | gb28181:openapi:client:status |
界面如图 20-4 所示。
图 20-4 客户端概览弹窗
20.6 状态
客户端只有三种状态，且只能单向推进或回退：
| 状态 | 标签颜色 | 含义 | 还能做哪些动作 |
|---|---|---|---|
| 启用 | 绿 | 可以正常认证、可以调用已授权能力、可以观看 | 概览、配置能力、调用记录、轮换 SK、停用、撤销 |
| 停用 | 橙 | 认证被拒；已建立的观看连接由服务端异步清退 | 概览、配置能力、调用记录、轮换 SK、启用、撤销 |
| 已撤销 | 红 | 终态，认证立即失败、授权不可再改 | 概览、配置能力、调用记录 |
状态流转：启用 ⇄ 停用（可反复），启用／停用 → 已撤销（单向，不可回）。
注意 - 处「停用」「已撤销」时，详情页的能力授权整体只读，开关、全选、保存按钮全部置灰，并提示「当前客户端状态或账号权限不允许修改能力。」要改授权必须先「启用」。 - 「密钥版本」与「认证状态」是两件独立的事：轮换 SK 不会改变状态；停用状态下的客户端即使拿到新 SK 也无法认证。
20.7 新建客户端 ★
前置条件
- 账号具备
gb28181:openapi:client:create。 - 已知这个客户端归属哪个部门、能访问到哪一层设备、给多少限速与并发。归属部门与数据范围创建后不可修改，建错只能重建。
操作步骤
进入左侧菜单「OpenAPI 客户端」。
点击右上「新建客户端」，打开「新建 OpenAPI 客户端」对话框（宽 560）。
填写「客户端名称」，例如
现场集成服务，最多 100 字。建议写成「对接方 + 用途」，便于日后对账。选择「归属部门」。可选范围是当前账号可管理的部门，支持输入搜索；下拉为空说明你的账号没有可管理部门，请联系上级分配。
选择「数据范围」。两个选项下方会实时显示该选项的含义：
- 「本部门」——「仅访问归属部门的设备，不包含下级部门。」
- 「本部门及以下」——「访问归属部门及其所有下级部门的设备。」
在「访问限制」一组里填三个数字（默认 10 / 20 / 10）：
| 字段 | 单位 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|
| 「调用速度」 | 次 / 秒 | 10 | 1–10000 的整数 | 稳态速率上限 |
| 「突发容量」 | 次 | 20 | 1–10000 的整数 | 允许的瞬时突发，应大于等于调用速度 |
| 「观看配额」 | 路并发 | 10 | 1–10000 的整数 | 同一时刻允许的观看路数 |
可选填「组织 / 公司名称」「负责人姓名」「负责人联系方式」，最多 200 / 100 / 100 字。这三项只用于登记与联系，不影响鉴权；建议至少填联系方式，密钥出问题时能第一时间找到人。
点击右下「创建并显示一次性 SK」。
结果确认
- 对话框关闭后弹出「一次性密钥」窗口，同时右上角提示「客户端创建成功，请安全保存一次性 SK」。
- 列表出现新行，认证状态为「启用」，密钥版本为 1。
- 详情页头部显示「已授权 0 / N 项」——新建的客户端没有任何能力，必须按 20.9 授权后才可调用。
异常处理
| 现象 | 原因 | 处理 |
|---|---|---|
| 「创建并显示一次性 SK」是灰的 | 客户端名称为空，或没选归属部门 | 补齐这两项 |
| 名称框失焦后红字「请输入客户端名称」 | 只输了空格 | 输入实际名称 |
| 部门框失焦后红字「请选择归属部门」 | 未选择 | 选择部门 |
| 数字框红字「调用速度需为 1-10000 之间的整数」 | 空值、0、负数、小数或超过 10000 | 改成 1–10000 的整数；三个框的文案分别对应「调用速度」「突发容量」「观看配额」 |
| 弹窗顶部红条显示「服务暂不可用，请稍后重试；若持续出现请联系管理员」 | 服务端异常（HTTP 5xx） | 稍后重试；持续出现请把时间和操作报给管理员 |
| 弹窗顶部红条显示「当前账号没有执行该操作的权限」 | 账号缺 create 权限 | 找管理员分配 |
对话框底部固定有一句说明：「客户端按上方数据范围访问设备，不包含共享可见设备；创建成功后能力默认为空。」这句话解释了两件事：一是共享出去给人看的设备，OpenAPI 看不到；二是能力必须另外授权。
界面如图 20-2 所示。
图 20-2 「新建客户端」弹窗
20.8 一次性密钥
只在这两种时机弹出：新建成功后、轮换成功后。关掉就再也看不到 SK。
窗口内容自上而下：
| 区域 | 内容 |
|---|---|
| 黄色警示条 | 新建时：「SK 只在创建成功后展示这一次。」／轮换时：「轮换后旧 SK 立即失效，新的 SK 只展示这一次。」，后接固定句「关闭窗口后平台无法找回明文 SK，请先将它交给接入方安全保存。」 |
| AK 行 | 左侧「AK」，中间等宽字体的 AK，右侧「复制」按钮 |
| SK 行 | 左侧「SK」，中间橙色等宽字体的 SK，右侧「复制」按钮 |
| 按钮组 | 「我已安全保存」；新建时另有主按钮「继续配置能力」 |
| 控件 | 点了会怎样 |
|---|---|
| 「复制」（AK 行） | 写入剪贴板并提示「AK已复制」；浏览器不允许写剪贴板时提示「复制失败，请手动复制」 |
| 「复制」（SK 行） | 同上，提示「SK已复制」 |
| 「我已安全保存」 | 关闭窗口，回到列表（新建时列表已自动刷新）；不打开能力授权 |
| 「继续配置能力」（仅新建时出现） | 关闭窗口并直接跳到该客户端的能力授权页，省去在列表里找一遍 |
注意 - 这个窗口不能关：没有右上角的叉，按 Esc 无效，点窗外遮罩也无效。只能点两个按钮之一离开，避免误触后永久丢失 SK。 - SK 明文只存在于这一屏。对接方没存下来就只能轮换（20.5），轮换会让对方的旧配置立刻失效。 - 复制走的是浏览器剪贴板，若平台部署在非 HTTPS 环境，浏览器可能禁止写入，此时按提示手工选中复制。
界面如图 20-3 所示。
图 20-3 一次性密钥窗口
20.9 能力授权 ★
能力授权是详情页的主体，也是本功能最容易配错的地方。它的作用是：从平台开放的能力清单里，勾出这个客户端可以调用的那几项。
前置条件
- 账号具备
gb28181:openapi:client:grant。 - 客户端状态为「启用」。停用／已撤销时整页只读。
- 能力目录加载成功。若显示「能力目录暂不可用，授权已锁定」，说明服务端能力清单没取到，此时任何授权操作都不允许，需先解决目录问题（见 20.11）。
页面结构
详情页顶部是摘要卡：左侧「返回客户端列表」、客户端名称 + 状态标签、AK、「数据范围」、「已授权 N / M 项」；右侧「刷新」（圆形箭头图标）。
中部是三栏工作台：
| 区域 | 内容 |
|---|---|
| 顶部工具条 | 搜索框（占位「搜索能力名称、scope 或接口路径」）、风险筛选下拉、「仅看已授权」复选框 |
| 左栏「能力分类」 | 「全部能力」+ 每个能力分组，每项右侧显示「已授权数 / 总数」 |
| 中栏能力表 | 标题为当前分类名；下方固定说明「能力授权决定客户端可以调用哪些外部 API，实际数据仍受归属部门和数据范围约束。」；右上「本分类全选」复选框；表格 |
| 右栏「本次变更」 | 「已授权 N / M 项」、「新增 N 项」、「移除 N 项」、风险告警、「撤销修改」「保存授权」 |
工具条与筛选
| 控件 | 作用 |
|---|---|
| 搜索框 | 同时匹配能力名称、描述、scope、接口路径、请求方法、协议版本、标准依据；支持清空 |
| 风险筛选 | 选项：全部风险／只读／媒体／控制／破坏性／风险未知。用于只看高危项 |
| 「仅看已授权」 | 勾上后表格只留已开启的能力，方便复核 |
三个条件同时生效（与关系）。筛完没有结果时表格显示「没有符合当前筛选条件的能力」。
能力表
| 列 | 内容 | 说明 |
|---|---|---|
| 「能力」 | 能力名称（粗体）+ 描述 + 「协议版本：…」+「标准依据：…」 | 描述缺失时显示「服务端尚未提供描述。」；协议版本会补全成 GB/T 28181-2022 形式 |
| 「Scope」 | 等宽字体的能力标识 | 就是授权项的唯一键，排障时对日志用 |
| 「接口」 | 请求方法标签 + 外部接口路径 | 对接方文档里写的就是这个路径 |
| 「风险」 | 彩色标签：只读（绿）、媒体（橙）、控制（红）、破坏性（红）、风险未知（灰） | 标签下方可能追加「要求 Idempotency-Key」／「支持 Idempotency-Key」／「幂等策略未知」，以及红字「调用时必须提交 confirmed=true」 |
| 「授权」 | 开关（固定在右侧） | 开＝允许调用，关＝禁止 |
风险等级是选授权时的核心依据：
| 风险 | 含义 | 建议 |
|---|---|---|
| 只读 | 只查询，不改状态 | 按需放行 |
| 媒体 | 取流、点播、抓图一类，占带宽与并发 | 与「观看配额」一起评估 |
| 控制 | 会改设备状态，如云台、布防 | 只给确实需要控制的对接方 |
| 破坏性 | 可能造成不可逆的数据或设备状态变化 | 默认不给；给了要在变更单上留痕 |
| 风险未知 | 服务端未标注风险 | 先核实再授权 |
操作步骤
- 在列表页对目标客户端点「配置能力」，进入详情页的能力授权区。
- 左栏选择能力分类（默认「全部能力」）。每个分类后面跟着「已授权数 / 总数」，可先看哪一类还是 0。
- 用搜索框定位具体能力，或用风险筛选把「破坏性」「控制」类单独挑出来复核。
- 逐行拨动「授权」开关。开关拨动只是改草稿，不会立刻生效，右栏「本次变更」会实时累计。
- 需要整类开通时，勾中栏右上「本分类全选」。该复选框在本类已全选时是勾选态，部分选中时是半选态。
- 检查右栏「本次变更」：
- 「新增 N 项」逐条列出
+ scope； - 「移除 N 项」逐条列出
- scope； - 出现橙色告警「包含 N 项媒体或控制能力变更，请确认接入方影响。」时，说明这次改动会扩大或收缩取流／控制权限；
- 出现红色告警「包含 N 项破坏性能力授权变更，调用可能造成不可逆的数据或设备状态变化。」时，必须与对接方书面确认；
- 出现灰色告警「包含 N 项风险未知的能力；请先核实其风险定义再授权。」时，先别保存。
- 「新增 N 项」逐条列出
- 点「保存授权」。
结果确认
- 保存成功后提示「能力授权已更新」，摘要卡的「已授权 N / M 项」刷新为新值，右栏「新增／移除」归零。
- 重新进入该客户端，开关状态与保存时一致。
按钮可用性
| 按钮 | 可点条件 | 不可点原因 |
|---|---|---|
| 「撤销修改」 | 草稿与已保存状态不一致时 | 没有任何改动时置灰 |
| 「保存授权」 | 有 grant 权限、客户端为「启用」、能力目录已加载、有实际改动、当前不在保存中 | 上述任一不满足即置灰；保存中显示加载态 |
| 所有开关 | 同上（不含「有改动」） | 无 grant 权限或客户端非启用态时全部置灰 |
| 「本分类全选」 | 同上 | 同上 |
异常处理
| 现象 | 原因 | 处理 |
|---|---|---|
| 底部弹出红条「授权已被其他管理员更新。已重新加载最新版本，请核对本次变更后再保存。」 | 两人同时改同一客户端，你的版本已过期 | 系统已自动重载最新授权并保留你刚才的草稿，核对后重新保存 |
| 红条「服务暂不可用，请稍后重试；若持续出现请联系管理员」 | 服务端异常（HTTP 5xx） | 稍后重试 |
| 红条「当前账号没有执行该操作的权限」 | 缺 grant 权限 | 找管理员分配 |
| 红条「对象不存在或已被删除，请返回列表刷新」 | 客户端已被别人删除 | 返回列表 |
| 空态「能力目录暂不可用，授权已锁定」 | 服务端能力清单未取到 | 点右上「刷新」重试；持续出现请联系管理员 |
| 红条「能力目录与运行时不一致，请联系管理员重新发布能力目录」 | 服务端发布的清单与实际运行接口不符 | 必须由管理员处理，不要在这状态下授权 |
注意 - 「保存授权」是整份覆盖，不是逐项提交：右栏显示的新增与移除会一次性提交，中途关掉页面等于全部放弃。 - 有未保存改动时，页面会拦你：点「返回客户端列表」或其他菜单，弹「放弃未保存修改」→「能力授权尚未保存，放弃本次修改并离开页面？」，按钮为「放弃修改」「留在当前页」；在有页签的场景下切页签，文案是「…放弃本次修改并切换页面？」。直接关浏览器标签页会触发浏览器的离开确认。 - 授权只在保存成功后才生效。改完预览就以为生效，是对接方「403 无权」的最常见原因。
界面如图 20-5 所示。
图 20-5 能力授权区域
20.10 调用记录
在列表行点「调用记录」进入。用于回答「这个客户端刚才那次调用为什么失败」。
| 控件 | 说明 |
|---|---|
| 结果筛选 | 全部结果／成功／失败；切换后回到第 1 页重新取数 |
| 「刷新」（圆形箭头图标） | 保持条件与页码重新取数 |
| 列 | 内容 |
|---|---|
| 「时间」 | 调用发生时间，YYYY-MM-DD HH:MM:SS |
| 「能力 / 操作」 | 第一行能力中文名（管理类操作显示「管理操作」），第二行等宽字体的 scope |
| 「资源」 | 资源类型 · 资源标识，缺一项显示 - |
| 「结果」 | 标签，「成功」为绿、「失败」为橙（原始值为 success / 其他） |
| 「原因」 | 失败原因分类，用于快速归类；成功时通常为空 |
| 「耗时」 | 毫秒数 |
| 「请求 ID」 | 排障时提供给开发人员的唯一标识 |
分页每页 10 条，可切 20／50／100。未加载过时显示「尚未加载调用记录」，加载完成为空显示「暂无调用记录」。
注意 - 没有 gb28181:openapi:client:audit 权限时，这一块显示「没有调用记录查看权限」，行上的「调用记录」按钮也是灰的。 - 调用记录是事后审计，不是实时日志流。刚发生的调用可能需要刷新一次才出现。
界面如图 20-6 所示。
图 20-6 调用记录
20.11 常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 对接方收到 401 认证失败 | SK 用错、已被轮换、客户端被停用／撤销 | 先看列表的「认证状态」与「密钥版本」：状态不是「启用」→ 按 20.5 启用；密钥版本比对接方记录的大 → 说明轮换过，需重新下发（只能再轮换一次并把新 SK 交给对方） |
| 对接方收到 403 无权 | 该能力没授权，或客户端的数据范围不覆盖目标设备 | 详情页搜该能力看「授权」开关是否为开；再看摘要卡的「数据范围」是否包含目标设备所属部门。共享出去的设备 OpenAPI 一律看不到 |
| 对接方被限流／429 | 超过「调用速度」或「突发容量」，或观看路数超过「观看配额」 | 让对接方降低并发或加重试退避；确属业务需要，则由管理员重建客户端并调大配额（限制项创建后不可改） |
| 新建完客户端，接口全返回 403 | 能力授权默认为空 | 按 20.9 授权后重试 |
| 想改归属部门或数据范围，找不到编辑入口 | 设计上不允许改 | 只能新建一个客户端，重新授权，再把旧的撤销 |
| 能力授权页是灰的、提示「当前客户端状态或账号权限不允许修改能力。」 | 客户端处于「停用」或「已撤销」，或账号没有 grant 权限 | 先启用客户端；确认权限 |
| 保存授权后接口仍报无权 | 保存失败但没注意，或有未保存改动就离开了页面 | 回详情页看开关是否仍是打开状态；重新保存一次并确认提示「能力授权已更新」 |
| 页面提示「服务暂不可用，请稍后重试；若持续出现请联系管理员」 | 服务端异常 | 稍后重试；持续出现把时间点报给管理员，由管理员查服务日志 |
「概览」里「调用限速」显示 10 / 秒，突发 20，看不懂 | 前者是每秒允许的请求数，后者是允许的瞬时峰值 | 见 20.7 第 6 步的字段说明 |