95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# 事件订阅
|
||
|
||
管理开放平台企业内部应用的事件订阅：列出可订阅事件、按事件码列表批量订阅/退订。
|
||
|
||
> 所有命令通过 `--unified-app-id` 定位应用；`corpId` / `userId` 由 MCP 系统上下文注入，CLI 不传。订阅/退订是写操作，先 `--dry-run`，确认后再 `--yes`。
|
||
|
||
## 可订阅事件列表
|
||
|
||
**搜索优先**：定位事件码时优先用 `--keyword` 搜索；只有用户明确要「全部事件」时才不带 `--keyword` 翻全量。
|
||
|
||
```bash
|
||
# 首选：按关键词搜索定位事件码
|
||
dws dev app event list --unified-app-id <unifiedAppId> --keyword 通讯录 --page-size 20 --format json
|
||
# 兜底：用户明确要全部事件时才翻全量
|
||
dws dev app event list --unified-app-id <unifiedAppId> --page-size 20 --format json
|
||
```
|
||
|
||
MCP tool: `list_dev_app_events`。`--keyword` 按事件码或事件名称模糊匹配。返回 `pushType=STREAM`、`events[]`、`hasMore`、`nextCursor`、`pageSize`；`hasMore=true` 时下一页继续传 `--cursor <nextCursor>`，逐页处理。`events[]` 每项含：
|
||
|
||
| 字段 | 含义 |
|
||
|------|------|
|
||
| `eventCode` | 事件码，订阅/退订时传入，如 `user_add_org` |
|
||
| `eventName` | 事件名称，如「通讯录用户增加」 |
|
||
| `subscribed` | 当前是否已订阅 |
|
||
|
||
常见事件码示例：`user_add_org`(通讯录用户增加) / `user_modify_org`(用户更改) / `user_leave_org`(用户离职) / `org_dept_create`(部门创建) / `org_dept_modify`(部门修改) / `org_dept_remove`(部门删除)。以 `event list` 实际返回为准。
|
||
|
||
## 订阅事件
|
||
|
||
```bash
|
||
dws dev app event subscribe --unified-app-id <unifiedAppId> --event-codes user_add_org,org_dept_modify --dry-run --format json
|
||
dws dev app event subscribe --unified-app-id <unifiedAppId> --event-codes user_add_org,org_dept_modify --yes --format json
|
||
```
|
||
|
||
MCP tool: `subscribe_dev_app_events`（入参 `unifiedAppId` + 必填数组 `eventCodes`，一次订阅多个事件码）。成功返回 `success/operation=SUBSCRIBE/unifiedAppId/eventCodes/needsPublish/versionRequiredAction`；失败时补 `errorCode/errorMsg/reason/retryable/action`。
|
||
|
||
## 退订事件
|
||
|
||
```bash
|
||
dws dev app event unsubscribe --unified-app-id <unifiedAppId> --event-codes user_add_org,org_dept_modify --dry-run --format json
|
||
dws dev app event unsubscribe --unified-app-id <unifiedAppId> --event-codes user_add_org,org_dept_modify --yes --format json
|
||
```
|
||
|
||
MCP tool: `unsubscribe_dev_app_events`（入参 `unifiedAppId` + 必填数组 `eventCodes`，一次退订多个事件码）。成功返回 `success/operation=UNSUBSCRIBE/unifiedAppId/eventCodes/needsPublish/versionRequiredAction`；失败时补 `errorCode/errorMsg/reason/retryable/action`。
|
||
|
||
## 字段映射
|
||
|
||
| CLI | MCP | 必填 | 说明 |
|
||
|-----|-----|------|------|
|
||
| `--unified-app-id` | `unifiedAppId` | 是 | 统一应用 ID |
|
||
| `--keyword` | `keyword` | list 可选 | 事件搜索关键词，匹配事件码或事件名称 |
|
||
| `--cursor` | `cursor` | list 可选 | 服务端返回的下一页游标 |
|
||
| `--page-size` | `pageSize` | list 可选 | 单页数量 |
|
||
| `--event-codes` | `eventCodes` | subscribe/unsubscribe 必填 | 事件码列表，逗号分隔，取自 `event list` |
|
||
|
||
## 灰度应用需发布版本生效（重要）
|
||
|
||
对**灰度统一应用**，`subscribe`/`unsubscribe` 只会把变更**暂存到版本元数据**，不会立即生效，需后续走版本发布链路：
|
||
|
||
```text
|
||
event subscribe/unsubscribe 订阅变更写入版本元数据
|
||
→ version create 创建新版本
|
||
→ version check-approval 预检审批
|
||
→ version publish 发布后订阅变更才生效
|
||
→ version status 轮询发布/审批状态
|
||
```
|
||
|
||
详见版本发布文档。
|
||
|
||
## 单步流程
|
||
|
||
```text
|
||
1. 定位事件码（搜索优先）
|
||
dws dev app event list --unified-app-id <ID> --keyword <关键词> --format json
|
||
→ 从返回里挑 eventCode
|
||
→ 用户明确要全部事件时，才不带 --keyword 翻全量（逐页）
|
||
|
||
2. 订阅（批量/全量前先列候选 eventCode 给用户确认）
|
||
dws dev app event subscribe --unified-app-id <ID> --event-codes <CODE1>,<CODE2> --dry-run --format json
|
||
→ 确认后加 --yes
|
||
|
||
3. 验证
|
||
dws dev app event list --unified-app-id <ID> --keyword <关键词> --format json
|
||
→ 确认对应事件 subscribed=true（灰度应用需先发布版本）
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
| 情况 | 处理 |
|
||
|------|------|
|
||
| `--event-codes` 缺失 | CLI 直接报错，先 `event list` 取事件码 |
|
||
| 订阅后 `subscribed` 仍为 false | 灰度应用需先 `version publish` 发布版本 |
|
||
| `errorCode=STREAM_NOT_CONNECTED` / `reason=STREAM_NOT_CONNECTED` | 先执行 `dev connect` 建联，再重试订阅 |
|
||
| `ServiceResult.success=false` | 透传 `errorCode/errorMsg` |
|