Broker 部署 API

使用 Broker 部署 API 管理 EMQX Cloud 中的 Broker 部署。本页说明如何创建和管理部署 API Key，以安全访问 API。

API 功能

Broker 部署 API 支持客户端监控、消息发布、认证和授权等部署层面的操作。

API	适用部署	描述
Serverless 部署 API	Serverless 部署	管理 Serverless 部署中客户端、订阅和发布的相关操作。
专有版和弹性专有版（v6）部署 API	专有版和弹性专有版（v6）部署	管理专有版和弹性专有版（v6）部署中的各项操作。对于 v5 和 v4 部署，请分别参阅 v5 API 和 v4 API。
BYOC 部署 API （API 与专有版一致）	BYOC（v6）部署	管理 BYOC（v6）部署中的各项操作。

创建和管理部署 API Key

部署 API Key 用于对访问 Broker 部署 API 的请求进行身份验证与授权。API Key 的创建与管理方式依据部署类型和版本的不同而有所差异。

对于运行中的专有版或弹性专有版部署，也可以使用平台 API 创建部署 API Key。平台 API 支持通过 API 权限白名单限制新 Key 的访问范围。有关要求和限制，参见创建部署 API Key。

在专有版和弹性专有版部署中创建 API Key

对于专有版和弹性专有版部署，您可以为每个 API Key 添加自定义备注，并分配细粒度的访问权限。

1. 进入目标部署的部署概览页面。

2. 在部署 API Key 区域，点击 + 新建 API Key。

3. 在弹出的对话框中填写以下信息：

   • 备注（可选）：添加描述信息，用于标识该 API Key 的用途和范围。
   • API 权限：
     • 选择所需的 HTTP 方法（如 GET、POST、PUT、DELETE）。
     • 可通过关键字筛选或搜索特定 API 路径。
     • 也可使用分类级复选框，批量选择整个分类或具体 API。
   

4. 点击确认后，系统将显示生成的 App ID 和 App Secret。

   重要提示

   App Secret 在 API Key 创建时仅显示一次，请妥善保存，一旦关闭将无法再次查看。

5. 点击关闭退出对话框。

关于专有版 (v4) 历史 API Key

在权限选择功能上线前创建的专有版 (v4) API Key 默认拥有全部权限，备注为空，且列表中不显示创建时间。建议删除旧 API Key 并重新创建，以获得完整的权限控制和创建时间记录。

Source 和授权缓存权限（v5/v6）

在专有版和弹性专有版（v5/v6）部署中，您可以在创建或编辑部署 API Key 时选择 Source API 和授权缓存重置权限。Source API 权限允许您通过 Broker 部署 API 管理 Source（数据源），例如 Kafka Consumer Source。

在 API 权限中，展开数据集成 -> 输入动作，选择 Source API 权限。仅选择应用所需的路径和 HTTP 方法：

权限路径	HTTP 方法	用途
/api/v5/sources	GET、POST、PUT、DELETE	管理 Source。
/api/v5/source_types	GET	列出可用的 Source 类型。

为 /api/v5/sources 选择的 HTTP 方法权限，也适用于以 /api/v5/sources 开头的接口路径，包括 /api/v5/sources/{id}、/api/v5/sources_summary 和 /api/v5/sources_probe。每个请求须使用具体 API 操作支持的路径和方法。

如果应用只需读取数据，仅选择所需的 GET 权限。Connector、输出动作或 Rule API 的权限不包含 Source API 的访问权限。缺少所需 Source API 权限的请求可能返回 403。

如需重置节点级别的授权缓存，在授权权限分组中选择 /api/v5/authorization/node_cache/reset 的 POST 权限。该接口仅支持 POST，要求 EMQX 5.10.0 或更高版本。

重要提示

在这些权限选项可用前创建的 API Key 不会自动获得 Source 或授权缓存重置权限。如需使用这些 API，请编辑 API Key，选择相应权限并保存。

在 Serverless 部署中创建 API Key

对于 Serverless 部署，API Key 将自动生成并默认拥有全部访问权限，不支持设置备注或配置权限。

1. 进入目标 Serverless 部署的部署概览页面。

2. 在部署 API Key 区域，点击 + 新建 API Key。

3. 系统将自动生成 App ID 和 App Secret，并在确认对话框中显示。

   重要提示

   App Secret 在 API Key 创建时仅显示一次，请妥善保存，一旦关闭将无法再次查看。

4. 点击关闭退出对话框。

管理 API Key

• 编辑（适用于专有版和弹性专有版）：可更新备注信息或调整分配的 API 权限；
• 删除：可随时删除 API Key，以立即撤销访问权限；
• 查看权限（适用于专有版和弹性专有版）：展开 API Key 记录，可查看其已分配的访问权限。