noteTb: 247
This data as json
| id | user_id | content | tags | created_at | updated_at | enable | pinned | folder_id | comment | position | visibility |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 247 | 1 1 | # 钉钉经验 作者：Copilot 版本：1.1 ## 通过应用凭证查用户 unionId 问题描述： - 钉钉表格 API 读取 workbook 时需要传 `operatorId`。 - 在当前项目里，这个 `operatorId` 实际使用的是目标操作人的 `unionid`，例如李梦的 `unionid`。 - 只用新版 `https://api.dingtalk.com/v1.0/oauth2/accessToken` 获取的 token，不能直接调用旧版 `oapi.dingtalk.com/topapi` 通讯录接口，否则会返回 `40014 不合法的access_token`。 解决办法： 1. 用旧版 token 接口获取通讯录可用的 access_token： ```powershell $appKey = '你的 APP_KEY' $appSecret = '你的 APP_SECRET' $old = Invoke-RestMethod -Method Get -Uri ('https://oapi.dingtalk.com/gettoken?appkey=' + $appKey + '&appsecret=' + $appSecret) $old.access_token ``` 2. 用旧版通讯录接口列出根部门用户： ```powershell $body = @{ dept_id = 1; cursor = 0; size = 100; language = 'zh_CN' } | ConvertTo-Json -Compress $r = Invoke-RestMethod -Method Post -Uri ('https://oapi.dingtalk.com/topapi/v2/user/list?access_token=' + $old.access_token) -ContentType 'application/json' -Body $body $r.result.list | Select-Object name, userid, unionid ``` 3. 在返回列表里按 `name` 找到目标人，取 `unionid` 作为钉钉文档 API 的 `operatorId`。 本次验证结果： - 李梦：`unionid` = `a58WCQV8iP3pDgp8TUWESEQiEiE` - 李梦：`userid` = `2020080928846616` - 黎盈莹：`unionid` = `qXTyB2t8BNrQtYX4JH7fHAiEiE` - 黎盈莹：`userid` = `01362837323940044863` 影响范围： - 这个方法只用于查组织通讯录里的用户身份，不等同于验证钉钉文档资源是否存在。 - 文档 workbook API 仍然使用新版 token：`https://api.dingtalk.com/v1.0/oauth2/accessToken`，请求头传 `x-acs-dingtalk-access-token`，参数传 `operatorId=<unionid>`。 - 如果 workbook API 返回 `uuid not exist` 或 404，优先检查数据源里保存的钉钉链接是否包含正确的 `docKey` / workbook id，不能先怀疑 unionId。 踩坑： - 新版 token 和旧版 topapi token 不能混用。 - `https://api.dingtalk.com/v1.0/contact/users`、`https://api.dingtalk.com/v1.0/contact/departments` 这两个地址本次验证返回 404，不适合作为当前查 unionId 的路径。 --- ## dentryKey vs workbook 内部 UUID 问题描述： - 钉钉表格编辑链接格式：`https://alidocs.dingtalk.com/spreadsheetv2/{dentryKey}/edit?dentryKey={dentryKey}&...` - URL 里可见的 `dentryKey`（如 `D4BNAw73cwb3ymV0`）是文档的公开标识符 - 工作簿 API `GET https://api.dingtalk.com/v1.0/doc/workbooks/{workbookId}/sheets` 需要的是另一个内部 UUID - 直接把 dentryKey 当 workbookId 传入，返回 `{"code":"invalidRequest.resource.notFound","message":"uuid not exist"}` 解决办法： - 在钉钉里打开目标表格 → 点右上角「分享」→ 复制分享链接 - 分享链接格式一般为：`https://alidocs.dingtalk.com/...?docKey=XXXXXXX&...` - 取 `?docKey=` 后面的值，这才是 workbook 内部 UUID - 把这个分享链接（含 docKey）存入数据源表，代码 `_extract_ding_wb_id()` 会自动优先提取 `?docKey=` 影响范围： - 凡是数据源表里存的是编辑链接（URL 里没有 `docKey=` 参数），读取钉钉表格都会报 `uuid not exist` - 替换为分享链接后可正常连通 - 代码里已有对应兼容逻辑，无需改代码，只需更新数据源 URL --- ## 通过链接获取 workbookId（nodeId / dentryUuid） 问题描述： - 钉钉表格编辑链接里的 `/spreadsheetv2/{dentryKey}/edit` 看起来像表格 ID，但直接传给 workbooks API 会返回 `uuid not exist`。 - 用户在「分享」面板里点「复制链接」时，可能拿到的仍然是这种编辑链接，不一定包含 `docKey`。 - 如果只要求重新复制 `?docKey=` 链接，会卡住，因为当前实际入口就是这个编辑链接。 解决办法： 1. 保留原始钉钉文档链接。 2. 用新版 token 调钉钉知识库接口： ```http POST https://api.dingtalk.com/v2.0/wiki/nodes/queryByUrl?operatorId=<unionId> x-acs-dingtalk-access-token: <new_access_token> Content-Type: application/json { "url": "https://alidocs.dingtalk.com/spreadsheetv2/.../edit?...", "option": { "withStatisticalInfo": false, "withPermissionRole": false } } ``` 3. 返回里的 `node.nodeId` 就是 `dentryUuid`，官方表格文档说明知识库 API 返回的 `nodeId` 可作为表格 `workbookId`。 4. 再用这个 `nodeId` 调用： ```http GET https://api.dingtalk.com/v1.0/doc/workbooks/{nodeId}/sheets?operatorId=<unionId> ``` 本次验证结果： - 当前链接直接作为 workbookId：返回 `invalidRequest.resource.notFound / uuid not exist`。 - `queryByUrl` 接口路径确认正确。 - 当前应用返回 403，错误要求开通 `Wiki.Node.Read`（知识库节点读权限）。 - 开通 `Wiki.Node.Read` 后，应优先用当前链接自动换 `nodeId`，不必强制要求数据源链接含 `?docKey=`。 影响范围： - 适用于钉钉表格 URL 只有 `dentryKey`、没有 `docKey`，但操作人有文档权限的情况。 - 应用除了钉钉表格读权限，还需要 `Wiki.Node.Read`，否则无法从链接换出 workbookId。 - 如果没有 `Wiki.Node.Read`，代码应给出权限申请提示，而不是继续提示用户换 `docKey`。 --- ## 从 URL 的 sheet_range 参数读取 Sheet ID 问题描述： - 钉钉表格编辑链接的 `sheet_range` 参数隐含了 sheet ID，例如： `sheet_range=st-74a99be8-34022_2930_10_1_1` - 格式为：`{sheetId}_{startRow}_{startCol}_{endRow}_{endCol}` - 下划线前的 `st-74a99be8-34022` 就是 sheet ID 用途： - 在没有 docKey 的情况下，仍可从编辑链接里提取 sheet ID - 用于后续调用 `/v1.0/doc/workbooks/{workbookId}/sheets/{sheetId}/ranges` 读取数据 - 同一张表不同滚动位置的链接 `dentryKey` 完全相同，sheet ID 也相同，只有末尾坐标不同 解析方法： ```python import re m = re.search(r'sheet_range=(st-[^_]+(?:-\d+)*)_', url) sheet_id = m.group(1) if m else None ``` --- ## 总结：完整连接流程 ``` APP_KEY + APP_SECRET │ ├─→ 旧版 gettoken（oapi.dingtalk.com/gettoken） │ └─→ access_token（32位） │ └─→ 通讯录 topapi/v2/user/list → 查用户 unionId │ └─→ 新版 accessToken（api.dingtalk.com/v1.0/oauth2/accessToken） └─→ 放 Header: x-acs-dingtalk-access-token └─→ 文档 API：/v1.0/doc/workbooks/{docKey}/sheets 需要参数 operatorId = 用户 unionId 需要 docKey = 分享链接里的 ?docKey= 值（非编辑链接里的 dentryKey） sheet ID 可从编辑链接 sheet_range 参数里提取（st- 开头到第一个下划线） ``` | [] | 2026-05-12 13:59:53 | 2026-05-12 13:59:53 | T | F | source=simplenote; source_id=0a03047e-de90-457d-acb9-579f57d3761d | 30 | public |