常见问题

​

接入相关

​

如何获取表格的 workbookId

• 从表格 URL 中获取：打开钉钉表格，URL 中包含的文档 ID 即为 workbookId。

• 从文档信息中获取：点击表格左上角「菜单」→「表格」→「文档信息」，其中的文档 ID 即为 workbookId。

• 通过知识库 API 获取：调用获取节点接口，返回的nodeId（dentryUuid）即为workbookId。

​

如何获取 operatorId

1. 通过手机号获取 userId：调用根据手机号查询用户接口。
2. 通过 userId 获取 unionId：调用查询用户详情接口，返回的unionId即为operatorId。

​

AccessToken 过期了怎么办

• 缓存 Token 及其过期时间；
• 在 Token 过期前 5 分钟主动刷新；
• 当接口返回 Token 无效错误时，立即刷新并重试。

​

调用接口报错 The operator has no permission，如何解决

• 用户是否有表格的访问权限：确保该用户已被添加为表格的协作者，或表格所在的知识库对该用户开放了权限。
• 权限类型是否匹配：
  • 读操作：如GetAllSheets、GetSheet、GetRange需要Document.Workbook.Read 权限。
  • 写操作：如AppendRows、UpdateRange、CreateSheet）需要 Document.Workbook.Write权限。
• 应用是否申请了对应权限：在钉钉开放平台的应用管理中，检查是否已申请并获批了相应的权限点。

​

API 使用相关

​

sheetId 参数可以传工作表名称吗

• 传 ID：Sheet1，系统生成的 ID；
• 传名称：销售数据，用户自定义的工作表标题。

建议：优先使用工作表 ID，因为名称可能被用户修改。可通过GetAllSheets接口获取所有工作表的 ID 和名称。

​

AppendRows 追加数据时，数据会写到哪里

• 如果工作表为空，数据从第一行开始写入。
• 追加的列数应与已有数据的列数保持一致，以确保数据对齐。

​

UpdateRange 更新单元格时，rangeAddress 的格式是什么？

​

GetRange 和 UpdateRange 有什么区别？

​

调用接口返回 invalidRequest.resource.notFound，如何排查

​

钉钉表格 API 有哪些使用限制

​

如何在代码中处理 API 调用失败的情况

• Token 过期自动刷新：捕获 Token 无效错误，自动刷新后重试。
• 频率限制重试：收到 429 错误时，等待一段时间后重试（建议使用指数退避策略）。
• 幂等性处理：对于写操作（如 AppendRows），需注意重试可能导致数据重复写入。建议在数据中加入唯一标识，写入后通过 GetRange 验证。
• 超时处理：网络请求设置合理的超时时间（建议 30 秒），超时后进行重试。

import time

def call_api_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except TokenExpiredError:
            refresh_token()
        except RateLimitError:
            time.sleep(2 ** attempt)
        except TimeoutError:
            time.sleep(1)
    raise Exception("API 调用失败，已达最大重试次数")