feat: add dingtalk-log skill for querying work reports
- Add SKILL.md with full API documentation - Add shell script for quick queries - Update TOOLS.md with reference to new skill
This commit is contained in:
root
341
skills/dingtalk-document/references/api.md
Normal file
341
skills/dingtalk-document/references/api.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# dingtalk-document API 参考
|
||||
|
||||
> 所有接口均已验证可用。
|
||||
> `NEW_TOKEN` = 新版 token（`api.dingtalk.com` 用），获取方式 `bash scripts/dt_helper.sh --token`
|
||||
> `OPERATOR_ID` = 用户 unionId，获取方式 `bash scripts/dt_helper.sh --get DINGTALK_MY_OPERATOR_ID`
|
||||
> ⚠️ **重要**：所有接口均需传 `operatorId`（unionId），缺少则返回 `MissingoperatorId` 错误。
|
||||
|
||||
---
|
||||
|
||||
## 1. 查询知识库列表
|
||||
|
||||
```
|
||||
GET https://api.dingtalk.com/v2.0/wiki/workspaces?operatorId={OPERATOR_ID}&maxResults=20&nextToken=
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `operatorId` | string | ✅ | 用户 unionId |
|
||||
| `maxResults` | int | ❌ | 每页数量，默认 20 |
|
||||
| `nextToken` | string | ❌ | 分页令牌，首次为空 |
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"workspaces": [
|
||||
{
|
||||
"workspaceId": "QXvd5SLN2AxOQz0Z",
|
||||
"name": "团队知识库",
|
||||
"description": "...",
|
||||
"rootNodeId": "P0MALyR8kl3qpB7qTkM1xn3mW3bzYmDO",
|
||||
"type": "TEAM",
|
||||
"url": "https://alidocs.dingtalk.com/i/spaces/.../overview",
|
||||
"createTime": "2024-01-01T00:00Z",
|
||||
"modifiedTime": "2024-06-01T00:00Z"
|
||||
}
|
||||
],
|
||||
"nextToken": "..."
|
||||
}
|
||||
```
|
||||
|
||||
> 翻页：`nextToken` 非空时传入下次请求继续获取。
|
||||
|
||||
---
|
||||
|
||||
## 2. 查询知识库信息
|
||||
|
||||
```
|
||||
GET https://api.dingtalk.com/v2.0/wiki/workspaces/{workspaceId}?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
响应：单个 workspace 对象（结构同列表项）
|
||||
|
||||
---
|
||||
|
||||
## 3. 查询节点列表
|
||||
|
||||
```
|
||||
GET https://api.dingtalk.com/v2.0/wiki/nodes?parentNodeId={nodeId}&operatorId={OPERATOR_ID}&maxResults=50&nextToken=
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `parentNodeId` | string | ✅ | 父节点 ID，传知识库的 `rootNodeId` 可列出顶层内容 |
|
||||
| `operatorId` | string | ✅ | 用户 unionId |
|
||||
| `maxResults` | int | ❌ | 每页数量，默认 20 |
|
||||
| `nextToken` | string | ❌ | 分页令牌 |
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"nodeId": "LeBq413JAw31yaz1fB0BBdLGWDOnGvpb",
|
||||
"name": "使用文档.adoc",
|
||||
"type": "FILE",
|
||||
"category": "ALIDOC",
|
||||
"extension": "adoc",
|
||||
"workspaceId": "QXvd5SnBnzmZdZ0Z",
|
||||
"url": "https://alidocs.dingtalk.com/i/nodes/...",
|
||||
"createTime": "2026-03-04T16:58Z",
|
||||
"modifiedTime": "2026-03-04T17:51Z"
|
||||
}
|
||||
],
|
||||
"nextToken": "..."
|
||||
}
|
||||
```
|
||||
|
||||
> `type`：`FILE`（文档/文件）| `FOLDER`（文件夹）
|
||||
|
||||
---
|
||||
|
||||
## 4. 查询单个节点
|
||||
|
||||
```
|
||||
GET https://api.dingtalk.com/v2.0/wiki/nodes/{nodeId}?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
响应：`{ "node": { nodeId, name, type, category, workspaceId, url, ... } }`
|
||||
|
||||
---
|
||||
|
||||
## 5. 通过 URL 查询节点
|
||||
|
||||
```
|
||||
POST https://api.dingtalk.com/v2.0/wiki/nodes/queryByUrl?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"url": "https://alidocs.dingtalk.com/i/nodes/<nodeId>",
|
||||
"operatorId": "{OPERATOR_ID}"
|
||||
}
|
||||
```
|
||||
|
||||
响应：与 GET 单个节点相同的 node 结构。
|
||||
|
||||
---
|
||||
|
||||
## 6. 创建文档
|
||||
|
||||
```
|
||||
POST https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"operatorId": "{OPERATOR_ID}",
|
||||
"docType": "DOC",
|
||||
"name": "文档标题"
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `operatorId` | string | ✅ | 用户 unionId |
|
||||
| `docType` | string | ✅ | 固定填 `"DOC"`（ALIDOC 富文本格式） |
|
||||
| `name` | string | ✅ | 文档标题 |
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"dentryUuid": "aaa",
|
||||
"nodeId": "xxx",
|
||||
"docKey": "yyy",
|
||||
"workspaceId": "zzz",
|
||||
"url": "https://..."
|
||||
}
|
||||
```
|
||||
|
||||
> **重要**：
|
||||
> - `docKey` / `dentryUuid`：用于 `/v1.0/doc/suites/documents/{id}` 内容读写
|
||||
> - `nodeId`：用于 `/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}` 删除/管理
|
||||
|
||||
---
|
||||
|
||||
## 7. 删除文档
|
||||
|
||||
```
|
||||
DELETE https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
> `workspaceId` 和 `nodeId` 均使用创建文档响应中的值。成功返回 `200 {}`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 读取文档内容（Block 结构）
|
||||
|
||||
```
|
||||
GET https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
> **docKey 的来源**：
|
||||
> - 通过 wiki nodes 接口查到的 `nodeId` 本质是 `dentryUuid`，可直接用于正文读写
|
||||
> - 通过创建文档接口新建的文档：可使用响应中的 `docKey` 或 `dentryUuid`
|
||||
> - 创建响应中的 `nodeId`（通常出现在 `/docs/<nodeId>` 链接中）不能直接用于正文读写
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"data": [
|
||||
{ "blockType": "heading", "heading": { "level": "heading-2", "text": "快速开始" }, "index": 0, "id": "xxx" },
|
||||
{ "blockType": "paragraph", "paragraph": { "text": "正文内容..." }, "index": 1, "id": "yyy" },
|
||||
{ "blockType": "table", "table": { "colSize": 2, "rowSize": 10 }, "index": 2, "id": "zzz" },
|
||||
{ "blockType": "unknown", "index": 3, "id": "aaa", "unknown": {} }
|
||||
]
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
`blockType` 枚举：`heading`、`paragraph`、`unorderedList`、`orderedList`、`table`、`blockquote`、`unknown`（代码块/图片等）
|
||||
|
||||
---
|
||||
|
||||
## 9. 覆盖写入文档内容
|
||||
|
||||
```
|
||||
POST https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/overwriteContent?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
> ⚠️ `operatorId` 必须**同时**作为 query param 和请求体字段传入，缺一会报 `Missingcontent` 错误。
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"operatorId": "{OPERATOR_ID}",
|
||||
"content": "# 新标题\n\n新的正文内容，支持 Markdown 格式。",
|
||||
"contentType": "markdown"
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ 此操作**全量覆盖**文档内容，不可撤销。
|
||||
|
||||
---
|
||||
|
||||
## 10. 追加文本到段落
|
||||
|
||||
```
|
||||
POST https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/blocks/{blockId}/paragraph/appendText
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{ "operatorId": "{OPERATOR_ID}", "text": "追加的文字" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 添加文档成员
|
||||
|
||||
```
|
||||
POST https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}/members
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"operatorId": "{OPERATOR_ID}",
|
||||
"members": [
|
||||
{ "id": "<userId>", "roleType": "viewer" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `id` | 用户 userId（**注意**：这里用 userId，不是 unionId）|
|
||||
| `roleType` | `viewer`（只读）| `editor`（可编辑）|
|
||||
|
||||
---
|
||||
|
||||
## 12. 更新文档成员权限
|
||||
|
||||
```
|
||||
PUT https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}/members/{memberId}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{ "operatorId": "{OPERATOR_ID}", "roleType": "viewer" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. 移除文档成员
|
||||
|
||||
```
|
||||
DELETE https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}/members/{memberId}?operatorId={OPERATOR_ID}
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 搜索文档（用于找回可读写 ID）
|
||||
|
||||
```
|
||||
GET https://api.dingtalk.com/v1.0/doc/docs?operatorId={OPERATOR_ID}&workspaceId={workspaceId}&keyword={keyword}&maxResults=20&nextToken=
|
||||
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
|
||||
```
|
||||
|
||||
说明：
|
||||
- 需要权限：`Document.WorkspaceDocument.Read`
|
||||
- 返回结果中的 `docs[].nodeBO.nodeId` 即可用于 `/v1.0/doc/suites/documents/{id}` 的读写（该值是 `dentryUuid` 风格 ID）
|
||||
|
||||
示例响应（节选）：
|
||||
```json
|
||||
{
|
||||
"docs": [
|
||||
{
|
||||
"nodeBO": {
|
||||
"name": "测试创建.adoc",
|
||||
"nodeId": "np9zOoBVBYwB2OZBIn4y0G1vW1DK0g6l",
|
||||
"url": "https://alidocs.dingtalk.com/i/nodes/np9zOoBVBYwB2OZBIn4y0G1vW1DK0g6l"
|
||||
},
|
||||
"workspaceBO": {
|
||||
"workspaceId": "QXvd5SLN2AxOQz0Z"
|
||||
}
|
||||
}
|
||||
],
|
||||
"hasMore": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误码
|
||||
|
||||
| HTTP状态码 | 错误码 | 说明 | 处理建议 |
|
||||
|---|---|---|---|
|
||||
| 400 | `MissingoperatorId` | operatorId 未传 | 补充 operatorId（unionId）|
|
||||
| 400 | `paramError` | 参数类型错误 | operatorId 必须是 unionId，不是 userId |
|
||||
| 403 | `Forbidden.AccessDenied.AccessTokenPermissionDenied` | 应用缺少权限 | 错误中有 `requiredScopes`，开通对应权限 |
|
||||
| 404 | `InvalidAction.NotFound` | 接口路径不存在 | 检查版本号（v1.0/v2.0）和路径 |
|
||||
| 429 | — | QPS 限流 | 1 秒后重试 |
|
||||
|
||||
---
|
||||
|
||||
## 所需应用权限
|
||||
|
||||
| 功能 | 权限 scope |
|
||||
|---|---|
|
||||
| 查询知识库/节点 | `Wiki.Node.Read` |
|
||||
| 读取文档正文 | `Storage.File.Read` |
|
||||
| 写入文档正文 | `Storage.File.Write` |
|
||||
| 创建/删除文档 | `Storage.File.Write` |
|
||||
| 查询用户 unionId | `Contact.User.Read` |
|
||||
Reference in New Issue
Block a user