From b1f1324d02b4bb1d0b7817339c86acb4ff388bfd Mon Sep 17 00:00:00 2001 From: zelong <2895587166@qq.com> Date: Mon, 15 Dec 2025 18:52:51 +0800 Subject: [PATCH] 'phase1-1.1' --- .gitignore | 135 ++ TAPD接口文档.md | 1218 +++++++++++++ config/config.ini | 9 + requirements.txt | 13 + src/__init__.py | 7 + src/api_test.py | 372 ++++ src/config.py | 143 ++ src/main.py | 149 ++ 开发路线.md | 638 +++++++ 智能表格接口文档.md | 4222 +++++++++++++++++++++++++++++++++++++++++++ 需求文档.md | 55 + 11 files changed, 6961 insertions(+) create mode 100644 .gitignore create mode 100644 TAPD接口文档.md create mode 100644 config/config.ini create mode 100644 requirements.txt create mode 100644 src/__init__.py create mode 100644 src/api_test.py create mode 100644 src/config.py create mode 100644 src/main.py create mode 100644 开发路线.md create mode 100644 智能表格接口文档.md create mode 100644 需求文档.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ac45307 --- /dev/null +++ b/.gitignore @@ -0,0 +1,135 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# PEP 582; __pypackages__ +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyderworkspace + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# VSCode +.vscode/ + +# Custom +logs/ +.claude/ \ No newline at end of file diff --git a/TAPD接口文档.md b/TAPD接口文档.md new file mode 100644 index 0000000..35b441d --- /dev/null +++ b/TAPD接口文档.md @@ -0,0 +1,1218 @@ + + +**文档内地址为api.tapd.cn请修改为公司地址 https://tapd-api.bilibili.co/tapd** + +# 需求 + +# 需求(story)字段说明 + +## [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/story.html#需求重要字段说明)需求重要字段说明 + +| 字段 | 说明 | +| :-----------------: | :----------------------------------------------------------: | +| id | ID | +| name | 标题 | +| priority | 优先级 | +| priority_label | 优先级 | +| business_value | 业务价值 | +| status | 状态 | +| version | 版本 | +| module | 模块 | +| test_focus | 测试重点 | +| size | 规模 | +| owner | 处理人 | +| cc | 抄送人 | +| creator | 创建人 | +| developer | 开发人员 | +| begin | 预计开始 | +| due | 预计结束 | +| created | 创建时间 | +| modified | 最后修改时间 | +| completed | 完成时间 | +| iteration_id | 迭代 | +| effort | 预估工时 | +| effort_completed | 完成工时 | +| remain | 剩余工时 | +| exceed | 超出工时 | +| category_id | 需求分类 | +| workitem_type_id | 需求类别 | +| release_id | 发布计划 | +| source | 来源 | +| type | 类型 | +| bug_id | 关联的bugID | +| parent_id | 父需求 | +| children_id | 子需求 | +| ancestor_id | 祖先ID | +| description | 详细描述 | +| workspace_id | 项目ID | +| created_from | 创建来源 | +| step | 流程节点 | +| path | 需求位置（到根需求的直系父需求ID组成） | +| level | 需求层级（到根需求的直系父需求数量） | +| templated_id | 模板ID | +| feature | 特性 | +| label | 标签 | +| progress | 进度 | +| is_archived | 是否归档 | +| tech_risk | 技术风险 | +| business_value | 业务价值 | +| flows | 状态流转步骤快照 | +| secret_root_id | 需求保密根节点 | +| progress_manual | 进度（可忽略，已废弃） | +| priority_label | 自定义计划应用名称 | +| custom_field_* | 自定义字段参数，具体字段名通过接口 [获取需求自定义字段配置](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/get_story_custom_fields_settings.html) 获取 | +| custom_plan_field_* | 自定义计划应用参数，具体字段名通过接口 [获取自定义计划应用](https://open.tapd.cn/document/api-doc/API文档/api_reference/iteration/get_plan_apps.html) 获取 | + +## [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/story.html#需求优先级-priority-取值字段说明)需求优先级(priority)取值字段说明 + +为了兼容自定义优先级，`请使用 priority_label 字段`，详情参考：[如何兼容自定义优先级](https://open.tapd.cn/document/api-doc/API文档/subject/custom_priority/) 。 + +## [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/story.html#其他字段)其他字段 + +status(状态)/ module(模块)/ iteration_id(迭代) 等字段可选值跟当前项目有关,属于动态可选值, 需要通过接口 [获取需求所有字段及候选值](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/get_story_fields_info.html)获取. + +## 创建需求 + +### url + +``` +https://api.tapd.cn/stories +``` + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#支持格式)支持格式 + +JSON/XML（默认JSON格式） + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#http请求方式)HTTP请求方式 + +POST + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#请求数限制)请求数限制 + +一次插入一条数据 + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#请求参数)请求参数 + +| 字段名 | 必选 | 类型及范围 | 说明 | +| :-----------------------------: | :--: | :---------------: | :----------------------------------------------------------: | +| workspace_id | `是` | integer | 项目ID | +| name | `是` | string | 标题 | +| priority | 否 | string | 优先级。为了兼容自定义优先级，`请使用 priority_label 字段`，详情参考：[如何兼容自定义优先级](https://open.tapd.cn/document/api-doc/API文档/subject/custom_priority/) | +| priority_label | 否 | string | 优先级。推荐使用这个字段 | +| business_value | 否 | integer | 业务价值 | +| version | 否 | string | 版本 | +| module | 否 | string | 模块 | +| test_focus | 否 | string | 测试重点 | +| size | 否 | integer | 规模 | +| owner | 否 | string | 处理人 | +| cc | 否 | string | 抄送人 | +| creator | 否 | string | 创建人 | +| developer | 否 | string | 开发人员 | +| begin | 否 | date | 预计开始 | +| due | 否 | date | 预计结束 | +| iteration_id | 否 | string | 迭代ID | +| templated_id | 否 | integer | 模板ID | +| parent_id | 否 | integer | 父需求ID | +| effort | 否 | string | 预估工时 | +| effort_completed | 否 | string | 完成工时 | +| remain | 否 | float | 剩余工时 | +| exceed | 否 | float | 超出工时 | +| category_id | 否 | integer | 需求分类 | +| workitem_type_id | 否 | integer | 需求类别 | +| release_id | 否 | integer | 发布计划 | +| source | 否 | string | 来源 | +| type | 否 | string | 类型 | +| feature | 否 | string | 特性 | +| tech_risk | 否 | string | 技术风险 | +| business_value | 否 | string | 业务价值 | +| description | 否 | string | 详细描述 | +| label | 否 | string | 标签，标签不存在时将自动创建，多个以英文坚线分格 | +| cus_{$自定义字段别名} | 否 | string | 自定义字段值，参数名会由后台自动转义为custom_field_*，如：cus_自定义字段的名称 | +| custom_field_* | 否 | string或者integer | 自定义字段参数，具体字段名通过接口 [获取需求自定义字段配置](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/get_story_custom_fields_settings.html) 获取 | +| custom_plan_field_* | 否 | string或者integer | 自定义计划应用参数，具体字段名通过接口 [获取自定义计划应用](https://open.tapd.cn/document/api-doc/API文档/api_reference/iteration/get_plan_apps.html) 获取 | +| is_apply_template_default_value | 否 | integer | 是否从模板继承默认值、保密设置（传值=1继承模板默认值） | +| apply_template | 否 | string | 模版选项,支持多个选项传入,使用','隔开 如: "option1,option2" 当前支持参数:preset_stories(支持创建需求模板预设子需求),preset_tasks(支持创建需求模板预设子任务) | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#调用示例及返回结果)调用示例及返回结果 + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#在项目下创建需求)在项目下创建需求 + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#curl-使用-basic-auth-鉴权调用示例)curl 使用 Basic Auth 鉴权调用示例 + +``` +curl -u 'api_user:api_password' -d 'name=story_created_by_api&workspace_id=10158231&cus_自定义字段的名称=custom_field_value' 'https://api.tapd.cn/stories' +``` + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/story/add_story.html#返回结果)返回结果 + +```json +{ + "status": 1, + "data": { + "Story": { + "id": "1010104801124922063", + "workitem_type_id": "1010104801000022091", + "name": "story_created_by_api", + "description": null, + "workspace_id": "10104801", + "creator": "v_xuanfang", + "created": "2025-06-16 14:42:59", + "modified": "2025-06-16 14:42:59", + "status": "planning", + "step": "", + "owner": "", + "cc": "", + "begin": null, + "due": null, + "size": null, + "priority": "", + "developer": "", + "iteration_id": "0", + "test_focus": "", + "type": "", + "source": "", + "module": "", + "version": "", + "completed": null, + "category_id": "-1", + "path": "1010104801124922063:", + "parent_id": "0", + "children_id": "|", + "ancestor_id": "1010104801124922063", + "level": "0", + "business_value": null, + "effort": null, + "effort_completed": "0", + "exceed": "0", + "remain": "0", + "release_id": "0", + "bug_id": null, + "templated_id": null, + "created_from": "api", + "feature": "", + "label": "", + "progress": "0", + "is_archived": "0", + "tech_risk": null, + "flows": null, + "custom_field_one": "", + "custom_field_two": "", + "custom_field_three": "", + "custom_field_four": "", + "custom_field_five": "", + "custom_field_six": "", + "custom_field_seven": "", + "custom_field_eight": "", + "secret_root_id": "0", + "progress_manual": "0", + "custom_field_9": "", + "custom_field_10": "", + "custom_field_11": "", + "custom_field_12": "", + "custom_field_13": "", + "custom_field_14": "", + "custom_field_15": "", + "custom_field_16": "", + "custom_field_17": "", + "custom_field_18": "", + "custom_field_19": "", + "custom_field_20": "", + "custom_field_21": "", + "custom_field_22": "", + "custom_field_23": "", + "custom_field_24": "", + "custom_field_25": "", + "custom_field_26": "", + "custom_field_27": "", + "custom_field_28": "", + "custom_field_29": "", + "custom_field_30": "", + "custom_field_31": "", + "custom_field_32": "", + "custom_field_33": "", + "custom_field_34": "", + "custom_field_35": "", + "custom_field_36": "", + "custom_field_37": "", + "custom_field_38": "", + "custom_field_39": "", + "custom_field_40": "", + "custom_field_41": "", + "custom_field_42": "", + "custom_field_43": "", + "custom_field_44": "", + "custom_field_45": "", + "custom_field_46": "", + "custom_field_47": "", + "custom_field_48": "", + "custom_field_49": "", + "custom_field_50": "", + "custom_field_51": "", + "custom_field_52": "", + "custom_field_53": "", + "custom_field_54": "", + "custom_field_55": "", + "custom_field_56": "", + "custom_field_57": "", + "custom_field_58": "", + "custom_field_59": "", + "custom_field_60": "", + "custom_field_61": "", + "custom_field_62": "", + "custom_field_63": "", + "custom_field_64": "", + "custom_field_65": "", + "custom_field_66": "", + "custom_field_67": "", + "custom_field_68": "", + "custom_field_69": "", + "custom_field_70": "", + "custom_field_71": "", + "custom_field_72": "", + "custom_field_73": "", + "custom_field_74": "", + "custom_field_75": "", + "custom_field_76": "", + "custom_field_77": "", + "custom_field_78": "", + "custom_field_79": "", + "custom_field_80": "", + "custom_field_81": "", + "custom_field_82": "", + "custom_field_83": "", + "custom_field_84": "", + "custom_field_85": "", + "custom_field_86": "", + "custom_field_87": "", + "custom_field_88": "", + "custom_field_89": "", + "custom_field_90": "", + "custom_field_91": "", + "custom_field_92": "", + "custom_field_93": "", + "custom_field_94": "", + "custom_field_95": "", + "custom_field_96": "", + "custom_field_97": "", + "custom_field_98": "", + "custom_field_99": "", + "custom_field_100": "", + "custom_field_101": "", + "custom_field_102": "", + "custom_field_103": "", + "custom_field_104": "", + "custom_field_105": "", + "custom_field_106": "", + "custom_field_107": "", + "custom_field_108": "", + "custom_field_109": "", + "custom_field_110": "", + "custom_field_111": "", + "custom_field_112": "", + "custom_field_113": "", + "custom_field_114": "", + "custom_field_115": "", + "custom_field_116": "", + "custom_field_117": "", + "custom_field_118": "", + "custom_field_119": "", + "custom_field_120": "", + "custom_field_121": "", + "custom_field_122": "", + "custom_field_123": "", + "custom_field_124": "", + "custom_field_125": "", + "custom_field_126": "", + "custom_field_127": "", + "custom_field_128": "", + "custom_field_129": "", + "custom_field_130": "", + "custom_field_131": "", + "custom_field_132": "", + "custom_field_133": "", + "custom_field_134": "", + "custom_field_135": "", + "custom_field_136": "", + "custom_field_137": "", + "custom_field_138": "", + "custom_field_139": "", + "custom_field_140": "", + "custom_field_141": "", + "custom_field_142": "", + "custom_field_143": "", + "custom_field_144": "", + "custom_field_145": "", + "custom_field_146": "", + "custom_field_147": "", + "custom_field_148": "", + "custom_field_149": "", + "custom_field_150": "", + "custom_field_151": "", + "custom_field_152": "", + "custom_field_153": "", + "custom_field_154": "", + "custom_field_155": "", + "custom_field_156": "", + "custom_field_157": "", + "custom_field_158": "", + "custom_field_159": "", + "custom_field_160": "", + "custom_field_161": "", + "custom_field_162": "", + "custom_field_163": "", + "custom_field_164": "", + "custom_field_165": "", + "custom_field_166": "", + "custom_field_167": "", + "custom_field_168": "", + "custom_field_169": "", + "custom_field_170": "", + "custom_field_171": "", + "custom_field_172": "", + "custom_field_173": "", + "custom_field_174": "", + "custom_field_175": "", + "custom_field_176": "", + "custom_field_177": "", + "custom_field_178": "", + "custom_field_179": "", + "custom_field_180": "", + "custom_field_181": "", + "custom_field_182": "", + "custom_field_183": "", + "custom_field_184": "", + "custom_field_185": "", + "custom_field_186": "", + "custom_field_187": "", + "custom_field_188": "", + "custom_field_189": "", + "custom_field_190": "", + "custom_field_191": "", + "custom_field_192": "", + "custom_field_193": "", + "custom_field_194": "", + "custom_field_195": "", + "custom_field_196": "", + "custom_field_197": "", + "custom_field_198": "", + "custom_field_199": "", + "custom_field_200": "", + "custom_plan_field_1": "0", + "custom_plan_field_2": "0", + "custom_plan_field_3": "0", + "custom_plan_field_4": "0", + "custom_plan_field_5": "0", + "custom_plan_field_6": "0", + "custom_plan_field_7": "0", + "custom_plan_field_8": "0", + "custom_plan_field_9": "0", + "custom_plan_field_10": "0", + "priority_label": "" + } + }, + "info": "success" +} +``` + +# 缺陷 + +## 缺陷重要字段说明 + +| 字段 | 说明 | +| :--------------: | :----------: | +| id | ID | +| title | 标题 | +| priority | 优先级 | +| priority_label | 优先级 | +| severity | 严重程度 | +| status | 状态 | +| iteration_id | 迭代 | +| module | 模块 | +| feature | 特性 | +| release_id | 发布计划 | +| version_report | 发现版本 | +| version_test | 验证版本 | +| version_fix | 合入版本 | +| version_close | 关闭版本 | +| baseline_find | 发现基线 | +| baseline_join | 合入基线 | +| baseline_test | 验证基线 | +| baseline_close | 关闭基线 | +| current_owner | 处理人 | +| cc | 抄送人 | +| reporter | 创建人 | +| participator | 参与人 | +| te | 测试人员 | +| de | 开发人员 | +| auditer | 审核人 | +| confirmer | 验证人 | +| fixer | 修复人 | +| closer | 关闭人 | +| lastmodify | 最后修改人 | +| size | 规模 | +| created | 创建时间 | +| in_progress_time | 接受处理时间 | +| resolved | 解决时间 | +| verify_time | 验证时间 | +| closed | 关闭时间 | +| reject_time | 拒绝时间 | +| modified | 最后修改时间 | +| begin | 预计开始 | +| due | 预计结束 | +| deadline | 解决期限 | +| os | 操作系统 | +| platform | 软件平台 | +| testmode | 测试方式 | +| testphase | 测试阶段 | +| testtype | 测试类型 | +| source | 缺陷根源 | +| bugtype | 缺陷类型 | +| issue_id | 问题ID | +| frequency | 重现规律 | +| originphase | 发现阶段 | +| sourcephase | 引入阶段 | +| resolution | 解决方法 | +| estimate | 预计解决时间 | +| description | 详细描述 | +| workspace_id | 项目ID | +| effort | 预估工时 | +| effort_completed | 完成工时 | +| remain | 剩余工时 | +| exceed | 超出工时 | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/bug.html#常用字段候选值映射)常用字段候选值映射 + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/bug.html#缺陷优先级-priority-字段说明)缺陷优先级(priority)字段说明 + +为了兼容自定义优先级，`请使用 priority_label 字段`，详情参考：[如何兼容自定义优先级](https://open.tapd.cn/document/api-doc/API文档/subject/custom_priority/) 。`下面取值将不再使用`。 + +| 取值 | 字面值 | +| :-----------: | :------: | +| urgent | 紧急 | +| high | 高 | +| medium | 中 | +| low | 低 | +| insignificant | 无关紧要 | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/bug.html#缺陷严重程度-severity-字段说明)缺陷严重程度(severity)字段说明 + +| 取值 | 字面值 | +| :-----: | :----: | +| fatal | 致命 | +| serious | 严重 | +| normal | 一般 | +| prompt | 提示 | +| advice | 建议 | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/bug.html#缺陷解决方法-resolution-字段说明)缺陷解决方法(resolution)字段说明 + +| 取值 | 字面值 | +| :------------------: | :------------: | +| ignore | 无需解决 | +| fix | 延期解决 | +| failed | 无法重现 | +| external | 外部原因 | +| duplicated | 重复 | +| intentional | 设计如此 | +| unclear | 问题描述不准确 | +| hold | 挂起 | +| feature | 需求变更 | +| fixed | 已解决 | +| transferred to story | 已转需求 | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/bug.html#其他字段)其他字段 + +status(状态)/ module(模块)/ iteration_id(迭代) 等字段可选值跟当前项目有关,属于动态可选值, 需要通过接口 [获取缺陷所有字段及候选值](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bug_fields_info.html)获取. + +## 创建缺陷（bug） + +### url + +``` +https://api.tapd.cn/bugs +``` + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#支持格式)支持格式 + +JSON/XML（默认JSON格式） + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#http请求方式)HTTP请求方式 + +POST + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#请求数限制)请求数限制 + +一次插入一条数据 + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#请求参数)请求参数 + +| 字段名 | 必选 | 类型及范围 | 说明 | +| :-----------------------------: | :--: | :---------------: | :----------------------------------------------------------: | +| workspace_id | `是` | integer | 项目ID | +| title | `是` | string | 缺陷标题 | +| priority | 否 | string | 优先级。为了兼容自定义优先级，`请使用 priority_label 字段`，详情参考：[如何兼容自定义优先级](https://open.tapd.cn/document/api-doc/API文档/subject/custom_priority/) | +| priority_label | 否 | string | 优先级。推荐使用这个字段 | +| severity | 否 | string | 严重程度 | +| module | 否 | string | 模块 | +| feature | 否 | string | 特性 | +| release_id | 否 | integer | 发布计划 | +| version_report | 否 | string | 发现版本 | +| version_test | 否 | string | 验证版本 | +| version_fix | 否 | string | 合入版本 | +| version_close | 否 | string | 关闭版本 | +| baseline_find | 否 | string | 发现基线 | +| baseline_join | 否 | string | 合入基线 | +| baseline_test | 否 | string | 验证基线 | +| baseline_close | 否 | string | 关闭基线 | +| current_owner | 否 | string | 处理人 | +| template_id | 否 | integer | 模板ID | +| cc | 否 | string | 抄送人 | +| reporter | 否 | string | 创建人 | +| participator | 否 | string | 参与人 | +| te | 否 | string | 测试人员 | +| de | 否 | string | 开发人员 | +| auditer | 否 | string | 审核人 | +| confirmer | 否 | string | 验证人 | +| fixer | 否 | string | 修复人 | +| closer | 否 | string | 关闭人 | +| lastmodify | 否 | string | 最后修改人 | +| in_progress_time | 否 | datetime | 接受处理时间 | +| verify_time | 否 | datetime | 验证时间 | +| reject_time | 否 | datetime | 拒绝时间 | +| begin | 否 | date | 预计开始 | +| due | 否 | date | 预计结束 | +| deadline | 否 | date | 解决期限 | +| iteration_id | 否 | string | 迭代ID | +| size | 否 | string | 规模 | +| os | 否 | string | 操作系统 | +| platform | 否 | string | 软件平台 | +| testmode | 否 | string | 测试方式 | +| testphase | 否 | string | 测试阶段 | +| testtype | 否 | string | 测试类型 | +| source | 否 | string | 缺陷根源 | +| bugtype | 否 | string | 缺陷类型 | +| frequency | 否 | string | 重现规律 | +| originphase | 否 | string | 发现阶段 | +| sourcephase | 否 | string | 引入阶段 | +| resolution | 否 | string | 解决方法 | +| estimate | 否 | integer | 预计解决时间 | +| description | 否 | string | 详细描述 | +| label | 否 | string | 标签，标签不存在时将自动创建，多个以英文坚线分格 | +| effort | 否 | integer | 预估工时 | +| is_apply_template_default_value | 否 | integer | 是否从模板继承默认值（传值=1继承模板默认值） | +| cus_{$自定义字段别名} | 否 | string | 缺陷自定义字段值，参数名会由后台自动转义为custom_field_*，如：cus_自定义字段的名称 | +| custom_field_* | 否 | string或者integer | 缺陷自定义字段参数，具体字段名通过接口 [获取缺陷自定义字段配置](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bug_custom_fields_settings.html) 获取 | +| custom_plan_field_* | 否 | string或者integer | 自定义计划应用参数，具体字段名通过接口 [获取自定义计划应用](https://open.tapd.cn/document/api-doc/API文档/api_reference/iteration/get_plan_apps.html) 获取 | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#调用示例及返回结果)调用示例及返回结果 + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#在项目下创建缺陷)在项目下创建缺陷 + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#curl-使用-basic-auth-鉴权调用示例)curl 使用 Basic Auth 鉴权调用示例 + +``` +curl -u 'api_user:api_password' -d 'title=bug_created_by_api&workspace_id=10158231&cus_自定义字段的名称=custom_field_value' 'https://api.tapd.cn/bugs' +``` + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#返回结果)返回结果 + +```json +{ + "status": 1, + "data": { + "Bug": { + "id": "1010158231500643487", + "title": "bug_created_by_api", + "description": null, + "priority": "", + "severity": "", + "module": null, + "status": "new", + "reporter": "api_doc_oauth", + "deadline": null, + "created": "2019-06-27 14:19:47", + "bugtype": "", + "resolved": null, + "closed": null, + "modified": "2019-06-27 14:19:47", + "lastmodify": "api_doc_oauth", + "auditer": null, + "de": null, + "fixer": null, + "version_test": "", + "version_report": "", + "version_close": "", + "version_fix": "", + "baseline_find": "", + "baseline_join": "", + "baseline_close": "", + "baseline_test": "", + "sourcephase": "", + "te": null, + "current_owner": null, + "iteration_id": "0", + "resolution": "", + "source": "", + "originphase": "", + "confirmer": null, + "milestone": null, + "participator": null, + "closer": null, + "platform": "", + "os": "", + "testtype": "", + "testphase": "", + "frequency": "", + "cc": null, + "regression_number": "0", + "flows": "new", + "feature": null, + "testmode": "", + "estimate": null, + "issue_id": null, + "created_from": "api", + "in_progress_time": null, + "verify_time": null, + "reject_time": null, + "reopen_time": null, + "audit_time": null, + "suspend_time": null, + "due": null, + "begin": null, + "release_id": null, + "label": "阻塞|延期", + "effort": null, + "effort_completed": "0", + "exceed": "0", + "remain": "0", + "cus_自定义字段的名称": "custom_field_value", + "custom_field_one": "", + "custom_field_two": "", + "custom_field_three": "", + "custom_field_four": "", + "custom_field_five": "", + "custom_field_6": "", + "custom_field_7": "", + "custom_field_8": "", + "custom_field_9": "", + "custom_field_10": "", + "custom_field_11": "", + "custom_field_12": "", + "custom_field_13": "", + "custom_field_14": "", + "custom_field_15": "", + "custom_field_16": "", + "custom_field_17": "", + "custom_field_18": "", + "custom_field_19": "", + "custom_field_20": "", + "custom_field_21": "", + "custom_field_22": "", + "custom_field_23": "", + "custom_field_24": "", + "custom_field_25": "", + "custom_field_26": "", + "custom_field_27": "", + "custom_field_28": "", + "custom_field_29": "", + "custom_field_30": "", + "custom_field_31": "", + "custom_field_32": "", + "custom_field_33": "", + "custom_field_34": "", + "custom_field_35": "", + "custom_field_36": "", + "custom_field_37": "", + "custom_field_38": "", + "custom_field_39": "", + "custom_field_40": "", + "custom_field_41": "", + "custom_field_42": "", + "custom_field_43": "", + "custom_field_44": "", + "custom_field_45": "", + "custom_field_46": "", + "custom_field_47": "", + "custom_field_48": "", + "custom_field_49": "", + "custom_field_50": "", + "workspace_id": "10158231" + } + }, + "info": "success" +} +``` + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#在项目下创建一张带-tapd-cn-logo-、优先级为高的缺陷)在项目下创建一张带 tapd.cn logo 、优先级为高的缺陷 + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#curl-使用-basic-auth-鉴权调用示例-2)curl 使用 Basic Auth 鉴权调用示例 + +``` +curl -u 'api_user:api_password' -d 'title=tapd_logo&description=&priority=high&workspace_id=10158231' 'https://api.tapd.cn/bugs' +``` + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/add_bug.html#返回结果-2)返回结果 + +```json +{ + "status": 1, + "data": { + "Bug": { + "id": "1010158231500643491", + "title": "tapd_logo", + "description": "", + "priority": "high", + "severity": "", + "module": null, + "status": "new", + "reporter": "api_doc_oauth", + "deadline": null, + "created": "2019-06-27 14:19:48", + "bugtype": "", + "resolved": null, + "closed": null, + "modified": "2019-06-27 14:19:48", + "lastmodify": "api_doc_oauth", + "auditer": null, + "de": null, + "fixer": null, + "version_test": "", + "version_report": "", + "version_close": "", + "version_fix": "", + "baseline_find": "", + "baseline_join": "", + "baseline_close": "", + "baseline_test": "", + "sourcephase": "", + "te": null, + "current_owner": null, + "iteration_id": "0", + "resolution": "", + "source": "", + "originphase": "", + "confirmer": null, + "milestone": null, + "participator": null, + "closer": null, + "platform": "", + "os": "", + "testtype": "", + "testphase": "", + "frequency": "", + "cc": null, + "regression_number": "0", + "flows": "new", + "feature": null, + "testmode": "", + "estimate": null, + "issue_id": null, + "created_from": "api", + "in_progress_time": null, + "verify_time": null, + "reject_time": null, + "reopen_time": null, + "audit_time": null, + "suspend_time": null, + "due": null, + "begin": null, + "release_id": null, + "custom_field_one": "", + "custom_field_two": "", + "custom_field_three": "", + "custom_field_four": "", + "custom_field_five": "", + "custom_field_6": "", + "custom_field_7": "", + "custom_field_8": "", + "custom_field_9": "", + "custom_field_10": "", + "custom_field_11": "", + "custom_field_12": "", + "custom_field_13": "", + "custom_field_14": "", + "custom_field_15": "", + "custom_field_16": "", + "custom_field_17": "", + "custom_field_18": "", + "custom_field_19": "", + "custom_field_20": "", + "custom_field_21": "", + "custom_field_22": "", + "custom_field_23": "", + "custom_field_24": "", + "custom_field_25": "", + "custom_field_26": "", + "custom_field_27": "", + "custom_field_28": "", + "custom_field_29": "", + "custom_field_30": "", + "custom_field_31": "", + "custom_field_32": "", + "custom_field_33": "", + "custom_field_34": "", + "custom_field_35": "", + "custom_field_36": "", + "custom_field_37": "", + "custom_field_38": "", + "custom_field_39": "", + "custom_field_40": "", + "custom_field_41": "", + "custom_field_42": "", + "custom_field_43": "", + "custom_field_44": "", + "custom_field_45": "", + "custom_field_46": "", + "custom_field_47": "", + "custom_field_48": "", + "custom_field_49": "", + "custom_field_50": "", + "workspace_id": "10158231" + } + }, + "info": "success" +} +``` + + + +## 获取缺陷 + +### 说明 + +返回符合查询条件的所有缺陷（分页显示，默认一页30条） + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#url)url + +``` +https://api.tapd.cn/bugs +``` + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#支持格式)支持格式 + +JSON/XML（默认JSON格式） + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#http请求方式)HTTP请求方式 + +GET + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#请求数限制)请求数限制 + +默认返回 30 条。可通过传 limit 参数设置，最大取 200。也可以传 page 参数翻页 + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#请求参数)请求参数 + +| 字段名 | 必选 | 类型及范围 | 说明 | 特殊规则 | +| :-----------------: | :--: | :---------------: | :----------------------------------------------------------: | :------------------------------------: | +| id | 否 | integer | ID | 支持多ID查询 | +| title | 否 | string | 标题 | 支持模糊匹配 | +| priority | 否 | string | 优先级。为了兼容自定义优先级，`请使用 priority_label 字段`，详情参考：[如何兼容自定义优先级](https://open.tapd.cn/document/api-doc/API文档/subject/custom_priority/) | | +| priority_label | 否 | string | 优先级。推荐使用这个字段 | | +| severity | 否 | string | 严重程度 | 支持枚举查询 | +| status | 否 | string | 状态 | 支持不等于查询、枚举查询 | +| v_status | 否 | string | 状态(支持传入中文状态名称) | | +| label | 否 | string | 标签查询 | 支持枚举查询 | +| iteration_id | 否 | string | 迭代 | 支持枚举查询 | +| module | 否 | string | 模块 | 支持枚举查询 | +| release_id | 否 | integer | 发布计划 | | +| version_report | 否 | string | 发现版本 | 枚举查询 | +| version_test | 否 | string | 验证版本 | | +| version_fix | 否 | string | 合入版本 | | +| version_close | 否 | string | 关闭版本 | | +| baseline_find | 否 | string | 发现基线 | | +| baseline_join | 否 | string | 合入基线 | | +| baseline_test | 否 | string | 验证基线 | | +| baseline_close | 否 | string | 关闭基线 | | +| feature | 否 | string | 特性 | | +| current_owner | 否 | string | 处理人 | 支持模糊匹配 | +| cc | 否 | string | 抄送人 | | +| reporter | 否 | string | 创建人 | 支持多人员查询 | +| participator | 否 | string | 参与人 | 支持多人员查询 | +| te | 否 | string | 测试人员 | 支持模糊匹配 | +| de | 否 | string | 开发人员 | 支持模糊匹配 | +| auditer | 否 | string | 审核人 | | +| confirmer | 否 | string | 验证人 | | +| fixer | 否 | string | 修复人 | | +| closer | 否 | string | 关闭人 | | +| lastmodify | 否 | string | 最后修改人 | | +| created | 否 | datetime | 创建时间 | 支持时间查询 | +| in_progress_time | 否 | datetime | 接受处理时间 | 支持时间查询 | +| resolved | 否 | datetime | 解决时间 | 支持时间查询 | +| verify_time | 否 | datetime | 验证时间 | 支持时间查询 | +| closed | 否 | datetime | 关闭时间 | 支持时间查询 | +| reject_time | 否 | datetime | 拒绝时间 | 支持时间查询 | +| modified | 否 | datetime | 最后修改时间 | 支持时间查询 | +| begin | 否 | date | 预计开始 | | +| due | 否 | date | 预计结束 | | +| deadline | 否 | date | 解决期限 | | +| os | 否 | string | 操作系统 | | +| size | 否 | string | 规模 | | +| platform | 否 | string | 软件平台 | | +| testmode | 否 | string | 测试方式 | | +| testphase | 否 | string | 测试阶段 | | +| testtype | 否 | string | 测试类型 | | +| source | 否 | string | 缺陷根源 | 支持枚举查询 | +| bugtype | 否 | string | 缺陷类型 | | +| frequency | 否 | string | 重现规律 | 支持枚举查询 | +| originphase | 否 | string | 发现阶段 | | +| sourcephase | 否 | string | 引入阶段 | | +| resolution | 否 | string | 解决方法 | 支持枚举查询 | +| estimate | 否 | integer | 预计解决时间 | | +| description | 否 | string | 详细描述 | 支持模糊匹配 | +| workspace_id | `是` | integer | 项目ID | | +| custom_field_* | 否 | string或者integer | 自定义字段参数，具体字段名通过接口 [获取缺陷自定义字段配置](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bug_custom_fields_settings.html) 获取 | 支持枚举查询 | +| custom_plan_field_* | 否 | string或者integer | 自定义计划应用参数，具体字段名通过接口 [获取自定义计划应用](https://open.tapd.cn/document/api-doc/API文档/api_reference/iteration/get_plan_apps.html) 获取 | | +| limit | 否 | integer | 设置返回数量限制，默认为30 | | +| page | 否 | integer | 返回当前数量限制下第N页的数据，默认为1（第一页） | | +| order | 否 | string | 排序规则，规则：字段名 ASC或者DESC，然后 urlencode | 如按创建时间逆序：order=created%20desc | +| fields | 否 | string | 设置获取的字段，多个字段间以','逗号隔开 | | + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#调用示例及返回结果)调用示例及返回结果 + +### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#获取项目下的缺陷数据)获取项目下的缺陷数据 + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#curl-使用-basic-auth-鉴权调用示例)curl 使用 Basic Auth 鉴权调用示例 + +``` +curl -u 'api_user:api_password' 'https://api.tapd.cn/bugs?workspace_id=10158231&limit=2' +``` + +#### [#](https://open.tapd.cn/document/api-doc/API文档/api_reference/bug/get_bugs.html#返回结果)返回结果 + +```json +{ + "status": 1, + "data": [ + { + "Bug": { + "id": "1010158231500628817", + "title": "【示例】新官网Chrome浏览器兼容性bug", + "description": null, + "priority": "high", + "severity": "prompt", + "module": null, + "status": "in_progress", + "reporter": "anyechen", + "deadline": null, + "created": "2017-06-20 16:49:19", + "bugtype": "", + "resolved": null, + "closed": null, + "modified": "2018-01-12 14:45:27", + "lastmodify": "anyechen", + "auditer": null, + "de": null, + "fixer": null, + "version_test": "", + "version_report": "版本1", + "version_close": "", + "version_fix": "", + "baseline_find": "", + "baseline_join": "", + "baseline_close": "", + "baseline_test": "", + "sourcephase": "", + "te": null, + "current_owner": null, + "iteration_id": "0", + "resolution": "", + "source": "", + "originphase": "", + "confirmer": null, + "milestone": null, + "participator": null, + "closer": null, + "platform": "", + "os": "", + "testtype": "", + "testphase": "", + "frequency": "", + "cc": null, + "regression_number": "0", + "flows": "new", + "feature": null, + "testmode": "", + "estimate": null, + "issue_id": null, + "created_from": null, + "in_progress_time": null, + "verify_time": null, + "reject_time": null, + "reopen_time": null, + "audit_time": null, + "suspend_time": null, + "due": null, + "begin": null, + "release_id": null, + "label": "阻塞|重点关注", + "custom_field_one": "", + "custom_field_two": "", + "custom_field_three": "", + "custom_field_four": "", + "custom_field_five": "", + "custom_field_6": "", + "custom_field_7": "", + "custom_field_8": "", + "custom_field_9": "", + "custom_field_10": "", + "custom_field_11": "", + "custom_field_12": "", + "custom_field_13": "", + "custom_field_14": "", + "custom_field_15": "", + "custom_field_16": "", + "custom_field_17": "", + "custom_field_18": "", + "custom_field_19": "", + "custom_field_20": "", + "custom_field_21": "", + "custom_field_22": "", + "custom_field_23": "", + "custom_field_24": "", + "custom_field_25": "", + "custom_field_26": "", + "custom_field_27": "", + "custom_field_28": "", + "custom_field_29": "", + "custom_field_30": "", + "custom_field_31": "", + "custom_field_32": "", + "custom_field_33": "", + "custom_field_34": "", + "custom_field_35": "", + "custom_field_36": "", + "custom_field_37": "", + "custom_field_38": "", + "custom_field_39": "", + "custom_field_40": "", + "custom_field_41": "", + "custom_field_42": "", + "custom_field_43": "", + "custom_field_44": "", + "custom_field_45": "", + "custom_field_46": "", + "custom_field_47": "", + "custom_field_48": "", + "custom_field_49": "", + "custom_field_50": "", + "workspace_id": "10158231" + } + }, + { + "Bug": { + "id": "1010158231500628815", + "title": "【示例】新官网页面宽度自适应bug", + "description": null, + "priority": "medium", + "severity": "normal", + "module": null, + "status": "new", + "reporter": "anyechen", + "deadline": null, + "created": "2017-06-20 16:49:19", + "bugtype": "", + "resolved": null, + "closed": null, + "modified": "2017-06-20 16:49:19", + "lastmodify": "ruirayli", + "auditer": null, + "de": null, + "fixer": null, + "version_test": "", + "version_report": "版本1", + "version_close": "", + "version_fix": "", + "baseline_find": "", + "baseline_join": "", + "baseline_close": "", + "baseline_test": "", + "sourcephase": "", + "te": null, + "current_owner": null, + "iteration_id": "0", + "resolution": "", + "source": "", + "originphase": "", + "confirmer": null, + "milestone": null, + "participator": null, + "closer": null, + "platform": "", + "os": "", + "testtype": "", + "testphase": "", + "frequency": "", + "cc": null, + "regression_number": "0", + "flows": "new", + "feature": null, + "testmode": "", + "estimate": null, + "issue_id": null, + "created_from": null, + "in_progress_time": null, + "verify_time": null, + "reject_time": null, + "reopen_time": null, + "audit_time": null, + "suspend_time": null, + "due": null, + "begin": null, + "release_id": null, + "custom_field_one": "", + "custom_field_two": "", + "custom_field_three": "", + "custom_field_four": "", + "custom_field_five": "", + "custom_field_6": "", + "custom_field_7": "", + "custom_field_8": "", + "custom_field_9": "", + "custom_field_10": "", + "custom_field_11": "", + "custom_field_12": "", + "custom_field_13": "", + "custom_field_14": "", + "custom_field_15": "", + "custom_field_16": "", + "custom_field_17": "", + "custom_field_18": "", + "custom_field_19": "", + "custom_field_20": "", + "custom_field_21": "", + "custom_field_22": "", + "custom_field_23": "", + "custom_field_24": "", + "custom_field_25": "", + "custom_field_26": "", + "custom_field_27": "", + "custom_field_28": "", + "custom_field_29": "", + "custom_field_30": "", + "custom_field_31": "", + "custom_field_32": "", + "custom_field_33": "", + "custom_field_34": "", + "custom_field_35": "", + "custom_field_36": "", + "custom_field_37": "", + "custom_field_38": "", + "custom_field_39": "", + "custom_field_40": "", + "custom_field_41": "", + "custom_field_42": "", + "custom_field_43": "", + "custom_field_44": "", + "custom_field_45": "", + "custom_field_46": "", + "custom_field_47": "", + "custom_field_48": "", + "custom_field_49": "", + "custom_field_50": "", + "workspace_id": "10158231" + } + } + ], + "info": "success" +} +``` \ No newline at end of file diff --git a/config/config.ini b/config/config.ini new file mode 100644 index 0000000..62e6349 --- /dev/null +++ b/config/config.ini @@ -0,0 +1,9 @@ +# autoTAPD 配置文件 + +[TAPD] +# TAPD项目ID +workspace_id = 58335167 + +[SmartSheet] +# 智能表格文档ID +docid = dcRybSHojZR9-b5ePgDp33yr29bQy6BtQiVJ-nSGUM-ot6FSpq-TGW9jEn_f7ORLcFWRj9zvxtB1PP_TE29qPoAw diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..d6937f0 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,13 @@ +# 企业微信智能表格API测试工具依赖包 + +# HTTP请求库 +requests>=2.31.0 + +# JSON处理（Python内置，无需安装） +# json + +# 日期时间处理（Python内置，无需安装） +# datetime + +# 操作系统接口（Python内置，无需安装） +# os diff --git a/src/__init__.py b/src/__init__.py new file mode 100644 index 0000000..5905df2 --- /dev/null +++ b/src/__init__.py @@ -0,0 +1,7 @@ +""" +autoTAPD - Debug阶段自动开单工具 +从腾讯智能表格读取bug信息，自动在TAPD创建bug单 +""" + +__version__ = "0.1.0" +__author__ = "autoTAPD Team" diff --git a/src/api_test.py b/src/api_test.py new file mode 100644 index 0000000..220a99a --- /dev/null +++ b/src/api_test.py @@ -0,0 +1,372 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +""" +企业微信智能表格API测试工具 +用于测试和熟悉企业微信文档API接口 +""" + +import requests +import json +import os +from datetime import datetime + + +class WeWorkAPITester: + """企业微信API测试类""" + + def __init__(self): + self.access_token = None + self.log_file = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'logs', 'api_test_log.json') + self.base_url = "https://qyapi.weixin.qq.com/cgi-bin" + + # 确保日志文件存在 + self._init_log_file() + + def _init_log_file(self): + """初始化日志文件""" + if not os.path.exists(self.log_file): + with open(self.log_file, 'w', encoding='utf-8') as f: + json.dump({"records": []}, f, ensure_ascii=False, indent=2) + + def _log_api_call(self, operation, request_data, response_data): + """记录API调用到JSON文件""" + try: + # 读取现有记录 + with open(self.log_file, 'r', encoding='utf-8') as f: + log_data = json.load(f) + + # 添加新记录 + record = { + "operation": operation, + "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"), + "request": request_data, + "response": response_data + } + log_data["records"].append(record) + + # 写回文件 + with open(self.log_file, 'w', encoding='utf-8') as f: + json.dump(log_data, f, ensure_ascii=False, indent=2) + + print(f"✓ API调用已记录到日志文件") + except Exception as e: + print(f"✗ 记录日志失败: {str(e)}") + + def get_access_token(self, corpid, corpsecret): + """ + 获取access_token + + Args: + corpid: 企业ID + corpsecret: 应用的凭证密钥 + + Returns: + bool: 是否成功获取token + """ + print("\n=== 获取access_token ===") + + url = f"{self.base_url}/gettoken" + params = { + "corpid": corpid, + "corpsecret": corpsecret + } + + try: + response = requests.get(url, params=params, timeout=10) + response_data = response.json() + + # 记录API调用 + request_data = { + "url": url, + "params": { + "corpid": corpid, + "corpsecret": "***" # 隐藏敏感信息 + } + } + self._log_api_call("get_access_token", request_data, response_data) + + # 检查返回结果 + if response_data.get("errcode") == 0: + self.access_token = response_data.get("access_token") + expires_in = response_data.get("expires_in") + print(f"✓ 成功获取access_token") + print(f" Token: {self.access_token[:20]}...") + print(f" 有效期: {expires_in}秒 ({expires_in//60}分钟)") + return True + else: + print(f"✗ 获取失败") + print(f" 错误码: {response_data.get('errcode')}") + print(f" 错误信息: {response_data.get('errmsg')}") + return False + + except Exception as e: + print(f"✗ 请求异常: {str(e)}") + return False + + def create_doc(self, doc_name, doc_type=10, spaceid=None, fatherid=None): + """ + 新建文档 + + Args: + doc_name: 文档名称 + doc_type: 文档类型 (3:文档 4:表格 10:智能表格) + spaceid: 空间ID (可选) + fatherid: 父目录ID (可选) + + Returns: + dict: 包含docid和url的字典，失败返回None + """ + print("\n=== 新建文档 ===") + + if not self.access_token: + print("✗ 请先获取access_token") + return None + + url = f"{self.base_url}/wedoc/create_doc" + params = {"access_token": self.access_token} + + # 构造请求体 + data = { + "doc_type": doc_type, + "doc_name": doc_name + } + if spaceid: + data["spaceid"] = spaceid + if fatherid: + data["fatherid"] = fatherid + + try: + response = requests.post(url, params=params, json=data, timeout=10) + response_data = response.json() + + # 记录API调用 + request_data = { + "url": url, + "params": {"access_token": "***"}, + "body": data + } + self._log_api_call("create_doc", request_data, response_data) + + # 检查返回结果 + if response_data.get("errcode") == 0: + docid = response_data.get("docid") + doc_url = response_data.get("url") + print(f"✓ 文档创建成功") + print(f" 文档名称: {doc_name}") + print(f" 文档ID: {docid}") + print(f" 访问链接: {doc_url}") + return {"docid": docid, "url": doc_url} + else: + print(f"✗ 创建失败") + print(f" 错误码: {response_data.get('errcode')}") + print(f" 错误信息: {response_data.get('errmsg')}") + return None + + except Exception as e: + print(f"✗ 请求异常: {str(e)}") + return None + + def rename_doc(self, docid, new_name): + """ + 重命名文档 + + Args: + docid: 文档ID + new_name: 新的文档名称 + + Returns: + bool: 是否成功 + """ + print("\n=== 重命名文档 ===") + + if not self.access_token: + print("✗ 请先获取access_token") + return False + + url = f"{self.base_url}/wedoc/rename_doc" + params = {"access_token": self.access_token} + data = { + "docid": docid, + "new_name": new_name + } + + try: + response = requests.post(url, params=params, json=data, timeout=10) + response_data = response.json() + + # 记录API调用 + request_data = { + "url": url, + "params": {"access_token": "***"}, + "body": data + } + self._log_api_call("rename_doc", request_data, response_data) + + # 检查返回结果 + if response_data.get("errcode") == 0: + print(f"✓ 重命名成功") + print(f" 文档ID: {docid}") + print(f" 新名称: {new_name}") + return True + else: + print(f"✗ 重命名失败") + print(f" 错误码: {response_data.get('errcode')}") + print(f" 错误信息: {response_data.get('errmsg')}") + return False + + except Exception as e: + print(f"✗ 请求异常: {str(e)}") + return False + + def delete_doc(self, docid): + """ + 删除文档 + + Args: + docid: 文档ID + + Returns: + bool: 是否成功 + """ + print("\n=== 删除文档 ===") + + if not self.access_token: + print("✗ 请先获取access_token") + return False + + url = f"{self.base_url}/wedoc/del_doc" + params = {"access_token": self.access_token} + data = {"docid": docid} + + try: + response = requests.post(url, params=params, json=data, timeout=10) + response_data = response.json() + + # 记录API调用 + request_data = { + "url": url, + "params": {"access_token": "***"}, + "body": data + } + self._log_api_call("delete_doc", request_data, response_data) + + # 检查返回结果 + if response_data.get("errcode") == 0: + print(f"✓ 删除成功") + print(f" 文档ID: {docid}") + return True + else: + print(f"✗ 删除失败") + print(f" 错误码: {response_data.get('errcode')}") + print(f" 错误信息: {response_data.get('errmsg')}") + return False + + except Exception as e: + print(f"✗ 请求异常: {str(e)}") + return False + + +def print_menu(): + """打印菜单""" + print("\n" + "="*50) + print("企业微信智能表格API测试工具") + print("="*50) + print("1. 获取access_token") + print("2. 新建文档") + print("3. 重命名文档") + print("4. 删除文档") + print("5. 查看日志文件") + print("0. 退出") + print("="*50) + + +def main(): + """主函数""" + tester = WeWorkAPITester() + + while True: + print_menu() + choice = input("\n请选择操作 (0-5): ").strip() + + if choice == "0": + print("\n感谢使用，再见！") + break + + elif choice == "1": + print("\n请输入企业微信认证信息：") + corpid = input("企业ID (corpid): ").strip() + corpsecret = input("应用密钥 (corpsecret): ").strip() + + if corpid and corpsecret: + tester.get_access_token(corpid, corpsecret) + else: + print("✗ corpid和corpsecret不能为空") + + elif choice == "2": + doc_name = input("\n请输入文档名称: ").strip() + if not doc_name: + print("✗ 文档名称不能为空") + continue + + print("\n文档类型:") + print(" 3 - 文档") + print(" 4 - 表格") + print(" 10 - 智能表格 (默认)") + doc_type_input = input("请选择文档类型 (直接回车默认为10): ").strip() + doc_type = int(doc_type_input) if doc_type_input else 10 + + tester.create_doc(doc_name, doc_type) + + elif choice == "3": + docid = input("\n请输入文档ID: ").strip() + new_name = input("请输入新的文档名称: ").strip() + + if docid and new_name: + tester.rename_doc(docid, new_name) + else: + print("✗ 文档ID和新名称不能为空") + + elif choice == "4": + docid = input("\n请输入要删除的文档ID: ").strip() + + if docid: + confirm = input(f"确认要删除文档 {docid} 吗? (y/n): ").strip().lower() + if confirm == 'y': + tester.delete_doc(docid) + else: + print("已取消删除操作") + else: + print("✗ 文档ID不能为空") + + elif choice == "5": + print("\n=== 查看日志文件 ===") + try: + with open(tester.log_file, 'r', encoding='utf-8') as f: + log_data = json.load(f) + records = log_data.get("records", []) + + if not records: + print("日志文件为空") + else: + print(f"\n共有 {len(records)} 条记录\n") + for i, record in enumerate(records[-10:], 1): # 只显示最近10条 + print(f"记录 {i}:") + print(f" 操作: {record.get('operation')}") + print(f" 时间: {record.get('timestamp')}") + print(f" 响应: errcode={record.get('response', {}).get('errcode')}, " + f"errmsg={record.get('response', {}).get('errmsg')}") + print() + + if len(records) > 10: + print(f"(仅显示最近10条，完整日志请查看: {tester.log_file})") + except Exception as e: + print(f"✗ 读取日志文件失败: {str(e)}") + + else: + print("✗ 无效的选择，请重新输入") + + input("\n按回车键继续...") + + +if __name__ == "__main__": + main() diff --git a/src/config.py b/src/config.py new file mode 100644 index 0000000..1a92de9 --- /dev/null +++ b/src/config.py @@ -0,0 +1,143 @@ +""" +配置管理模块 +负责读取和管理config.ini配置文件 +""" + +import os +import configparser +from pathlib import Path + + +class ConfigManager: + """配置管理器""" + + def __init__(self, config_path=None): + """ + 初始化配置管理器 + + Args: + config_path: 配置文件路径，如果为None则使用默认路径 + """ + self.config = configparser.ConfigParser() + + # 确定配置文件路径 + if config_path is None: + # 默认路径：项目根目录/config/config.ini + project_root = Path(__file__).parent.parent + config_path = project_root / "config" / "config.ini" + + self.config_path = Path(config_path) + + # 读取配置文件 + self._load_config() + + def _load_config(self): + """加载配置文件""" + # 检查配置文件是否存在 + if not self.config_path.exists(): + raise FileNotFoundError( + f"配置文件不存在: {self.config_path}\n" + f"请确保配置文件存在于正确的位置。" + ) + + # 读取配置文件 + try: + self.config.read(self.config_path, encoding='utf-8') + print(f"成功加载配置文件: {self.config_path}") + except Exception as e: + raise RuntimeError(f"读取配置文件失败: {e}") + + def get_tapd_config(self): + """ + 获取TAPD配置 + + Returns: + dict: 包含workspace_id的字典 + + Raises: + ValueError: 配置项缺失时抛出 + """ + if not self.config.has_section('TAPD'): + raise ValueError("配置文件缺少[TAPD]节") + + if not self.config.has_option('TAPD', 'workspace_id'): + raise ValueError("配置文件[TAPD]节缺少workspace_id配置项") + + workspace_id = self.config.get('TAPD', 'workspace_id').strip() + if not workspace_id: + raise ValueError("workspace_id配置项不能为空") + + return { + 'workspace_id': workspace_id + } + + def get_smartsheet_config(self): + """ + 获取智能表格配置 + + Returns: + dict: 包含docid的字典 + + Raises: + ValueError: 配置项缺失时抛出 + """ + if not self.config.has_section('SmartSheet'): + raise ValueError("配置文件缺少[SmartSheet]节") + + if not self.config.has_option('SmartSheet', 'docid'): + raise ValueError("配置文件[SmartSheet]节缺少docid配置项") + + docid = self.config.get('SmartSheet', 'docid').strip() + if not docid: + raise ValueError("docid配置项不能为空") + + return { + 'docid': docid + } + + def get_all_config(self): + """ + 获取所有配置 + + Returns: + dict: 包含所有配置的字典 + """ + return { + 'tapd': self.get_tapd_config(), + 'smartsheet': self.get_smartsheet_config() + } + + def print_config(self): + """打印当前配置信息（用于调试）""" + print("\n=== 当前配置信息 ===") + try: + tapd_config = self.get_tapd_config() + print(f"[TAPD]") + print(f" workspace_id: {tapd_config['workspace_id']}") + except ValueError as e: + print(f"[TAPD] 配置错误: {e}") + + try: + smartsheet_config = self.get_smartsheet_config() + print(f"[SmartSheet]") + print(f" docid: {smartsheet_config['docid']}") + except ValueError as e: + print(f"[SmartSheet] 配置错误: {e}") + + print("==================\n") + + +if __name__ == "__main__": + # 测试代码 + try: + config_manager = ConfigManager() + config_manager.print_config() + + # 测试获取所有配置 + all_config = config_manager.get_all_config() + print("所有配置获取成功:") + print(f" TAPD workspace_id: {all_config['tapd']['workspace_id']}") + print(f" SmartSheet docid: {all_config['smartsheet']['docid']}") + + except Exception as e: + print(f"错误: {e}") diff --git a/src/main.py b/src/main.py new file mode 100644 index 0000000..044a371 --- /dev/null +++ b/src/main.py @@ -0,0 +1,149 @@ +""" +autoTAPD 主程序 +Debug阶段自动开单工具 - 第一阶段1.1版本 +""" + +import sys +import argparse +from pathlib import Path + +# 添加项目根目录到Python路径 +project_root = Path(__file__).parent.parent +sys.path.insert(0, str(project_root)) + +from src.config import ConfigManager + + +def parse_arguments(): + """ + 解析命令行参数 + + Returns: + argparse.Namespace: 解析后的参数对象 + """ + parser = argparse.ArgumentParser( + description='autoTAPD - Debug阶段自动开单工具', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +示例用法: + python main.py --access-token YOUR_ACCESS_TOKEN + python main.py -t YOUR_ACCESS_TOKEN --config /path/to/config.ini + """ + ) + + # 必需参数 + parser.add_argument( + '-t', '--access-token', + required=True, + help='企业微信access_token（必填）' + ) + + # 可选参数 + parser.add_argument( + '-c', '--config', + default=None, + help='配置文件路径（默认: config/config.ini）' + ) + + parser.add_argument( + '-v', '--verbose', + action='store_true', + help='显示详细输出信息' + ) + + return parser.parse_args() + + +def validate_access_token(access_token): + """ + 验证access_token是否有效 + + Args: + access_token: 待验证的token + + Raises: + ValueError: token无效时抛出 + """ + if not access_token or not access_token.strip(): + raise ValueError("access_token不能为空") + + # 基本格式检查（企业微信的access_token通常较长） + if len(access_token.strip()) < 20: + raise ValueError("access_token格式可能不正确（长度过短）") + + +def main(): + """主函数""" + print("=" * 60) + print("autoTAPD - Debug阶段自动开单工具") + print("版本: 0.1.0 (第一阶段1.1)") + print("=" * 60) + print() + + try: + # 1. 解析命令行参数 + print("[1/3] 解析命令行参数...") + args = parse_arguments() + + if args.verbose: + print(f" - access_token: {args.access_token[:10]}...（已隐藏）") + print(f" - config: {args.config or '使用默认路径'}") + print(f" - verbose: {args.verbose}") + + # 2. 验证access_token + print("[2/3] 验证access_token...") + validate_access_token(args.access_token) + print(" ✓ access_token格式验证通过") + + # 3. 加载配置文件 + print("[3/3] 加载配置文件...") + config_manager = ConfigManager(config_path=args.config) + + # 获取并显示配置信息 + all_config = config_manager.get_all_config() + print(" ✓ 配置文件加载成功") + print() + + # 显示配置摘要 + print("=" * 60) + print("配置摘要:") + print("-" * 60) + print(f"TAPD workspace_id: {all_config['tapd']['workspace_id']}") + print(f"SmartSheet docid: {all_config['smartsheet']['docid'][:20]}...") + print(f"Access Token: {args.access_token[:10]}...（已隐藏）") + print("=" * 60) + print() + + print("✓ 所有初始化步骤完成！") + print() + print("提示: 第一阶段1.1已完成，后续将实现智能表格数据读取功能。") + + return 0 + + except FileNotFoundError as e: + print(f"\n✗ 错误: {e}") + print("\n解决方案:") + print(" 1. 检查配置文件是否存在") + print(" 2. 使用 --config 参数指定正确的配置文件路径") + return 1 + + except ValueError as e: + print(f"\n✗ 错误: {e}") + print("\n解决方案:") + print(" 1. 检查配置文件中的配置项是否完整") + print(" 2. 确保所有必填项都已填写") + print(" 3. 检查access_token是否正确") + return 1 + + except Exception as e: + print(f"\n✗ 未预期的错误: {e}") + print(f"错误类型: {type(e).__name__}") + if args.verbose: + import traceback + print("\n详细错误信息:") + traceback.print_exc() + return 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/开发路线.md b/开发路线.md new file mode 100644 index 0000000..1815eca --- /dev/null +++ b/开发路线.md @@ -0,0 +1,638 @@ +# Debug阶段自动开单工具 - 开发路线 + +## 一、项目概述 + +本项目旨在实现一个自动化工具，从腾讯智能表格读取bug信息，自动在TAPD创建bug单，实现表格到TAPD的单向同步。 + +## 二、开发说明 + +### 2.1 access_token管理策略 +- **第五阶段前：** 所有需要access_token的操作，由开发者手动获取token并传入程序 +- **第五阶段：** 实现access_token的自动获取与缓存机制 +- **第五阶段后：** 程序自动管理access_token的获取、缓存和刷新 + +### 2.2 日志记录策略 +- **第八阶段前：** 使用简单的print输出关键信息 +- **第八阶段：** 实现完整的日志记录系统 + +## 三、字段映射关系 + +| 智能表格列名 | TAPD Bug字段 | 字段类型 | 说明 | +|------------|-------------|---------|------| +| 标题 | title | string | 必填，同步为TAPD标题 | +| 详细描述 | description | string | 必填 | +| 优先级 | priority_label | string | 必填，单选 | +| 严重程度 | severity | string | 必填，单选 | +| 处理人 | current_owner | string | 必填 | +| 验证人 | confirmer | string | 必填 | +| 发现版本 | version_report | string | 必填 | +| 模块 | module | string | 必填 | +| 开单状态 | - | - | 工具回写，✅成功 / ❌失败 | +| TAPD单号 | - | - | 工具回写，可点击跳转 | +| bug状态 | - | - | 工具回写，同步TAPD当前状态 | + +**字段说明：** +- `priority_label`：推荐使用的优先级字段（兼容自定义优先级） +- `severity` 可选值：fatal(致命)、serious(严重)、normal(一般)、prompt(提示)、advice(建议) +- 必填字段共8个，需在第一阶段校验 + +## 四、开发阶段规划 + +### 前期准备：API测试工具开发 + +**目标：** 创建测试脚本，熟悉智能表格API，为后续开发做准备 + +**任务清单：** +1. 创建API测试脚本（api_test.py） +2. 实现获取access_token功能 + - 手动输入corpid和corpsecret + - 调用企业微信API获取access_token + - 将token保存到变量中供后续使用 +3. 实现新建文档功能 + - 调用创建智能表格接口 + - 传入必要参数（doc_name、doc_type等） +4. 实现重命名文档功能 + - 调用重命名文档接口 + - 传入docid和新名称 +5. 实现删除文档功能 + - 调用删除文档接口 + - 传入docid +6. 实现执行记录功能 + - 记录每次API调用的请求内容 + - 记录请求发起时间 + - 记录返回结果 + - 将所有记录保存到JSON文件（api_test_log.json） +7. 实现简单的命令行交互 + - 选择要执行的操作 + - 输入必要参数 + - 显示执行结果 + +**验收标准：** +- [x] 能成功获取access_token +- [x] 能成功创建智能表格文档 +- [x] 能成功重命名文档 +- [x] 能成功删除文档 +- [x] 所有API调用都有完整的记录保存到JSON文件 +- [x] JSON文件格式清晰，包含请求和响应的完整信息 +- [x] 脚本有基本的错误处理 + +**技术要点：** +- 使用requests库调用企业微信API +- JSON文件的读写操作 +- 时间戳的格式化 +- 基本的命令行交互 + +**JSON记录格式示例：** +```json +{ + "records": [ + { + "operation": "get_access_token", + "timestamp": "2025-12-15 10:30:00", + "request": { + "url": "https://qyapi.weixin.qq.com/cgi-bin/gettoken", + "params": { + "corpid": "xxx", + "corpsecret": "***" + } + }, + "response": { + "errcode": 0, + "errmsg": "ok", + "access_token": "xxx", + "expires_in": 7200 + } + } + ] +} +``` + +**潜在问题记录：** +- access_token的有效期管理（本阶段暂不处理，手动重新获取即可） +- API调用失败时的重试机制（本阶段暂不实现） + +--- + +### 第一阶段：基础框架搭建与数据读取 + +#### 阶段1.1：建立基础框架 + +**目标：** 搭建项目基础结构，实现配置管理 + +**任务清单：** +1. 创建项目目录结构 +2. 实现ini配置文件读取模块 + - 配置项：workspace_id（TAPD项目ID） + - 配置项：docid（智能表格文档ID） +3. 实现命令行参数解析 + - 接收access_token参数 + - 接收其他必要参数 +4. 实现基本的错误处理 + - 配置文件不存在 + - 配置项缺失 + - access_token未提供 + +**验收标准：** +- [ ] 能成功读取ini配置文件中的所有配置项 +- [ ] 能通过命令行参数接收access_token +- [ ] 配置缺失时有清晰的错误提示 +- [ ] 使用print输出关键信息 + +**技术要点：** +- 使用configparser读取ini文件 +- 使用argparse解析命令行参数 +- 基本的异常处理 + +**潜在问题记录：** +- 配置文件路径的处理（相对路径 vs 绝对路径） + +--- + +#### 阶段1.2：实现智能表格数据读取与校验 + +**目标：** 扫描智能表格，获取"开单状态"为空的行，并校验必填项 + +**任务清单：** +1. 实现智能表格API调用模块 + - 接收命令行传入的access_token + - 获取子表信息（get_sheet接口） + - 获取字段信息（get_fields接口） + - 查询记录（get_records接口） +2. 实现字段ID映射 + - 根据字段标题获取字段ID + - 建立字段名称到字段ID的映射关系 +3. 实现数据过滤逻辑 + - 筛选"开单状态"字段为空的记录 + - 使用filter_spec参数实现服务端过滤 +4. 实现必填项校验 + - 校验8个必填字段是否为空 + - 记录校验失败的行和具体缺失字段 +5. 输出扫描结果 + - 使用print打印待开单的记录数量 + - 使用print打印校验通过和失败的记录详情 + +**验收标准：** +- [ ] 能成功连接智能表格并获取子表信息 +- [ ] 能正确获取所有字段的ID和名称 +- [ ] 能准确筛选出"开单状态"为空的记录 +- [ ] 能正确校验所有必填字段 +- [ ] 校验失败时能明确指出缺失的字段 +- [ ] 使用print输出关键信息 +- [ ] 异常情况（如网络错误、字段不存在）有明确的错误提示 + +**技术要点：** +- 使用企业微信文档API的smartsheet相关接口 +- 使用filter_spec实现条件查询（OPERATOR_IS_EMPTY） +- 字段类型判断：文本、单选、人员等 +- 数据结构设计：记录对象的表示方式 + +**潜在问题记录：** +- 字段值的合法性校验（如优先级、严重程度的可选值）暂不实现，后续优化 +- 人员字段的userid格式校验暂不实现 +- 大量数据的分页处理（limit和offset参数） + +--- + +### 第二阶段：TAPD API集成与开单功能 + +**目标：** 根据获取到的需要开单的行，调用TAPD API创建bug单 + +**任务清单：** +1. 实现TAPD API认证模块 + - 从环境变量读取TAPD API User和Password + - 实现Basic Auth认证 +2. 实现字段映射转换 + - 将智能表格字段值转换为TAPD API参数 + - 处理人员字段的userid映射 + - 处理单选字段的值映射 +3. 实现TAPD创建bug接口调用 + - 构造请求参数 + - 调用POST /bugs接口 + - 解析返回结果 +4. 实现错误处理 + - API调用失败重试机制（最多3次） + - 记录失败原因 +5. 批量处理逻辑 + - 逐条创建bug单 + - 记录成功和失败的数量 + +**验收标准：** +- [ ] 能成功从环境变量读取TAPD认证信息 +- [ ] 能正确将智能表格数据转换为TAPD API参数 +- [ ] 能成功调用TAPD API创建bug单 +- [ ] 创建成功后能获取到bug ID +- [ ] API调用失败时有重试机制 +- [ ] 所有操作都有详细的日志记录 +- [ ] 能处理TAPD API返回的各种错误码 + +**技术要点：** +- 使用requests库的auth参数实现Basic Auth +- TAPD API的workspace_id参数必填 +- 返回结果中的Bug.id即为TAPD单号 +- 错误码处理：认证失败、参数错误、权限不足等 + +**潜在问题记录：** +- TAPD API的频率限制需要注意 +- 字段值的格式转换（如日期格式） +- 人员字段的userid在TAPD和企业微信中可能不一致，需要确认映射关系 + +--- + +### 第三阶段：回写结果到智能表格 + +**目标：** 将开单结果回写到智能表格，更新"开单状态"、"TAPD单号"、"bug状态"字段 + +**任务清单：** +1. 实现智能表格更新记录接口 + - 调用update_records接口 + - 构造更新参数 +2. 实现开单成功的回写逻辑 + - 更新"开单状态"为✅ + - 更新"TAPD单号"为可点击的链接 + - 更新"bug状态"为TAPD当前状态 +3. 实现开单失败的回写逻辑 + - 更新"开单状态"为❌ + - 记录失败原因（可选，后续优化） +4. 实现批量回写 + - 收集所有需要更新的记录 + - 批量调用更新接口 +5. 实现回写失败的处理 + - 记录回写失败的记录 + - 重试机制 + +**验收标准：** +- [ ] 开单成功后能正确回写✅到"开单状态"字段 +- [ ] 能正确回写TAPD单号，并生成可点击的链接 +- [ ] 能正确回写bug状态 +- [ ] 开单失败后能正确回写❌到"开单状态"字段 +- [ ] 回写失败时有重试机制 +- [ ] 所有操作都有详细的日志记录 + +**技术要点：** +- 智能表格的链接字段格式：CellUrlValue类型 +- TAPD单号链接格式：https://tapd-api.bilibili.co/tapd/workspace_id/bugtrace/bugs/view/bug_id +- 批量更新时注意API的请求限制 +- 字段类型：文本、链接 + +**潜在问题记录：** +- 回写失败时是否需要回滚TAPD的bug单（暂不实现） +- 链接字段的格式需要确认 +- bug状态的同步频率（需求文档建议15分钟一次） + +--- + +### 第四阶段：定时任务与服务化 + +**目标：** 将工具部署为服务，实现定时扫描和状态同步 + +**任务清单：** +1. 实现定时任务调度 + - 使用schedule库或APScheduler + - 配置开单扫描频率（默认5分钟） + - 配置状态同步频率（默认15分钟） +2. 实现bug状态同步功能 + - 查询已开单的记录 + - 调用TAPD API获取bug最新状态 + - 更新智能表格的"bug状态"字段 +3. 实现服务启动和停止 + - 命令行参数解析 + - 优雅退出机制 +4. 实现配置文件扩展 + - 添加轮询频率配置 + - 添加状态同步频率配置 +5. 完善日志和监控 + - 添加运行统计信息 + - 添加性能监控 + +**验收标准：** +- [ ] 服务能正常启动和停止 +- [ ] 能按配置的频率执行开单扫描 +- [ ] 能按配置的频率执行状态同步 +- [ ] 状态同步功能正常工作 +- [ ] 服务异常时能自动恢复 +- [ ] 有完善的运行日志和统计信息 + +**技术要点：** +- 定时任务的线程安全 +- 信号处理（SIGINT、SIGTERM） +- 异常捕获和恢复 +- 配置热加载（可选） + +**潜在问题记录：** +- 长时间运行的内存泄漏问题 +- access_token过期的自动刷新 +- 并发执行的冲突处理 + +--- + +### 第五阶段：access_token自动获取与缓存 + +**目标：** 实现access_token的自动获取与缓存机制，不再需要手动传入token + +**任务清单：** +1. 实现企业微信认证模块 + - 从环境变量读取corpid和corpsecret + - 调用企业微信API获取access_token + - 处理认证失败的情况 +2. 设计token缓存结构 + - 存储token值 + - 存储过期时间 + - 存储获取时间 +3. 实现token缓存逻辑 + - 首次获取时缓存 + - 使用前检查是否过期 + - 过期前自动刷新（建议提前5分钟） +4. 实现持久化存储（可选） + - 使用文件存储token + - 服务重启后能恢复token +5. 实现token失效处理 + - 检测token失效（API返回42001错误码） + - 自动重新获取 +6. 重构现有代码 + - 移除命令行传入access_token的逻辑 + - 所有API调用自动使用缓存的token + +**验收标准：** +- [ ] 能从环境变量读取corpid和corpsecret +- [ ] 能自动获取access_token +- [ ] token能正确缓存和复用 +- [ ] token过期前能自动刷新 +- [ ] token失效时能自动重新获取 +- [ ] 不再需要手动传入access_token +- [ ] 减少了获取token的API调用次数 +- [ ] 环境变量未设置时有清晰的错误提示 + +**技术要点：** +- token有效期为7200秒（2小时） +- 建议在过期前5分钟刷新 +- 使用os.environ读取环境变量 +- 线程安全的缓存实现 +- 异常处理：网络错误、认证失败等 + +**潜在问题记录：** +- 多实例部署时的token共享问题 +- 时钟不同步导致的过期判断错误 +- 环境变量的安全性问题 + +--- + +### 第六阶段：企业微信推送功能 + +**目标：** 实现开单失败时的企业微信推送通知 + +**任务清单：** +1. 实现企业微信消息推送API + - 调用发送应用消息接口 + - 构造消息内容 +2. 实现推送对象配置 + - 配置接收推送的人员列表 + - 支持按部门推送 +3. 实现推送内容设计 + - 失败原因 + - 失败的记录信息 + - 智能表格链接 +4. 实现推送频率控制 + - 避免频繁推送 + - 合并相同类型的错误 +5. 实现推送失败处理 + - 记录推送失败的日志 + - 重试机制 + +**验收标准：** +- [ ] 开单失败时能正确推送消息 +- [ ] 推送内容清晰明确 +- [ ] 推送对象配置灵活 +- [ ] 推送频率合理 +- [ ] 推送失败有日志记录 + +**技术要点：** +- 企业微信消息推送API +- 消息格式：文本、markdown等 +- 推送对象：userid、部门ID +- 频率控制：时间窗口、消息合并 + +**潜在问题记录：** +- 推送频率限制 +- 消息长度限制 +- 用户未关注应用时的处理 + +--- + +### 第七阶段：字段合法性校验与优化 + +**目标：** 完善字段值的合法性校验，提高数据质量 + +**任务清单：** +1. 实现优先级字段校验 + - 获取TAPD项目的优先级配置 + - 校验智能表格中的值是否合法 +2. 实现严重程度字段校验 + - 校验可选值：fatal、serious、normal、prompt、advice +3. 实现人员字段校验 + - 校验userid格式 + - 校验用户是否存在 +4. 实现模块字段校验 + - 获取TAPD项目的模块配置 + - 校验模块是否存在 +5. 实现版本字段校验 + - 获取TAPD项目的版本配置 + - 校验版本是否存在 +6. 完善错误提示 + - 明确指出不合法的字段和原因 + - 提供修正建议 + +**验收标准：** +- [ ] 能正确校验所有字段的合法性 +- [ ] 不合法的值有明确的错误提示 +- [ ] 校验失败时不创建TAPD单 +- [ ] 校验结果能回写到智能表格（可选） + +**技术要点：** +- TAPD API：获取字段配置接口 +- 智能表格：单选字段的option_id +- 数据缓存：避免频繁查询配置 +- 错误信息的友好展示 + +**潜在问题记录：** +- TAPD配置变更时的同步问题 +- 自定义字段的校验规则 + +--- + +### 第八阶段：日志系统与性能优化 + +**目标：** 实现完整的日志记录系统，优化系统性能，添加监控和告警 + +**任务清单：** +1. 实现日志记录模块 + - 使用Python logging模块 + - 日志级别：DEBUG、INFO、WARNING、ERROR + - 日志输出：控制台 + 文件 + - 日志轮转：按日期或大小分割 +2. 重构现有代码 + - 将所有print语句替换为日志记录 + - 添加详细的日志信息 + - 统一日志格式 +3. 实现批量处理优化 + - 批量创建TAPD bug + - 批量更新智能表格 +4. 实现并发处理 + - 使用线程池或协程 + - 控制并发数量 +5. 实现性能监控 + - 记录每次扫描的耗时 + - 记录API调用的耗时 + - 记录成功率 +6. 实现告警机制 + - 失败率过高时告警 + - 服务异常时告警 +7. 实现数据统计 + - 每日开单数量 + - 失败原因统计 + - 性能趋势分析 + +**验收标准：** +- [ ] 日志模块能正常输出到控制台和文件 +- [ ] 日志格式统一，信息完整 +- [ ] 日志文件能自动轮转 +- [ ] 所有关键操作都有日志记录 +- [ ] 批量处理性能提升明显 +- [ ] 并发处理稳定可靠 +- [ ] 有完善的性能监控数据 +- [ ] 异常情况能及时告警 +- [ ] 有详细的统计报表 + +**技术要点：** +- logging模块的配置和使用 +- RotatingFileHandler或TimedRotatingFileHandler +- 线程池：concurrent.futures.ThreadPoolExecutor +- 协程：asyncio、aiohttp +- 监控：Prometheus、Grafana（可选） +- 告警：企业微信、邮件等 + +**潜在问题记录：** +- 并发时的API频率限制 +- 数据一致性问题 +- 监控数据的存储和查询 +- 日志文件的磁盘占用 + +--- + +## 五、技术栈 + +- **编程语言：** Python 3.8+ +- **核心库：** + - requests：HTTP请求 + - configparser：配置文件解析 + - argparse：命令行参数解析 + - json：JSON文件处理 + - datetime：时间处理 + - logging：日志记录（第八阶段） + - schedule/APScheduler：定时任务（第四阶段） +- **API：** + - 企业微信文档API + - TAPD Open API + +## 六、配置文件示例 + +### config.ini +```ini +[TAPD] +workspace_id = 10158231 + +[SmartSheet] +docid = your_doc_id + +[Schedule] +# 第四阶段添加 +scan_interval = 5 +sync_interval = 15 +``` + +### 环境变量（第五阶段开始使用） +```bash +# 企业微信（第五阶段） +WEWORK_CORPID=your_corpid +WEWORK_CORPSECRET=your_corpsecret + +# TAPD（第二阶段） +TAPD_API_USER=your_api_user +TAPD_API_PASSWORD=your_api_password +``` + +## 七、目录结构（建议） + +``` +autoTAPD/ +├── config/ +│ └── config.ini # 配置文件 +├── src/ +│ ├── __init__.py +│ ├── api_test.py # 前期准备：API测试工具 +│ ├── config.py # 配置管理 +│ ├── wework_api.py # 企业微信API（第五阶段完善） +│ ├── smartsheet.py # 智能表格操作 +│ ├── tapd_api.py # TAPD API +│ ├── validator.py # 数据校验 +│ ├── mapper.py # 字段映射 +│ ├── token_cache.py # token缓存（第五阶段） +│ ├── scheduler.py # 定时任务（第四阶段） +│ ├── logger.py # 日志模块（第八阶段） +│ └── main.py # 主程序 +├── logs/ # 日志目录（第八阶段） +│ └── api_test_log.json # API测试记录 +├── tests/ # 测试代码 +├── requirements.txt # 依赖包 +└── README.md # 项目说明 +``` + +## 八、开发原则 + +1. **小步走原则：** 每个阶段完成一个独立功能，验收通过后再进入下一阶段 +2. **先实现后优化：** 前期以完成功能为主，不过度设计，后期再优化性能和潜在问题 +3. **异常处理：** 所有外部调用都要有异常处理，关键操作需要重试机制 +4. **配置驱动：** 尽量通过配置文件控制行为，避免硬编码 +5. **代码复用：** 相同逻辑封装为函数或类，避免重复代码 +6. **阶段性验收：** 每个阶段完成后必须通过验收标准才能进入下一阶段 + +## 九、注意事项 + +1. **API频率限制：** 注意企业微信和TAPD的API调用频率限制 +2. **数据安全：** 敏感信息（如token、密码）不要硬编码，使用环境变量 +3. **错误恢复：** 服务异常时要能自动恢复，不影响后续执行 +4. **向后兼容：** 配置文件和数据结构的变更要考虑向后兼容 +5. **文档更新：** 每个阶段完成后更新相关文档 +6. **access_token管理：** 第五阶段前手动传入，第五阶段后自动管理 +7. **日志策略：** 第八阶段前使用print，第八阶段后使用logging模块 + +## 十、阶段依赖关系 + +``` +前期准备（API测试工具） + ↓ +第一阶段（基础框架 + 数据读取） + ↓ +第二阶段（TAPD开单） + ↓ +第三阶段（回写结果） + ↓ +第四阶段（定时任务） + ↓ +第五阶段（access_token自动化） + ↓ +第六阶段（企业微信推送） + ↓ +第七阶段（字段合法性校验） + ↓ +第八阶段（日志系统 + 性能优化） +``` + +## 十一、后续优化方向 + +1. 支持多个智能表格和TAPD项目 +2. 支持自定义字段映射配置 +3. 支持webhook触发（实时开单） +4. 支持双向同步（TAPD更新同步到智能表格） +5. 提供Web管理界面 +6. 支持数据统计和报表 +7. 支持更多的字段类型和复杂映射规则 diff --git a/智能表格接口文档.md b/智能表格接口文档.md new file mode 100644 index 0000000..453824b --- /dev/null +++ b/智能表格接口文档.md @@ -0,0 +1,4222 @@ +# 概述 + +最后更新：2025/07/16 + +企业和开发者通过文档接口可以便捷地新建文档和表格，将项目进展、业务数据等通知给成员，提高信息流转效率；也可通过文档接口新建智能表格（目前仅支持企业新建），邀请成员协作编辑，与业务系统结合更紧密；还可通过接口新建收集表，收集员工信息。 +调用接口的应用自动成为文档创建者，所建的文档、表格和收集表，仅应用可编辑内容；所建的智能表格，应用和成员均可编辑内容，内容也可被应用获取。创建后，应用可通过接口管理文档，也可指定成员作为文档管理员辅助管理。 + +提示 + +应用仅可读取和编辑自己创建的文档，无法编辑成员创建的文档；应用通过接口创建文档后，即可获得docid。docid仅在创建时返回，需要开发者妥善保存。 + + + +## 接口创建文档表现 + +- 接口创建的文档和收集表将在文档应用中标识出应用创建的信息，文档图标也将替换为应用图标。 +- 接口创建的文档和收集表可添加企业成员进入通知范围，仅应用可编辑文档内容，成员无法编辑，但指定的管理员可以修改通知范围和获取收集表数据。 +- 通过接口创建、修改、删除文档或收集表后，文档应用将自动向文档或收集表相关成员推送通知。 + + +## 接口创建智能表格的表现 + +- 接口创建的智能表格将在智能表格中标识出应用创建的信息。 +- 应用自动加入智能表格，成员可查询应用信息。 +- 成员首次编辑智能表格时，展示 应用可获取编辑内容 提示。 + + +## 配置可调用文档接口的应用 + +应用在调用文档接口前，需要先获得文档的使用权限。 + +**自建应用** +登录企业微信管理端，进入「协作」-「文档」-「API」，配置「可调用接口的应用」。 +**第三方应用** +第三方服务商创建应用的时候，需要开启“文档接口权限”，企业授权安装第三方应用之后，第三方应用即拥有了调用文档接口的权限 +**代开发应用** +第三方服务商为企业配置代开发应用时，需要开启「文档接口权限」，企业管理员确认之后，应用即拥有文档权限。 + +# 获取access_token + +最后更新：2024/03/26 + +注意 + +为了安全考虑，开发者 **请勿** 将 access_token 返回给前端，需要开发者保存在后台，所有访问企业微信api的请求由后台发起 + +获取access_token是调用企业微信API接口的第一步，相当于创建了一个登录凭证，其它的业务API接口，都需要依赖于access_token来鉴权调用者身份。 +因此开发者，在使用业务接口前，要明确access_token的颁发来源，使用正确的access_token。 + +**请求方式：** GET（**HTTPS**） +**请求地址：** https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET + +提示 + +此处标注大写的单词 ID 和 SECRET，为需要替换的变量，根据实际获取值更新。其它接口也采用相同的标注，不再说明。 + +**参数说明：** + +| 参数 | 必须 | 说明 | +| ---------- | ---- | ------------------------------------------------------------ | +| corpid | 是 | 企业ID，获取方式参考：[术语说明-corpid](https://developer.work.weixin.qq.com/document/path/91039#14953/corpid) | +| corpsecret | 是 | 应用的凭证密钥，**注意应用需要是启用状态**，获取方式参考：[术语说明-secret](https://developer.work.weixin.qq.com/document/path/91039#14953/secret) | + +**权限说明：** +每个应用有独立的secret，获取到的access_token只能本应用使用，所以每个应用的access_token应该分开来获取 + +**返回结果：** + +```javascript +{ + "errcode": 0, + "errmsg": "ok", + "access_token": "accesstoken000001", + "expires_in": 7200 +} +``` + +**参数说明：** + +| 参数 | 说明 | +| ------------ | ---------------------------------------- | +| errcode | 出错返回码，为0表示成功，非0表示调用失败 | +| errmsg | 返回码提示语 | +| access_token | 获取到的凭证，最长为512字节 | +| expires_in | 凭证的有效时间（秒） | + +**注意事项：** +开发者需要缓存access_token，用于后续接口的调用（注意：不能频繁调用gettoken接口，否则会受到频率拦截）。当access_token失效或过期时，需要重新获取。 + +access_token的有效期通过返回的expires_in来传达，正常情况下为7200秒（2小时）。 +由于企业微信每个应用的access_token是彼此独立的，所以进行缓存时需要区分应用来进行存储。 +access_token至少保留512字节的存储空间。 +企业微信可能会出于运营需要，提前使access_token失效，开发者应实现access_token失效时重新获取的逻辑。 + +# 获取企业微信接口IP段 + +最后更新：2023/04/24 + +API域名IP即qyapi.weixin.qq.com的解析地址，由开发者调用企业微信端的接入IP。如果企业需要做防火墙配置，那么可以通过这个接口获取到所有相关的IP段。IP段有变更可能，当IP段变更时，新旧IP段会同时保留一段时间。建议企业每天定时拉取IP段，更新防火墙设置，避免因IP段变更导致网络不通。 + +**请求方式：**GET（**HTTPS**） +**请求地址：** https://qyapi.weixin.qq.com/cgi-bin/get_api_domain_ip?access_token=ACCESS_TOKEN （[获取ACCESS_TOKEN](https://developer.work.weixin.qq.com/document/path/92520#15074)） + +**请求参数说明：** + +| 参数 | 必须 | 说明 | +| ------------ | ---- | ------------ | +| access_token | 是 | 调用接口凭证 | + +**权限说明：** + +无限定。 + +**返回结果：** + +```javascript +{ + "ip_list":[ + "182.254.11.176", + "182.254.78.66" + ], + "errcode":0, + "errmsg":"ok" +} +``` + +**返回参数说明：** + +| 参数 | 类型 | 说明 | +| ------- | ----------- | ---------------------------------------- | +| ip_list | StringArray | 企业微信服务器IP段 | +| errcode | int | 错误码，0表示成功，非0表示调用失败 | +| errmsg | string | 错误信息，调用失败会有相关的错误信息返回 | + +根据errcode值非0，判断调用失败。以下是access_token过期的返回示例： + +```javascript +{ + "ip_list":[], + "errcode":42001, + "errmsg":"access_token expired, hint: [1576065934_28_e0fae07666aa64636023c1fa7e8f49a4], from ip: 9.30.0.138, more info at https://open.work.weixin.qq.com/devtool/query?e=42001" +} +``` + + + +# 管理文档 + +## 新建文档 + +最后更新：2025/07/16 + +该接口用于新建文档、表格及智能表格，新建收集表可前往 [收集表管理](https://developer.work.weixin.qq.com/document/path/97460#43942) 查看。 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "spaceid": "SPACEID", + "fatherid": "FATHERID", + "doc_type": 3, + "doc_name": "DOC_NAME", + "admin_users": ["USERID1", "USERID2", "USERID3"] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----------- | -------- | -------- | ------------------------------------------------------------ | +| spaceid | string | 否 | 空间spaceid。若指定`spaceid`，则`fatherid`也要同时指定 | +| fatherid | string | 否 | 父目录fileid, 在根目录时为空间spaceid | +| doc_type | uint32 | 是 | 文档类型, 3:文档 4:表格 10:智能表格 | +| doc_name | string | 是 | 文档名字（注意：文件名最多填255个字符, 超过255个字符会被截断） | +| admin_users | string[] | 否 | 文档管理员userid | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97460#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97460#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "url": "URL", + "docid": "DOCID" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | -------------------------------------------------------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| url | string | 新建文档的访问链接 | +| docid | string | 新建文档的docid。docid仅在创建时返回，需要开发者妥善保存 | + +## 重命名文档 + +最后更新：2024/10/28 + +该接口用于对指定文档、表格、智能表格及收集表进行重命名。 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/rename_doc?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "formid": "FORMID", + "new_name": "NEW_NAME" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------ | -------- | ------------------------------------------------------------ | +| docid | string | 否 | 文档docid（docid、formid只能填其中一个） ，仅可修改应用自己创建的文档 | +| formid | string | 否 | 收集表id（docid、formid只能填其中一个） ，仅可修改应用自己创建的收集表 | +| new_name | string | 是 | 重命名后的文档名 （注意：文档名最多填255个字符, 英文算1个, 汉字算2个, 超过255个字符会被截断） | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97736#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97736#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 删除文档 + +最后更新：2024/10/28 + +该接口用于删除指定文档、表格、智能表格及收集表进行重命名。 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/del_doc?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "formid": "FORMID" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------ | ------ | -------- | ------------------------------------------------------------ | +| docid | string | 否 | 文档docid（docid、formid只能填其中一个），仅可删除应用自己创建的文档 | +| formid | string | 否 | 收集表id（docid、formid只能填其中一个），仅可删除应用自己创建的收集表 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97735#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97735#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 获取文档基础信息 + +最后更新：2024/05/30 + +该接口用于获取指定文档、表格、智能表格及收集表的基础信息。 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/get_doc_base_info?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----- | ------ | -------- | --------- | +| docid | string | 是 | 文档docid | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97734#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97734#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "doc_base_info": { + "docid": "DOCID", + "doc_name": "DOC_NAME", + "create_time": 1717071093, + "modify_time": 1717071093, + "doc_type": 3 + } +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ----------- | ------ | --------------------------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| docid | string | 文档docid | +| doc_name | string | 文档名字 | +| create_time | uint64 | 文档创建时间 | +| modify_time | uint64 | 文档最后修改时间 | +| doc_type | uint32 | 3: 文档 4: 表格 10:智能表格 | + +## 分享文档 + +最后更新：2024/05/30 + +该接口用于获取文档、表格、智能表格及收集表的分享链接。 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/doc_share?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid":"DOCID", + "formid": "FORMID" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----- | ------ | -------- | ------------------------------------- | +| docid | string | 否 | 文档id（docid、formid只能填其中一个） | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97733#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97733#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 +- 只能访问该应用创建的文档 + +**返回示例** + +```json +{ + "errcode":0, + "errmsg":"ok", + "share_url":"URL1" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| --------- | ------ | ------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| share_url | string | 文档分享链接 | + + + +# 管理智能表格内容 + +## 添加子表 + +本接口用于在表格的某个位置添加一个智能表，该智能表不存在视图、记录和字段，可以使用 API 在该智能表中添加视图、记录和字段。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_sheet?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "properties": { + "title": "智能表", + "index": 3 + } +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ---------------- | ------ | -------- | ----------- | +| docid | string | 是 | 文档的docid | +| properties | object | 否 | 智能表属性 | +| properties.title | string | 否 | 智能表标题 | +| properties.index | int32 | 否 | 智能表下标 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99896#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99896#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "properties": { + "title": "智能表", + "index": 3, + "sheet_id": "123abc" + } +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------------------- | ------ | --------------------------------------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| properties | object | 智能表属性 | +| properties.sheet_id | string | 智能表 ID，创建子表时生成的 6 位随机 ID | +| properties.title | string | 智能表标题 | +| properties.index | int32 | 智能表下标 | + +## 删除子表 + +本接口用于删除在线表格中的某个智能表。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_sheet?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------ | -------- | ------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 删除的Smartsheet 子表 ID | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99899#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99899#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 更新子表 + +本接口用于修改表格中某个子表的标题。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_sheet?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "properties": { + "sheet_id": "123abc", + "title": "XXXX" + } +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------------- | ------ | -------- | ----------- | +| docid | string | 是 | 文档的docid | +| properties.sheet_id | string | 是 | 子表 ID | +| properties.title | string | 否 | 子表标题 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99898#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99898#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 查询子表 + +本接口用于查询一篇在线表格中全部智能表信息。 +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_sheet?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "xxx", + "need_all_type_sheet":true +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------------- | ------ | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 否 | 指定子表ID查询 | +| need_all_type_sheet | bool | 否 | 获取所有类型子表。为true时可获取包含仪表盘和说明页在内的所有类型的子表 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101154#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101154#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "sheet_list": [ + { + "sheet_id": "123abc", + "title": "XXXX", + "is_visible": true, + "type":"smartsheet" + }, + { + "sheet_id": "456abc", + "title": "仪表盘1", + "is_visible": true, + "type": "dashboard" + }, + { + "sheet_id": "789abc", + "title": "如何搭建自己的智能表格", + "is_visible": true, + "type": "external" + } + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| --------------------- | ------------------- | ------------------------------------------------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| sheet_list | object[] 智能表信息 | | +| sheet_list.sheet_id | string | 子表id | +| sheet_list.title | string | 子表名称 | +| sheet_list.is_visible | bool | 子表是否可见 | +| sheet_list.type | string | 子表类型。"dashboard" 仪表盘。"external" 说明页，"smartsheet" 智能表 | + +## 添加视图 + +本接口用于在 Smartsheet 中的某个子表里添加一个新视图。单表最多允许有200个视图。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_view?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "view_title": "XXX", + "view_type": "VIEW_TYPE_GRID" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| view_title | string | 是 | 视图标题 | +| view_type | string | 是 | 视图类型。见[ViewType](https://developer.work.weixin.qq.com/document/path/99900#viewtype) | +| property_gantt | obect([GanttViewProperty](https://developer.work.weixin.qq.com/document/path/99900#ganttviewproperty)) | 否 | 甘特视图属性,添加甘特图时必填 | +| property_calendar | object([CalendarViewProperty](https://developer.work.weixin.qq.com/document/path/99900#calendarviewproperty)) | 否 | 日历视图属性，添加日历视图时必填 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99900#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99900#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "view": { + "view_id": "vFYZUS", + "view_title": "XXX", + "view_type": "VIEW_TYPE_GRID" + } +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| view | object([View](https://developer.work.weixin.qq.com/document/path/99900#view)) | 添加视图响应 | + +### 参数详细说明 + +### View + +**示例** + +```json +{ + "view_id": "vabcde", + "view_title": "默认视图", + "view_type": "VIEW_TYPE_GRID" +} +``` + +视图信息： + +| 参数名 | 类型 | 描述 | +| ---------- | ------ | ------------------------------------------------------------ | +| view_id | string | 视图 ID | +| view_title | string | 视图标题 | +| view_type | string | 视图类型。见[ViewType](https://developer.work.weixin.qq.com/document/path/99900#viewtype) | + +### ViewType + +视图类型： + +| 枚举类型 | 描述 | +| ------------------ | ---------------------------- | +| VEW_UNKNOWN | 未知类型视图，传递该值不合法 | +| VIEW_TYPE_GRID | 表格视图 | +| VIEW_TYPE_KANBAN | 看板视图 | +| VIEW_TYPE_GALLERY | 画册视图 | +| VIEW_TYPE_GANTT | 甘特视图 | +| VIEW_TYPE_CALENDAR | 日历视图 | + +### GanttViewProperty + +甘特设置 + +| 参数名 | 类型 | 是否必须 | 描述 | +| ------------------- | ------ | -------- | ------------------------------------------------------------ | +| start_date_field_id | string | 是 | 时间条起点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID | +| end_date_field_id | string | 是 | 时间条终点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID | + +### CalendarViewProperty + +日历设置 + +| 参数名 | 类型 | 是否必须 | 描述 | +| ------------------- | ------ | -------- | ------------------------------------------------------------ | +| start_date_field_id | string | 是 | 时间条起点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID | +| end_date_field_id | string | 是 | 时间条终点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID | + +## 删除视图 + +本接口用于在 smartsheet 中的某个子表里删除若干个视图。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_views?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "view_ids": [ + "VIEWID1", "VIEWID2" + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | -------- | -------- | ------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| view_ids | string[] | 是 | 要删除的视图ID列表 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99901#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99901#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + + 更新视图 + +本接口用于更新 Smartsheet 中的某个视图。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_view?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "view_id": "VIEWID", + "view_title": "XXX", + "property": { + } +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ---------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| view_id | string | 是 | 视图ID | +| view_title | string | 否 | 视图标题 | +| property | object([ViewProperty](https://developer.work.weixin.qq.com/document/path/99902#viewproperty)) | 否 | 视图的排序/过滤/分组/填色配置，详见[ViewProperty](https://developer.work.weixin.qq.com/document/path/99902#viewproperty) | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99902#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99902#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "view": { + } +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| view | object([View](https://developer.work.weixin.qq.com/document/path/99902#view)) | 更新成功的视图内容 | + +### 参数详细说明 + +### View + +**示例** + +```json +{ + "view_id": "vabcde", + "view_title": "默认视图", + "view_type": "VIEW_TYPE_GRID", + "property": { + } +} +``` + +视图信息： + +| 参数名 | 类型 | 描述 | +| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| view_id | string | 视图 ID | +| view_title | string | 视图标题 | +| view_type | string | 视图类型。见[ViewType](https://developer.work.weixin.qq.com/document/path/99902#53110/viewtype) | +| property | object([ViewProperty](https://developer.work.weixin.qq.com/document/path/99902#viewproperty)) | 视图属性 | + +### ViewProperty + +**示例** + +```json +{ + "auto_sort": false, + "sort_spec": {}, + "filter_spec": {}, + "group_spec": {}, + "is_field_stat_enabled": false, + "field_visibility": { + "f1gHSR": false, + "fabcde": false + }, + "frozen_field_count": 0, + "color_config": { + "conditions": [{ + "id": "4840474257", + "type": "VIEW_COLOR_CONDITION_TYPE_CELL", + "color": "chromeAmberLighten_5", + "condition": { + "field_id": "fRCjJz", + "field_type": "FIELD_TYPE_TEXT", + "operator": "OPERATOR_CONTAINS", + "string_value": { + "value": [ + "5555" + ] + } + } + }] + } +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| --------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------ | +| auto_sort | bool | 否 | 记录变更后自动重新排序 | +| sort_spec | object([SortSpec](https://developer.work.weixin.qq.com/document/path/99902#sortspec)) | 否 | 排序设置 | +| group_spec | object([GroupSpec](https://developer.work.weixin.qq.com/document/path/99902#groupspec)) | 否 | 分组设置 | +| filter_spec | object([FilterSpec](https://developer.work.weixin.qq.com/document/path/99902#filterspec)) | 否 | 过滤设置 | +| is_field_stat_enabled | bool | 否 | 是否使用数据统计 | +| field_visibility | object | 否 | 类似map。 key为字段ID, value为布尔值表示是否显示 | +| frozen_field_count | int32 | 否 | 冻结列数量，从首列开始 | +| color_config | object([ViewColorConfig](https://developer.work.weixin.qq.com/document/path/99902#viewcolorconfig)) | 否 | 填色设置 | + +### SortSpec + +**示例** + +```json +{ + "sort_infos": [ + { + "field_id": "FIELDID1", + "desc": false + }, + { + "field_id": "FIELDID2", + "desc": true + } + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ------------------- | -------- | -------- | ------------------ | +| sort_infos | object[] | 否 | 参与排序的字段列表 | +| sort_infos.field_id | string | 是 | 字段id | +| sort_infoes.desc | bool | 否 | 是否降序 | + +### GroupSpec + +**示例** + +```json +{ + "groups": [ + { + "field_id": "FIELDID1", + "desc": false + }, + { + "field_id": "FIELDID2", + "desc": true + } + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| --------------- | -------- | -------- | ------------------ | +| groups | object[] | 否 | 参与分组的字段列表 | +| groups.field_id | string | 是 | 字段id | +| groups.desc | bool | 否 | 是否降序 | + +### FilterSpec + +**示例** + +```json +{ + "conjunction": "CONJUNCTION_AND", + "conditions": [ + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ----------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| conjunction | string | 是 | 多个conditions之间是以and(`CONJUNCTION_AND`)还是or(`CONJUNCTION_OR`)进行组合 | +| conditions | object[]([Condition](https://developer.work.weixin.qq.com/document/path/99902#condition)) | 是 | 判断条件 | + +### Condition + +**注：不同字段类型支持的筛选不同，需要根据智能表格不同字段类型实际支持的筛选条件进行组合** + +**示例1** +过滤`FIELDID1`字段包含文本`hello world`的记录 + +```json +{ + "field_id": "FIELDID1", + "operator": "OPERATOR_CONTAINS", + "string_value": { + "value": ["hello world"] + } +} +``` + +**示例2** +过滤`FIELDID2`字段为用户`USERID1`的记录 + +```json +{ + "field_id": "FIELDID2", + "operator": "OPERATOR_IS", + "user_value": { + "value": ["USERID1"] + } +} +``` + +**示例3** +过滤`FIELDID3`字段为日期`2025年5月14日`的记录 + +```json +{ + "field_id": "FIELDID3", + "field_type": "FIELD_TYPE_DATE_TIME", + "operator": "OPERATOR_IS", + "date_time_value": { + "type": "DATE_TIME_TYPE_DETAIL_DATE", + "value": [ + "1747152000000" + ] + } +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| field_id | string | 是 | 字段ID | +| field_type | stiring | 是 | 字段类型 | +| operator | string | 是 | 判断类型。见[Operator](https://developer.work.weixin.qq.com/document/path/99902#operator) | +| string_value.value | string[] | 否 | 文本、网址、电话、邮箱、地理位置、单选、多选等列类型使用。选项列为选项ID；其它为文本值 | +| number_value.value | double | 否 | 数字、进度列类型使用 | +| bool_value.value | bool | 否 | 复选框列类型使用 | +| user_value.value | string[] | 否 | 人员、创建人、最后编辑人列类型使用，值为成员ID | +| date_time_value | object([FilterDataTimeValue](https://developer.work.weixin.qq.com/document/path/99902#filterdatetimevalue)) | 否 | 日期、创建时间、最后编辑时间列类型使用 | + +### Operator + +| 筛选值判断操作类型 | 说明 | +| ---------------------------- | ---------- | +| OPERATOR_UNKNOWN | 未知 | +| OPERATOR_IS | 等于 | +| OPERATOR_IS_NOT | 不等于 | +| OPERATOR_CONTAINS | 包含 | +| OPERATOR_DOES_NOT_CONTAIN | 不包含 | +| OPERATOR_IS_GREATER | 大于 | +| OPERATOR_IS_GREATER_OR_EQUAL | 大于或等于 | +| OPERATOR_IS_LESS | 小于 | +| OPERATOR_IS_LESS_OR_EQUAL | 小于或等于 | +| OPERATOR_IS_EMPTY | 为空 | +| OPERATOR_IS_NOT_EMPTY | 不为空 | + +### FilterDataTimeValue + +| 参数名 | 类型 | 是否必须 | 描述 | +| ------ | -------- | -------- | ------------------------------------------------------------ | +| type | string | 是 | 日期类型。见[DateTimeType](https://developer.work.weixin.qq.com/document/path/99902#datetimetype) | +| value | string[] | 是 | 具体日期值，type为具体日期(`DATE_TIME_TYPE_DETAIL_DATE`) | + +### DateTimeType + +| 日期值类型 | 说明 | +| ------------------------------- | -------------- | +| DATE_TIME_TYPE_DETAIL_DATE | 具体时间 | +| DATE_TIME_TYPE_TODAY | 今天 | +| DATE_TIME_TYPE_TOMORROW | 明天 | +| DATE_TIME_TYPE_YESTERDAY | 昨天 | +| DATE_TIME_TYPE_CURRENT_WEEK | 本周 | +| DATE_TIME_TYPE_LAST_WEEK | 上周 | +| DATE_TIME_TYPE_CURRENT_MONTH | 本月 | +| DATE_TIME_TYPE_THE_PAST_7_DAYS | 过去 7 天内 | +| DATE_TIME_TYPE_THE_NEXT_7_DAYS | 接下来 7 天内 | +| DATE_TIME_TYPE_LAST_MONTH | 上月 | +| DATE_TIME_TYPE_THE_PAST_30_DAYS | 过去 30 天内 | +| DATE_TIME_TYPE_THE_NEXT_30_DAYS | 接下来 30 天内 | + +### ViewColorConfig + +**示例** + +```json +{ + "conditions": [ + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | -------- | +| conditions | object[]([ViewColorCondition](https://developer.work.weixin.qq.com/document/path/99902#viewcolorcondition)) | 是 | 判断条件 | + +### ViewColorCondition + +**示例** + +```json +{ + "id": "5599107762", + "type": "VIEW_COLOR_CONDITION_TYPE_CELL", + "color": "chromeOrangeLighten_5", + "condition": { + "field_id": "fMPZMg", + "field_type": "FIELD_TYPE_NUMBER", + "operator": "OPERATOR_IS", + "number_value": { + "value": 5 + } + } +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| id | string | 否 | 填色id，新增时不需要传入，更新时传入 | +| type | string | 是 | 填色类型,见([ViewColorConditionType](https://developer.work.weixin.qq.com/document/path/99902#viewcolorconditiontype)) | +| color | string | 是 | 颜色，见([ViewColor](https://developer.work.weixin.qq.com/document/path/99902#viewcolor)) | +| conditions | object[]([Condition](https://developer.work.weixin.qq.com/document/path/99902#condition)) | 是 | 判断条件 | + +### ViewColorConditionType + +| 填色类型 | 说明 | +| -------------------------------- | ------ | +| VIEW_COLOR_CONDITION_TYPE_ROW | 行 | +| VIEW_COLOR_CONDITION_TYPE_COLUMN | 列 | +| VIEW_COLOR_CONDITION_TYPE_CELL | 单元格 | + +### ViewColor + +| 颜色值 | 描述 | +| --------------------- | -------- | +| fillColorGray_5 | 灰色_5 | +| accentBlueLighten_5 | 蓝色_5 | +| chromeCyanLighten_5 | 青色_5 | +| chromeMintLighten_5 | 薄荷色_5 | +| chromeRedLighten_5 | 红色_5 | +| chromeOrangeLighten_5 | 橙色_5 | +| chromeAmberLighten_5 | 琥珀色_5 | +| chromeVioletLighten_5 | 紫色_5 | +| chromePinkLighten_5 | 粉色_5 | +| fillColorGray_4 | 灰色_4 | +| accentBlueLighten_4 | 蓝色_4 | +| chromeCyanLighten_4 | 青色_4 | +| chromeMintLighten_4 | 薄荷色_4 | +| chromeRedLighten_4 | 红色_4 | +| chromeOrangeLighten_4 | 橙色_4 | +| chromeAmberLighten_4 | 琥珀色_4 | +| chromeVioletLighten_4 | 紫色_4 | +| chromePinkLighten_4 | 粉色_4 | +| fillColorGray_3 | 灰色_3 | +| accentBlueLighten_3 | 蓝色_3 | +| chromeCyanLighten_3 | 青色_3 | +| chromeMintLighten_3 | 薄荷色_3 | +| chromeRedLighten_3 | 红色_3 | +| chromeOrangeLighten_3 | 橙色_3 | +| chromeAmberLighten_3 | 琥珀色_3 | +| chromeVioletLighten_3 | 紫色_3 | +| chromePinkLighten_3 | 粉色_3 | + +## 查询视图 + +本接口用于获取 Smartsheet 中某个子表里全部视图信息。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_views?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "ezPcdA", + "view_ids": [ + "vPpw9C", + "vfM2tt" + ], + "offset": 0, + "limit": 1 +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | -------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| view_ids | string[] | 否 | 需要查询的视图 ID 数组 | +| offset | uint32 | 否 | 偏移量，初始值为 0 | +| limit | uint32 | 否 | 分页大小 , 每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 个视图，当总数小于 1000 时，返回全部视图；limit 最大值为 1000 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101155#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101155#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "total": 2, + "has_more": true, + "next": 1, + "views": [ + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| -------- | ------------------------------------------------------------ | -------------------------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| total | uint32 | 符合筛选条件的视图总数 | +| has_more | bool | 是否还有更多项 | +| next | uint32 | 下次下一个搜索结果的偏移量 | +| views | Object[]([View](https://developer.work.weixin.qq.com/document/path/101155#view)) | 视图数据 | + +### 参数详细说明 + +### View + +**示例** + +```json +{ + "view_id": "vabcde", + "view_title": "默认视图", + "view_type": "VIEW_TYPE_GRID" +} +``` + +视图信息： + +| 参数名 | 类型 | 描述 | +| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| view_id | string | 视图 ID | +| view_title | string | 视图标题 | +| view_type | string | 视图类型。见[ViewType](https://developer.work.weixin.qq.com/document/path/101155#viewtype) | +| property | object([ViewProperty](https://developer.work.weixin.qq.com/document/path/101155#viewproperty)) | 视图属性 | + +### ViewType + +视图类型： + +| 枚举类型 | 描述 | +| ----------------- | ---------------------------- | +| VEW_UNKNOWN | 未知类型视图，传递该值不合法 | +| VIEW_TYPE_GRID | 表格视图 | +| VIEW_TYPE_KANBAN | 看板视图 | +| VIEW_TYPE_GALLERY | 画册视图 | +| VIEW_TYPE_GANTT | 甘特视图 | + +### ViewProperty + +**示例** + +```json +{ + "auto_sort": false, + "sort_spec": {}, + "filter_spec": { + }, + "group_spec": {}, + "is_field_stat_enabled": false, + "field_visibility": { + "f1gHSR": false, + "fabcde": false + }, + "frozen_field_count": 0, + "color_config": { + "conditions": [{ + "id": "4840474257", + "type": "VIEW_COLOR_CONDITION_TYPE_CELL", + "color": "chromeAmberLighten_5", + "condition": { + "field_id": "fRCjJz", + "field_type": "FIELD_TYPE_TEXT", + "operator": "OPERATOR_CONTAINS", + "string_value": { + "value": [ + "5555" + ] + } + } + }] + } +} +``` + +**参数说明** + +| 参数名 | 类型 | 描述 | +| --------------------- | ------------------------------------------------------------ | ------------------------------------------------ | +| auto_sort | bool | 记录变更后自动重新排序 | +| sort_spec | object([SortSpec](https://developer.work.weixin.qq.com/document/path/101155#sortspec)) | 排序设置 | +| gourp_spec | object([GroupSpec](https://developer.work.weixin.qq.com/document/path/101155#groupspec)) | 分组设置 | +| filter_spec | object([FilterSpec](https://developer.work.weixin.qq.com/document/path/101155#filterspec)) | 过滤设置 | +| is_field_stat_enabled | bool | 是否使用数据统计 | +| field_visibility | object | 类似map。 key为字段ID, value为布尔值表示是否显示 | +| frozen_field_count | int32 | 冻结列数量，从首列开始 | +| color_config | object([ViewColorConfig](https://developer.work.weixin.qq.com/document/path/101155#viewcolorconfig)) | 填色设置 | + +### SortSpec + +**示例** + +```json +{ + "sort_infos": [ + { + "field_id": "FIELDID1", + "desc": false + }, + { + "field_id": "FIELDID2", + "desc": true + } + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 描述 | +| ------------------- | -------- | ------------------ | +| sort_infos | object[] | 参与排序的字段列表 | +| sort_infos.field_id | string | 字段id | +| sort_infoes.desc | bool | 是否降序 | + +### GroupSpec + +**示例** + +```json +{ + "groups": [ + { + "field_id": "FIELDID1", + "desc": false + }, + { + "field_id": "FIELDID2", + "desc": true + } + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 描述 | +| --------------- | -------- | ------------------ | +| groups | object[] | 参与分组的字段列表 | +| groups.field_id | string | 字段id | +| groups.desc | bool | 是否降序 | + +### FilterSpec + +**示例** + +```json +{ + "conjunction": "CONJUNCTION_AND", + "conditions": [ + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 描述 | +| ----------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| conjunction | string | 多个conditions之间是以and(`CONJUNCTION_AND`)还是or(`CONJUNCTION_OR`)进行组合 | +| conditions | object[]([Condition](https://developer.work.weixin.qq.com/document/path/101155#condition)) | 判断条件 | + +### Condition + +**注：不同字段类型支持的筛选不同，需要根据智能表格不同字段类型实际支持的筛选条件进行组合** + +**示例1** +过滤`FIELDID1`字段包含文本`hello world`的记录 + +```json +{ + "field_id": "FIELDID1", + "field_type": "FIELD_TYPE_TEXT", + "operator": "OPERATOR_CONTAINS", + "string_value": { + "value": [ + "hello world" + ] + } +} +``` + +**示例2** +过滤`FIELDID2`字段为用户`USERID1`的记录 + +```json +{ + "field_id": "FIELDID2", + "field_type": "FIELD_TYPE_USER", + "operator": "OPERATOR_IS", + "user_value": { + "value": ["USERID1"] + } +} +``` + +**示例3** +过滤`FIELDID3`字段为日期`2025年5月14日`的记录 + +```json +{ + "field_id": "FIELDID3", + "field_type": "FIELD_TYPE_DATE_TIME", + "operator": "OPERATOR_IS", + "date_time_value": { + "type": "DATE_TIME_TYPE_DETAIL_DATE", + "value": [ + "1747152000000" + ] + } +} +``` + + + +**参数说明** + +| 参数名 | 类型 | 描述 | +| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| field_id | string | 字段ID | +| field_type | string | 字段类型。见[FieldType](https://developer.work.weixin.qq.com/document/path/101155#fieldtype) | +| operator | string | 判断类型。见[Operator](https://developer.work.weixin.qq.com/document/path/101155#operator) | +| string_value.value | string[] | 文本、网址、电话、邮箱、地理位置、单选、多选等列类型使用。选项列为选项ID；其它为文本值 | +| number_value.value | double | 数字、进度列类型使用 | +| bool_value.value | bool | 复选框列类型使用 | +| user_value.value | string[] | 人员、创建人、最后编辑人列类型使用，值为成员ID | +| date_time_value | object([FilterDataTimeValue](https://developer.work.weixin.qq.com/document/path/101155#filterdatetimevalue)) | 日期、创建时间、最后编辑时间列类型使用 | + +### FieldType + +| 字段类型 | 说明 | +| ------------------------ | ------------ | +| FIELD_TYPE_TEXT | 文本 | +| FIELD_TYPE_NUMBER | 数字 | +| FIELD_TYPE_CHECKBOX | 复选框 | +| FIELD_TYPE_DATE_TIME | 日期 | +| FIELD_TYPE_IMAGE | 图片 | +| FIELD_TYPE_ATTACHMENT | 文件 | +| FIELD_TYPE_USER | 人员 | +| FIELD_TYPE_URL | 链接 | +| FIELD_TYPE_SELECT | 多选 | +| FIELD_TYPE_CREATED_USER | 创建人 | +| FIELD_TYPE_MODIFIED_USER | 最后编辑人 | +| FIELD_TYPE_CREATED_TIME | 创建时间 | +| FIELD_TYPE_MODIFIED_TIME | 最后编辑时间 | +| FIELD_TYPE_PROGRESS | 进度 | +| FIELD_TYPE_PHONE_NUMBER | 电话 | +| FIELD_TYPE_EMAIL | 邮箱 | +| FIELD_TYPE_SINGLE_SELECT | 单选 | +| FIELD_TYPE_LOCATION | 地理位置 | + +### Operator + +| 筛选值判断操作类型 | 说明 | +| ---------------------------- | ---------- | +| OPERATOR_UNKNOWN | 未知 | +| OPERATOR_IS | 等于 | +| OPERATOR_IS_NOT | 不等于 | +| OPERATOR_CONTAINS | 包含 | +| OPERATOR_DOES_NOT_CONTAIN | 不包含 | +| OPERATOR_IS_GREATER | 大于 | +| OPERATOR_IS_GREATER_OR_EQUAL | 大于或等于 | +| OPERATOR_IS_LESS | 小于 | +| OPERATOR_IS_LESS_OR_EQUAL | 小于或等于 | +| OPERATOR_IS_EMPTY | 为空 | +| OPERATOR_IS_NOT_EMPTY | 不为空 | + +### FilterDataTimeValue + +| 参数名 | 类型 | 描述 | | +| ------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| type | string | 日期类型。见[DateTimeType](https://developer.work.weixin.qq.com/document/path/101155#datetimetype) | | +| value | string[] | 是 | 具体日期值，type为具体日期(`DATE_TIME_TYPE_DETAIL_DATE`)时必填 | + +### DateTimeType + +| 日期值类型 | 说明 | +| ------------------------------- | -------------- | +| DATE_TIME_TYPE_DETAIL_DATE | 具体时间 | +| DATE_TIME_TYPE_TODAY | 今天 | +| DATE_TIME_TYPE_TOMORROW | 明天 | +| DATE_TIME_TYPE_YESTERDAY | 昨天 | +| DATE_TIME_TYPE_CURRENT_WEEK | 本周 | +| DATE_TIME_TYPE_LAST_WEEK | 上周 | +| DATE_TIME_TYPE_CURRENT_MONTH | 本月 | +| DATE_TIME_TYPE_THE_PAST_7_DAYS | 过去 7 天内 | +| DATE_TIME_TYPE_THE_NEXT_7_DAYS | 接下来 7 天内 | +| DATE_TIME_TYPE_LAST_MONTH | 上月 | +| DATE_TIME_TYPE_THE_PAST_30_DAYS | 过去 30 天内 | +| DATE_TIME_TYPE_THE_NEXT_30_DAYS | 接下来 30 天内 | + +### ViewColorConfig + +**示例** + +```json +{ + "conditions": [ + ] +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | -------- | +| conditions | object[]([ViewColorCondition](https://developer.work.weixin.qq.com/document/path/101155#viewcolorcondition)) | 是 | 判断条件 | + +### ViewColorCondition + +**示例** + +```json +{ + "id": "5599107762", + "type": "VIEW_COLOR_CONDITION_TYPE_CELL", + "color": "chromeOrangeLighten_5", + "condition": { + "field_id": "fMPZMg", + "field_type": "FIELD_TYPE_NUMBER", + "operator": "OPERATOR_IS", + "number_value": { + "value": 5 + } + } +} +``` + +**参数说明** + +| 参数名 | 类型 | 是否必须 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| id | string | 否 | 填色id，新增时不需要传入，更新时传入 | +| type | string | 是 | 填色类型,见([ViewColorConditionType](https://developer.work.weixin.qq.com/document/path/101155#viewcolorconditiontype)) | +| color | string | 是 | 颜色，见([ViewColor](https://developer.work.weixin.qq.com/document/path/101155#viewcolor)) | +| conditions | object[]([Condition](https://developer.work.weixin.qq.com/document/path/101155#condition)) | 是 | 判断条件 | + +### ViewColorConditionType + +| 填色类型 | 说明 | +| -------------------------------- | ------ | +| VIEW_COLOR_CONDITION_TYPE_ROW | 行 | +| VIEW_COLOR_CONDITION_TYPE_COLUMN | 列 | +| VIEW_COLOR_CONDITION_TYPE_CELL | 单元格 | + +### ViewColor + +| 颜色值 | 描述 | +| --------------------- | -------- | +| fillColorGray_5 | 灰色_5 | +| accentBlueLighten_5 | 蓝色_5 | +| chromeCyanLighten_5 | 青色_5 | +| chromeMintLighten_5 | 薄荷色_5 | +| chromeRedLighten_5 | 红色_5 | +| chromeOrangeLighten_5 | 橙色_5 | +| chromeAmberLighten_5 | 琥珀色_5 | +| chromeVioletLighten_5 | 紫色_5 | +| chromePinkLighten_5 | 粉色_5 | +| fillColorGray_4 | 灰色_4 | +| accentBlueLighten_4 | 蓝色_4 | +| chromeCyanLighten_4 | 青色_4 | +| chromeMintLighten_4 | 薄荷色_4 | +| chromeRedLighten_4 | 红色_4 | +| chromeOrangeLighten_4 | 橙色_4 | +| chromeAmberLighten_4 | 琥珀色_4 | +| chromeVioletLighten_4 | 紫色_4 | +| chromePinkLighten_4 | 粉色_4 | +| fillColorGray_3 | 灰色_3 | +| accentBlueLighten_3 | 蓝色_3 | +| chromeCyanLighten_3 | 青色_3 | +| chromeMintLighten_3 | 薄荷色_3 | +| chromeRedLighten_3 | 红色_3 | +| chromeOrangeLighten_3 | 橙色_3 | +| chromeAmberLighten_3 | 琥珀色_3 | +| chromeVioletLighten_3 | 紫色_3 | +| chromePinkLighten_3 | 粉色_3 | + +## 添加字段 + +本接口用于在智能表中的某个子表里添加一列或多列新字段。单表最多允许有150个字段。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_fields?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "fields": [{ + "field_title": "TITLE", + "field_type": "FIELD_TYPE_TEXT" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------------------------------------------------------------ | -------- | ----------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| fields | object [] [(AddFiled)](https://developer.work.weixin.qq.com/document/path/99904#addfield) | 是 | 字段详情 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99904#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99904#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "fields": [{ + "field_id": "FIELDID", + "field_title": "TITLE", + "field_type": "FIELD_TYPE_TEXT" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| fields | object [] [(Filed)](https://developer.work.weixin.qq.com/document/path/99904#field) | 字段详情 | + +### 参数详细说明 + +### AddField + +字段信息： + +![img](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHJ4PSI4IiBmaWxsPSIjQjM2NzFEIi8+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik04IDNDNy40NDc3MiAzIDcgMy40NDc3MiA3IDRWOEM3IDguNTUyMjggNy40NDc3MiA5IDggOUM4LjU1MjI4IDkgOSA4LjU1MjI4IDkgOFY0QzkgMy40NDc3MiA4LjU1MjI4IDMgOCAzWk04IDExQzcuNDQ3NzIgMTEgNyAxMS40NDc3IDcgMTJDNyAxMi41NTIzIDcuNDQ3NzIgMTMgOCAxM0M4LjU1MjI4IDEzIDkgMTIuNTUyMyA5IDEyQzkgMTEuNDQ3NyA4LjU1MjI4IDExIDggMTFaIiBmaWxsPSJ3aGl0ZSIvPjwvc3ZnPg==)注意 + +字段属性与字段类型是匹配的，一种字段类型对应一种字段属性 + + + +| 参数名 | 类型 | 是否必填 | 描述 | +| ---------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| field_title | string | 是 | 字段标题 | +| field_type | string | 是 | 字段类型，见[FieldType](https://developer.work.weixin.qq.com/document/path/99904#53114/fieldtype) ，必须为原属性 | +| property_number | object([NumberFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/numberfieldproperty)) | 是 | `数字` 类型的字段属性 | +| property_checkbox | object([CheckboxFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/checkboxfieldproperty)) | 否 | `复选框` 类型的字段属性 | +| property_date_time | object([DateTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/datetimefieldproperty)) | 是 | `日期` 类型的字段属性 | +| property_attachment | object([AttachmentFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/attachmentfieldproperty)) | 否 | `文件` 类型的字段属性 | +| property_user | object([UserFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/userfieldproperty)) | 否 | `人员` 类型的字段属性 | +| property_url | object([UrlFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/urlfieldproperty)) | 是 | `超链接` 类型的字段属性 | +| property_select | object([SelectFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/selectfieldproperty)) | 是 | `多选` 类型的字段属性 | +| property_created_time | object([CreatedTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/createdtimefieldproperty)) | 是 | `创建时间` 类型的字段属性 | +| property_modified_time | object([ModifiedTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/modifiedtimefieldproperty)) | 是 | `最后编辑时间` 类型的字段属性 | +| property_progress | object([ProgressFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/progressfieldproperty)) | 是 | `进度` 类型的字段属性 | +| property_single_select | object([SingleSelectFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/singleselectfieldproperty)) | 是 | `单选` 类型的字段属性 | +| property_reference | object([ReferenceFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/referencefieldproperty)) | 是 | `引用` 类型的字段属性 | +| property_location | object([LocationFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/locationfieldproperty)) | 是 | `地理位置` 类型的字段属性 | +| property_auto_number | object([AutoNumberFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/autonumberfieldproperty)) | 是 | `自动编号` 类型的字段属性 | +| property_currency | object([CurrencyFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/autonumberfieldproperty)) | 是 | `货币` 类型的字段属性 | +| property_ww_group | object([WwGroupFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/wwgroupfieldproperty)) | 否 | `群` 类型的字段属性 | +| property_percentage | object([PercentageFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/percentagefieldproperty)) | 否 | `百分数` 类型的字段属性 | +| property_barcode | object([BarcodeFieldProperty](https://developer.work.weixin.qq.com/document/path/99904#53114/barcodefieldproperty)) | 否 | `条码` 类型的字段属性 | + +### FieldType + +| 字段类型 | 说明 | +| ------------------------ | ------------ | +| FIELD_TYPE_TEXT | 文本 | +| FIELD_TYPE_NUMBER | 数字 | +| FIELD_TYPE_CHECKBOX | 复选框 | +| FIELD_TYPE_DATE_TIME | 日期 | +| FIELD_TYPE_IMAGE | 图片 | +| FIELD_TYPE_ATTACHMENT | 文件 | +| FIELD_TYPE_USER | 成员 | +| FIELD_TYPE_URL | 超链接 | +| FIELD_TYPE_SELECT | 多选 | +| FIELD_TYPE_CREATED_USER | 创建人 | +| FIELD_TYPE_MODIFIED_USER | 最后编辑人 | +| FIELD_TYPE_CREATED_TIME | 创建时间 | +| FIELD_TYPE_MODIFIED_TIME | 最后编辑时间 | +| FIELD_TYPE_PROGRESS | 进度 | +| FIELD_TYPE_PHONE_NUMBER | 电话 | +| FIELD_TYPE_EMAIL | 邮件 | +| FIELD_TYPE_SINGLE_SELECT | 单选 | +| FIELD_TYPE_REFERENCE | 关联 | +| FIELD_TYPE_LOCATION | 地理位置 | +| FIELD_TYPE_CURRENCY | 货币 | +| FIELD_TYPE_WWGROUP | 群 | +| FIELD_TYPE_AUTONUMBER | 自动编号 | +| FIELD_TYPE_PERCENTAGE | 百分数 | +| FIELD_TYPE_BARCODE | 条码 | + +### NumberFieldProperty + +数字类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/99904#53117/decimalplaces)) | 表示小数点的位数，即数字精度 | +| use_separate | bool | 是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000 | + +### CheckboxFieldProperty + +复选框类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------- | ---- | ------------------ | +| checked | bool | 新增时是否默认勾选 | + +### DateTimeFieldProperty + +日期类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| --------- | ------------------------------------------------------------ | ---------------------------- | +| format | string([Format](https://developer.work.weixin.qq.com/document/path/99904#53117/format)) | 设置日期格式 | +| auto_fill | bool | 新建记录时，是否自动填充时间 | + +### AttachmentFieldProperty + +文件类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------ | ------------------------------------------------------------ | ------------ | +| display_mode | string([DisplayMode](https://developer.work.weixin.qq.com/document/path/99904#53117/displaymode)) | 设置日期格式 | + +### UserFieldProperty + +成员类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ----------- | ---- | -------------------------------- | +| is_multiple | bool | 允许添加多个人员 | +| is_notified | bool | 添加人员时通知用户，关闭后不通知 | + +### UrlFieldProperty + +超链接类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | -------------- | +| type | string([LinkType](https://developer.work.weixin.qq.com/document/path/99904#53117/linktype)) | 超链接展示样式 | + +### SelectFieldProperty + +多选类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------ | ------------------------------------------------------------ | -------------------------------------------- | +| is_quick_add | bool | 是否允许填写时新增选项，用户不需要设置该参数 | +| options | object [] ]([Option](https://developer.work.weixin.qq.com/document/path/99904#53117/option)) | 多选选项的格式设置 | + +### CreatedTimeFieldProperty + +创建时间类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | ------------ | +| format | string([Format](https://developer.work.weixin.qq.com/document/path/99904#53117/format)) | 设置日期格式 | + +### ModifiedTimeFieldProperty + +最后编辑时间类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | ------------ | +| format | string([Format](https://developer.work.weixin.qq.com/document/path/99904#53117/format)) | 设置日期格式 | + +### ProgressFieldProperty + +进度类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | -------- | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/99904#53117/decimalplaces)) | 小数位数 | + +### SingleSelectFieldProperty + +单选类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------ | ------------------------------------------------------------ | -------------------------------------------- | +| is_quick_add | bool | 是否允许填写时新增选项，用户不需要设置该参数 | +| options | object [] ([Option](https://developer.work.weixin.qq.com/document/path/99904#53117/option)) | 单选选项的格式设置 | + +### ReferenceFieldProperty + +关联字段属性信息： + +| 参数名 | 类型 | 描述 | +| ----------- | ------ | ------------------------------------ | +| sub_id | string | 关联的子表id，为空时，表示关联本子表 | +| filed_id | string | 关联的字段id | +| is_multiple | bool | 是否允许多选 | +| view_id | string | 视图id | + +### LocationFieldProperty + +地理位置字段属性信息： + +| 参数名 | 类型 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | +| input_type | string([LocationInputType](https://developer.work.weixin.qq.com/document/path/99904#53117/locationinputtype)) | 输入类型 | + +### LocationFieldProperty + +地理位置字段属性信息： + +| 参数名 | 类型 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | +| input_type | string([LocationInputType](https://developer.work.weixin.qq.com/document/path/99904#53117/locationinputtype)) | 输入类型 | + +### AutoNumberFieldProperty + +自动编号字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------------------ | ------------------------------------------------------------ | ------------------ | +| type | string([NumberType](https://developer.work.weixin.qq.com/document/path/99904#53117/numbertype)) | 输入类型 | +| rules | object[] ([NumberRule](https://developer.work.weixin.qq.com/document/path/99904#53117/numberrule)) | 自定义规则 | +| reformat_existing_record | bool | 是否应用于已有编号 | + +### CurrencyFieldProperty + +货币类型字段属性 + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| currency_type | string([CurrencyType](https://developer.work.weixin.qq.com/document/path/99904#53117/currencytype)) | 输入类型 | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/99904#53117/decimalplaces)) | 表示小数点的位数，即数字精度 | +| use_separate | bool | 是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000 | + + + +### WwGroupFieldProperty + +群类型的字段属性 + +| 参数名 | 类型 | 描述 | +| -------------- | ---- | ---------------- | +| allow_multiple | bool | 是否允许多个群聊 | + +### PercentageFieldProperty + +百分数类型的字段属性 + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/99904#53117/decimalplaces)) | 表示小数点的位数，即数字精度 | +| use_separate | bool | 是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000 | + +### BarcodeFieldProperty + +条码类型的字段属性 + +| 参数名 | 类型 | 描述 | +| ---------------- | ---- | ---------------- | +| mobile_scan_only | bool | 仅限手机扫描录入 | + +## 删除字段 + +本接口用于删除智能表中的某个子表里的一列或多列字段。。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_fields?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "field_ids": [ + "FIELDID" + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| --------- | -------- | -------- | -------------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| field_ids | string[] | 是 | 需要删除的字段id列表 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99905#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99905#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 更新字段 + +本接口用于更新智能中的某个子表里的一个或多个字段的标题和字段属性信息。 + +![img](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHJ4PSI4IiBmaWxsPSIjQjM2NzFEIi8+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik04IDNDNy40NDc3MiAzIDcgMy40NDc3MiA3IDRWOEM3IDguNTUyMjggNy40NDc3MiA5IDggOUM4LjU1MjI4IDkgOSA4LjU1MjI4IDkgOFY0QzkgMy40NDc3MiA4LjU1MjI4IDMgOCAzWk04IDExQzcuNDQ3NzIgMTEgNyAxMS40NDc3IDcgMTJDNyAxMi41NTIzIDcuNDQ3NzIgMTMgOCAxM0M4LjU1MjI4IDEzIDkgMTIuNTUyMyA5IDEyQzkgMTEuNDQ3NyA4LjU1MjI4IDExIDggMTFaIiBmaWxsPSJ3aGl0ZSIvPjwvc3ZnPg==)注意 + +该接口只能更新字段名、字段属性，不能更新字段类型。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_fields?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "fields": [{ + "field_id": "FIELD_ID", + "field_title": "TITLE", + "field_type": "FIELD_TYPE_TEXT" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------------------------------------------------------------ | -------- | ----------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| fields | object [][(UpdateField)](https://developer.work.weixin.qq.com/document/path/99906#updatefield) | 是 | 字段详情 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99906#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99906#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "fields": [{ + "field_id": "FIELDID", + "field_title": "TITLE", + "field_type": "FIELD_TYPE_TEXT" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| fields | object [][(Field)](https://developer.work.weixin.qq.com/document/path/99906#53117/field) | 字段详情 | + +### 参数详细说明 + +### UpdateField + +字段信息： + +![img](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHJ4PSI4IiBmaWxsPSIjQjM2NzFEIi8+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik04IDNDNy40NDc3MiAzIDcgMy40NDc3MiA3IDRWOEM3IDguNTUyMjggNy40NDc3MiA5IDggOUM4LjU1MjI4IDkgOSA4LjU1MjI4IDkgOFY0QzkgMy40NDc3MiA4LjU1MjI4IDMgOCAzWk04IDExQzcuNDQ3NzIgMTEgNyAxMS40NDc3IDcgMTJDNyAxMi41NTIzIDcuNDQ3NzIgMTMgOCAxM0M4LjU1MjI4IDEzIDkgMTIuNTUyMyA5IDEyQzkgMTEuNDQ3NyA4LjU1MjI4IDExIDggMTFaIiBmaWxsPSJ3aGl0ZSIvPjwvc3ZnPg==)注意 + +字段属性与字段类型是匹配的，一种字段类型对应一种字段属性 +更新时field_title和property_number至少需要传一个，field_title不能被更新为原值 + + + +| 参数名 | 类型 | 是否必填 | 描述 | +| ---------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| field_id | string | 是 | 字段 ID，更新字段属性时需要填写该字段，但字段 ID 不能被更新 | +| field_title | string | 否 | 字段标题，需要更新为的字段标题 | +| field_type | string | 是 | 字段类型，见[FieldType](https://developer.work.weixin.qq.com/document/path/99906#53114/fieldtype) ，必须为原属性 | +| property_text | object | 否 | `文本` 类型的字段属性为空 | +| property_number | object([NumberFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/numberfieldproperty)) | 否 | `数字` 类型的字段属性 | +| property_checkbox | object([CheckboxFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/checkboxfieldproperty)) | 否 | `复选框` 类型的字段属性 | +| property_date_time | object([DateTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/datetimefieldproperty)) | 否 | `日期` 类型的字段属性 | +| property_attachment | object([AttachmentFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/attachmentfieldproperty)) | 否 | `文件` 类型的字段属性 | +| property_user | object([UserFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/userfieldproperty)) | 否 | `人员` 类型的字段属性 | +| property_url | object([UrlFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/urlfieldproperty)) | 否 | `超链接` 类型的字段属性 | +| property_select | object([SelectFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/selectfieldproperty)) | 否 | `多选` 类型的字段属性 | +| property_created_user | object | 否 | `创建人` 类型的字段属性为空 | +| property_modified_user | object | 否 | `最后编辑人` 类型的字段属性为空 | +| property_created_time | object([CreatedTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/createdtimefieldproperty)) | 否 | `创建时间` 类型的字段属性 | +| property_modified_time | object([ModifiedTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/modifiedtimefieldproperty)) | 否 | `最后编辑时间` 类型的字段属性 | +| property_progress | object([ProgressFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/progressfieldproperty)) | 否 | `进度` 类型的字段属性 | +| property_single_select | object([SingleSelectFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/singleselectfieldproperty)) | 否 | `单选` 类型的字段属性 | +| property_reference | object([PropertyReference](https://developer.work.weixin.qq.com/document/path/99906#53114/propertyreference)) | 否 | `引用` 类型的字段属性 | +| property_location | object([LocationFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/locationfieldproperty)) | 否 | `地理位置` 类型的字段属性 | +| property_auto_number | object([AutoNumberFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/autonumberfieldproperty)) | 否 | `自动编号` 类型的字段属性 | +| property_currency | object([CurrencyFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/autonumberfieldproperty)) | 否 | `货币` 类型的字段属性 | +| property_ww_group | object([WwGroupFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/wwgroupfieldproperty)) | 否 | `群` 类型的字段属性 | +| property_percentage | object([PercentageFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/percentagefieldproperty)) | 否 | `百分数` 类型的字段属性 | +| property_barcode | object([BarcodeFieldProperty](https://developer.work.weixin.qq.com/document/path/99906#53114/barcodefieldproperty)) | 否 | `条码` 类型的字段属性 | + +## 查询字段 + +本接口用于获取智能表中某个子表下字段信息，该接口可以完成下面三种功能：获取全部字段信息、依据字段名获取对应字段、依据字段 ID 获取对应字段信息。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_fields?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "offset": 0, + "limit": 10 +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------ | --------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| view_id | string | 否 | 视图 ID | +| field_ids | string [] | 否 | 由字段 ID 组成的 JSON 数组 | +| field_titles | string [] | 否 | 由字段标题组成的 JSON 数组 | +| offset | int | 否 | 偏移量，初始值为 0 | +| limit | int | 否 | 分页大小 , 每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 个字段，当总数小于 1000 时，返回全部字段；limit 最大值为 1000 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101157#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101157#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "total": 1, + "fields": [{ + "field_id": "ID1", + "field_title": "TITLE1", + "field_type": "FIELD_TYPE_TEXT" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| total | Object | 字段总数 | +| fields | object [][(Field)](https://developer.work.weixin.qq.com/document/path/101157#field) | 字段详情 | + +### 参数详细说明 + +### Field + +字段信息： + +![img](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHJ4PSI4IiBmaWxsPSIjQjM2NzFEIi8+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik04IDNDNy40NDc3MiAzIDcgMy40NDc3MiA3IDRWOEM3IDguNTUyMjggNy40NDc3MiA5IDggOUM4LjU1MjI4IDkgOSA4LjU1MjI4IDkgOFY0QzkgMy40NDc3MiA4LjU1MjI4IDMgOCAzWk04IDExQzcuNDQ3NzIgMTEgNyAxMS40NDc3IDcgMTJDNyAxMi41NTIzIDcuNDQ3NzIgMTMgOCAxM0M4LjU1MjI4IDEzIDkgMTIuNTUyMyA5IDEyQzkgMTEuNDQ3NyA4LjU1MjI4IDExIDggMTFaIiBmaWxsPSJ3aGl0ZSIvPjwvc3ZnPg==)注意 + +字段属性与字段类型是匹配的，一种字段类型对应一种字段属性 + + + +| 参数名 | 类型 | 描述 | +| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| field_id | string | 字段 ID | +| field_title | string | 字段标题 | +| field_type | string | 字段类型，见[FieldType](https://developer.work.weixin.qq.com/document/path/101157#fieldtype) | +| property_number | object([NumberFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#numberfieldproperty)) | `数字` 类型的字段属性 | +| property_checkbox | object([CheckboxFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#checkboxfieldproperty)) | `复选框` 类型的字段属性 | +| property_date_time | object([DateTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#datetimefieldproperty)) | `日期` 类型的字段属性 | +| property_attachment | object([AttachmentFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#attachmentfieldproperty)) | `文件` 类型的字段属性 | +| property_user | object([UserFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#userfieldproperty)) | `人员` 类型的字段属性 | +| property_url | object([UrlFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#urlfieldproperty)) | `超链接` 类型的字段属性 | +| property_select | object([SelectFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#selectfieldproperty)) | `多选` 类型的字段属性 | +| property_created_time | object([CreatedTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#createdtimefieldproperty)) | `创建时间` 类型的字段属性 | +| property_modified_time | object([ModifiedTimeFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#modifiedtimefieldproperty)) | `最后编辑时间` 类型的字段属性 | +| property_progress | object([ProgressFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#progressfieldproperty)) | `进度` 类型的字段属性 | +| property_single_select | object([SingleSelectFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#singleselectfieldproperty)) | `单选` 类型的字段属性 | +| property_reference | object([PropertyReference](https://developer.work.weixin.qq.com/document/path/101157#propertyreference)) | `引用` 类型的字段属性 | +| property_location | object([LocationFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#locationfieldproperty)) | `地理位置` 类型的字段属性 | +| property_auto_number | object([AutoNumberFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#autonumberfieldproperty)) | `自动编号` 类型的字段属性 | +| property_currency | object([CurrencyFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#autonumberfieldproperty)) | `货币` 类型的字段属性 | +| property_ww_group | object([WwGroupFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#wwgroupfieldproperty)) | `群` 类型的字段属性 | +| property_percentage | object([PercentageFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#percentagefieldproperty)) | `百分数` 类型的字段属性 | +| property_barcode | object([BarcodeFieldProperty](https://developer.work.weixin.qq.com/document/path/101157#barcodefieldproperty)) | `条码` 类型的字段属性 | + +### FieldType + +| 字段类型 | 说明 | +| ------------------------ | ------------ | +| FIELD_TYPE_TEXT | 文本 | +| FIELD_TYPE_NUMBER | 数字 | +| FIELD_TYPE_CHECKBOX | 复选框 | +| FIELD_TYPE_DATE_TIME | 日期 | +| FIELD_TYPE_IMAGE | 图片 | +| FIELD_TYPE_ATTACHMENT | 文件 | +| FIELD_TYPE_USER | 成员 | +| FIELD_TYPE_URL | 超链接 | +| FIELD_TYPE_SELECT | 多选 | +| FIELD_TYPE_CREATED_USER | 创建人 | +| FIELD_TYPE_MODIFIED_USER | 最后编辑人 | +| FIELD_TYPE_CREATED_TIME | 创建时间 | +| FIELD_TYPE_MODIFIED_TIME | 最后编辑时间 | +| FIELD_TYPE_PROGRESS | 进度 | +| FIELD_TYPE_PHONE_NUMBER | 电话 | +| FIELD_TYPE_EMAIL | 邮件 | +| FIELD_TYPE_SINGLE_SELECT | 单选 | +| FIELD_TYPE_REFERENCE | 关联 | +| FIELD_TYPE_LOCATION | 地理位置 | +| FIELD_TYPE_FORMULA | 公式 | +| FIELD_TYPE_CURRENCY | 货币 | +| FIELD_TYPE_WWGROUP | 群 | +| FIELD_TYPE_AUTONUMBER | 自动编号 | +| FIELD_TYPE_PERCENTAGE | 百分数 | +| FIELD_TYPE_BARCODE | 条码 | + +### NumberFieldProperty + +数字类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/101157#decimalplaces)) | 表示小数点的位数，即数字精度 | +| use_separate | bool | 是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000 | + +### CheckboxFieldProperty + +复选框类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------- | ---- | ------------------ | +| checked | bool | 新增时是否默认勾选 | + +### DateTimeFieldProperty + +日期类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| --------- | ------------------------------------------------------------ | ---------------------------- | +| format | string([Format](https://developer.work.weixin.qq.com/document/path/101157#format)) | 设置日期格式 | +| auto_fill | bool | 新建记录时，是否自动填充时间 | + +### AttachmentFieldProperty + +文件类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------ | ------------------------------------------------------------ | -------- | +| display_mode | string([DisplayMode](https://developer.work.weixin.qq.com/document/path/101157#displaymode)) | 展示样式 | + +### UserFieldProperty + +成员类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ----------- | ---- | -------------------------------- | +| is_multiple | bool | 允许添加多个人员 | +| is_notified | bool | 添加人员时通知用户，关闭后不通知 | + +### UrlFieldProperty + +超链接类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | -------------- | +| type | string([LinkType](https://developer.work.weixin.qq.com/document/path/101157#linktype)) | 超链接展示样式 | + +### SelectFieldProperty + +多选类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------ | ------------------------------------------------------------ | -------------------------------------------- | +| is_quick_add | bool | 是否允许填写时新增选项，用户不需要设置该参数 | +| options | object [] ]([Option](https://developer.work.weixin.qq.com/document/path/101157#option)) | 多选选项的格式设置 | + +### CreatedTimeFieldProperty + +创建时间类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | ------------ | +| format | string([Format](https://developer.work.weixin.qq.com/document/path/101157#format)) | 设置日期格式 | + +### ModifiedTimeFieldProperty + +最后编辑时间类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | ------------ | +| format | string([Format](https://developer.work.weixin.qq.com/document/path/101157#format)) | 设置日期格式 | + +### ProgressFieldProperty + +进度类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | -------- | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/101157#decimalplaces)) | 小数位数 | + +### SingleSelectFieldProperty + +单选类型字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------ | ------------------------------------------------------------ | -------------------------------------------- | +| is_quick_add | bool | 是否允许填写时新增选项，用户不需要设置该参数 | +| options | object [] ([Option](https://developer.work.weixin.qq.com/document/path/101157#option)) | 单选选项的格式设置 | + +### ReferenceFieldProperty + +关联字段属性信息： + +| 参数名 | 类型 | 描述 | +| ----------- | ------ | ------------------------------------ | +| sub_id | string | 关联的子表id，为空时，表示关联本子表 | +| filed_id | string | 关联的字段id | +| is_multiple | bool | 是否允许多选 | +| view_id | string | 视图id | + +### LocationFieldProperty + +地理位置字段属性信息： + +| 参数名 | 类型 | 描述 | +| ---------- | ------------------------------------------------------------ | -------- | +| input_type | string([LocationInputType](https://developer.work.weixin.qq.com/document/path/101157#locationinputtype)) | 输入类型 | + +### AutoNumberFieldProperty + +自动编号字段属性信息： + +| 参数名 | 类型 | 描述 | +| ------------------------ | ------------------------------------------------------------ | ------------------ | +| type | string([NumberType](https://developer.work.weixin.qq.com/document/path/101157#numbertype)) | 输入类型 | +| rules | object[] ([NumberRule](https://developer.work.weixin.qq.com/document/path/101157#numberrule)) | 自定义规则 | +| reformat_existing_record | bool | 是否应用于已有编号 | + +### CurrencyFieldProperty + +货币类型字段属性 + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| currency_type | string([CurrencyType](https://developer.work.weixin.qq.com/document/path/101157#currencytype)) | 输入类型 | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/101157#53117/decimalplaces)) | 表示小数点的位数，即数字精度 | +| use_separate | bool | 是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000 | + + + +### WwGroupFieldProperty + +群类型的字段属性 + +| 参数名 | 类型 | 描述 | +| -------------- | ---- | ---------------- | +| allow_multiple | bool | 是否允许多个群聊 | + +### PercentageFieldProperty + +百分数类型的字段属性 + +| 参数名 | 类型 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| decimal_places | int([DecimalPlaces](https://developer.work.weixin.qq.com/document/path/101157#53117/decimalplaces)) | 表示小数点的位数，即数字精度 | +| use_separate | bool | 是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000 | + +### BarcodeFieldProperty + +条码类型的字段属性 + +| 参数名 | 类型 | 描述 | +| ---------------- | ---- | ---------------- | +| mobile_scan_only | bool | 仅限手机扫描录入 | + +### DecimalPlaces + +小数点后的位数： + +| 数值 | 描述 | +| ---- | ---------------------------- | +| -1 | 显示原值 | +| 0 | 代表整数 | +| 1 | 精确到小数点后一位（1.0） | +| 2 | 精确到小数点后两位（1.00） | +| 3 | 精确到小数点后三位（1.000） | +| 4 | 精确到小数点后四位（1.0000） | + +### Format + +日期格式： + +| 字符串 | 描述 | +| ------------------------ | ------------------------- | +| yyyy"年"m"月"d"日" | 2018 年 4 月 20 日 | +| yyyy-mm-dd" | 2018-04-20 | +| yyyy/m/d | 2018/4/20 | +| m"月"d"日" | 4 月 20 日 | +| yyyy"年"m"月"d"日" dddd | 2018 年 4 月 20 日 星期五 | +| yyyy"年"m"月"d"日" hh:mm | 2018 年 4 月 20 日 14:00 | +| yyyy-mm-dd hh:mm | 2018-04-20 14:00 | +| m/d/yyyy | 4/20/2018 | +| d/m/yyyy | 20/4/2018 | + +### LinkType + +超链接展示样式可选值： + +| 样式 | 描述 | +| ------------------- | -------- | +| LINK_TYPE_PURE_TEXT | 文字 | +| LINK_TYPE_ICON_TEXT | 图标文字 | + +### Option + +Option 参数： + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | ---------------- | +| id | string | 选项 ID | +| text | string | 要填写的选项内容 | +| style | int([Style](https://developer.work.weixin.qq.com/document/path/101157#style)) | 选项颜色 | + +### Style + +选项颜色： + +| 数值 | 描述 | +| ---- | ------- | +| 1 | 浅红1 | +| 2 | 浅橙1 | +| 3 | 浅天蓝1 | +| 4 | 浅绿1 | +| 5 | 浅紫1 | +| 6 | 浅粉红1 | +| 7 | 浅灰1 | +| 8 | 白 | +| 9 | 灰 | +| 10 | 浅蓝1 | +| 11 | 浅蓝2 | +| 12 | 蓝 | +| 13 | 浅天蓝2 | +| 14 | 天蓝 | +| 15 | 浅绿2 | +| 16 | 绿 | +| 17 | 浅红2 | +| 18 | 红 | +| 19 | 浅橙2 | +| 20 | 橙 | +| 21 | 浅黄1 | +| 22 | 浅黄2 | +| 23 | 黄 | +| 24 | 浅紫2 | +| 25 | 紫 | +| 26 | 浅粉红2 | +| 27 | 粉红 | + +### DisplayMode + +展示样式 + +| 展示样式 | 说明 | +| ----------------- | -------- | +| DISPLAY_MODE_LIST | 列表样式 | +| DISPLAY_MODE_GRID | 宫格样式 | + +### LocationInputType + +地理位置输入类型 + +| 地理位置输入类型 | 说明 | +| -------------------------- | -------- | +| LOCATION_INPUT_TYPE_MANUAL | 手动输入 | +| LOCATION_INPUT_TYPE_AUTO | 自动定位 | + +### NumberType + +自动编号类型 + +| 自动编号类型 | 说明 | +| ------------------ | ------------ | +| NUMBER_TYPE_INCR | 自增数字类型 | +| NUMBER_TYPE_CUSTOM | 自定义类型 | + +### NumberRule + +| 自动编号规则 | 类型 | | 说明 | +| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ---- | +| type | string[NumberRuleType](https://developer.work.weixin.qq.com/document/path/101157#numberruletype) | 规则类型 | | +| value | string | 存放创建时间格式[CreateTimeFormat](https://developer.work.weixin.qq.com/document/path/101157#createtimeformat) 或固定字符，自增数字位数 | | + +### CreateTimeFormat + +| 格式 | 说明 | +| -------- | -------- | +| YYYYMMDD | 20240301 | +| YYYYMM | 202403 | +| MMDD | 0301 | +| YYYY | 2024 | +| MM | 03 | +| DD | 01 | + +### NumberRuleType + +数字规则类型 + +| 数字规则类型 | 说明 | +| --------------------------- | -------- | +| NUMBER_RULE_TYPE_INCR | 自增id | +| NUMBER_RULE_TYPE_FIXED_CHAR | 固定字符 | +| NUMBER_RULE_TYPE_TIME | 创建时间 | + +### CurrencyType + +货币符号 + +| 货币符号类型 | 说明 | +| ----------------- | -------------- | +| CURRENCY_TYPE_CNY | 人民币 | +| CURRENCY_TYPE_USD | 美元 | +| CURRENCY_TYPE_EUR | 欧元 | +| CURRENCY_TYPE_GBP | 英镑 | +| CURRENCY_TYPE_JPY | 日元 | +| CURRENCY_TYPE_KRW | 韩元 | +| CURRENCY_TYPE_HKD | 港元 | +| CURRENCY_TYPE_MOP | 澳门元 | +| CURRENCY_TYPE_TWD | 新台币 | +| CURRENCY_TYPE_AED | 阿联酋迪拉姆 | +| CURRENCY_TYPE_AUD | 澳大利亚元 | +| CURRENCY_TYPE_BRL | 巴西雷亚尔 | +| CURRENCY_TYPE_CAD | 加拿大元 | +| CURRENCY_TYPE_CHF | 瑞士法郎 | +| CURRENCY_TYPE_IDR | 印尼卢比 | +| CURRENCY_TYPE_INR | 印度卢比 | +| CURRENCY_TYPE_MXN | 墨西哥比索 | +| CURRENCY_TYPE_MYR | 马来西亚林吉特 | +| CURRENCY_TYPE_PHP | 菲律宾比索 | +| CURRENCY_TYPE_PLN | 波兰兹罗提 | +| CURRENCY_TYPE_RUB | 俄罗斯卢布 | +| CURRENCY_TYPE_SGD | 新加坡元 | +| CURRENCY_TYPE_THB | 泰国铢 | +| CURRENCY_TYPE_TRY | 土耳其里拉 | +| CURRENCY_TYPE_VND | 越南盾 | + +## 添加记录 + +本接口用于在 Smartsheet 中的某个子表里添加一行或多行新记录。单表最多允许有100000行记录，15000000个单元格。 +**注意** +不能通过添加记录接口给创建时间、最后编辑时间、创建人和最后编辑人四种类型的字段添加记录。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_records?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", + "records": [{ + "values": { + "FIELD_TITLE": [{ + "type": "text", + "text": "文本内容" + }] + } + }] +} +``` + +或 + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "key_type": "CELL_VALUE_KEY_TYPE_FIELD_ID", + "records": [{ + "values": { + "FIELD_ID": [{ + "type": "text", + "text": "文本内容" + }] + } + }] +} +``` + +- FIELD_TITLE和FIELD_ID需要替换为字段标题或者字段ID + + + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------------------------------------------------------------ | -------- | ---------------------------------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| key_type | string([CellValueKeyType](https://developer.work.weixin.qq.com/document/path/99907#cellvaluekeytype)) | 否 | 返回记录中单元格的key类型，默认用标题 | +| records | Object[]([AddRecord](https://developer.work.weixin.qq.com/document/path/99907#addrecord)) | 是 | 需要添加的记录的具体内容组成的 JSON 数组 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99907#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99907#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "records": [ + + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ------------------------------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| records | Object[]([CommonRecord](https://developer.work.weixin.qq.com/document/path/99907#commonrecord)) | 由添加成功的记录的具体内容组成的 JSON 数组 | + +### 参数详细说明 + + + +### CellValueKeyType + +记录([CommonRecord](https://developer.work.weixin.qq.com/document/path/99907#commonrecord) 或 [AddRecord](https://developer.work.weixin.qq.com/document/path/99907#addrecord))中key的类型 + +| 枚举类型 | 描述 | +| ------------------------------- | ----------------- | +| CELL_VALUE_KEY_TYPE_FIELD_TITLE | key用字段标题表示 | +| CELL_VALUE_KEY_TYPE_FIELD_ID | key用字段 ID 表示 | + +### AddRecord + +添加记录： + +| 参数名 | 类型 | 描述 | +| ------ | ------ | ------------------------------------------------------------ | +| values | Object | 记录的具体内容，key 为字段标题或字段 ID ，value 详见([Value](https://developer.work.weixin.qq.com/document/path/99907#value)) | + +### CommonRecord + +在 Smartsheet 的某个表格中添加记录响应、更新记录请求和更新记录响应的通用参数： + +| 参数名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------------------------ | +| record_id | string | 记录 ID | +| values | Object | 记录的具体内容，key 为字段标题或字段 ID ，value 详见([Value](https://developer.work.weixin.qq.com/document/path/99907#value)) | + + + +### Value + +各种类型的字段对应的单元格的值 + +| 字段类型 | 单元格值类型 | 描述 | +| ------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 文本(FIELD_TYPE_TEXT) | Object[]([CellTextValue](https://developer.work.weixin.qq.com/document/path/99907#celltextvalue)) | | +| 数字(FIELD_TYPE_NUMBER) | double | | +| 复选框(FIELD_TYPE_CHECKBOX) | bool | | +| 日期(FIELD_TYPE_DATE_TIME) | string(以毫秒为单位的unix时间戳) | | +| 图片(FIELD_TYPE_IMAGE) | Object[]([CellImageValue](https://developer.work.weixin.qq.com/document/path/99907#cellimagevalue)) | | +| 文件(FIELD_TYPE_ATTACHMENT) | Object[]([CellAttachmentValue](https://developer.work.weixin.qq.com/document/path/99907#cellattchmentvalue)) | | +| 成员(FIELD_TYPE_USER) | Object[]([CellUserValue](https://developer.work.weixin.qq.com/document/path/99907#celluservalue)) | | +| 链接(FIELD_TYPE_URL) | Object[]([CellUrlValue](https://developer.work.weixin.qq.com/document/path/99907#cellurlvalue)) | 数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接 | +| 多选(FIELD_TYPE_SELECT) | Object[]([Option](https://developer.work.weixin.qq.com/document/path/99907#option)) | | +| 进度(FIELD_TYPE_PROGRESS) | double | | +| 电话(FIELD_TYPE_PHONE_NUMBER) | string | | +| 邮箱(FIELD_TYPE_EMAIL) | string | | +| 单选(FIELD_TYPE_SINGLE_SELECT) | Object[]([Option](https://developer.work.weixin.qq.com/document/path/99907#option)) | | +| 地理位置(FIELD_TYPE_LOCATION) | Object[]([CellLocationValue](https://developer.work.weixin.qq.com/document/path/99907#celllocationvalue)) | 长度不大于1的数组。 | +| 货币(FIELD_TYPE_CURRENCY) | double | | +| 百分数(FIELD_TYPE_PERCENTAGE) | double | | + + + +### CellTextValue + +文本类型字段的单元值类型 + +| 参数名 | 类型 | 描述 | +| ------ | ------ | --------------------------------------------- | +| type | string | 内容为文本(值为`text`)、内容为链接(值为`url`) | +| text | string | 单元格内容 | +| link | string | 当type时`url`时，表示链接跳转url | + +### CellImageValue + +| 参数名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------------------------ | +| id | string | 图片 ID,自定义id | +| title | string | 图片标题 | +| image_url | string | 图片链接，通过[上传图片](https://developer.work.weixin.qq.com/document/path/99907#53863)接口获取 | +| width | int32 | 图片宽度 | +| height | int32 | 图片高度 | + +### CellAttachmentValue + +**示例** + +```json +{ + "doc_type": 2, + "file_ext": "SMARTSHEET", + "file_id": "FILEID", + "file_type": "70", + "file_url": "https://doc.weixin.qq.com/smartsheet/xxx", + "name": "智能表格", + "size": 3267 +} +``` + +| 参数名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------------------------ | +| name | string | 文件名 | +| size | int32 | 文件大小 | +| file_ext | string | 文件扩展名。文件夹为空，文件为对应文件拓展名，收集表为FORM，文档为DOC，表格为SHEET，幻灯片为SLIDE，思维导图为MIND，流程图为FLOWCHART，智能表为SMARTSHEET | +| file_id | string | 文件ID | +| file_url | string | 文件url ，如果是微盘文档则通过[获取分享链接](https://developer.work.weixin.qq.com/document/path/99907#44667)获得，如果是文档，则为文档url | +| file_type | string | 文件类型。文件夹为Folder，微盘文件为Wedrive，收集表为30，文档为50，表格是51，幻灯片为52，思维导图为54，流程图为55，智能表为70 | +| doc_type | string | 文件类型，用于区分文件夹和文件 | + +### CellUserValue + +| 参数名 | 类型 | 描述 | +| ------- | ------ | ------ | +| user_id | string | 成员ID | + +### CellUrlValue + +数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接 +**示例** + +```json +{ + "link": "https://developer.work.weixin.qq.com/document/path/97392", + "text": "企业微信开发者中心", + "type": "url" +} +``` + +| 参数名 | 类型 | 描述 | +| ------ | ------ | ------------ | +| type | string | 填`url` | +| text | string | 链接显示文本 | +| link | string | 链接跳转url | + + + +### Option + +**示例** + +```json +{ + "id": "1" +} +``` + +| 参数名 | 类型 | 描述 | +| ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| id | string | 选项ID，当选项存在时，通过ID识别选项，当需要新增选项，则不填写此字段 | +| style | int([Style](https://developer.work.weixin.qq.com/document/path/99907#53117/style)) | 选项颜色。新增选项时填写 | +| text | string | 要填写的选项内容。新增选项时填写，已经存在时优先匹配已经存在的选项，否则会新增选项 | + +### CellLocationValue + +**示例** + +```json +{ + "id": "14313005936863363130", + "latitude": "23.10647", + "longitude": "113.32446", + "source_type": 1, + "title": "广州塔" +} +``` + +| 参数名 | 类型 | 描述 | +| ----------- | ------ | --------------------------------------------------- | +| source_type | uint32 | 填`1`，表示来源为`腾讯地图`。目前只支持腾讯地图来源 | +| id | string | 地点ID | +| latitude | string | 纬度 | +| longitude | string | 经度 | +| title | string | 地点名称 | + +## 删除记录 + +本接口用于删除 Smartsheet 的某个子表中的一行或多行记录。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_records?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "record_ids": [ + "re9IqD", + "rpS0P9" + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ---------- | -------- | -------- | ----------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| record_ids | string[] | 是 | 要删除的记录 ID | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99908#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99908#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 更新记录 + +本接口用于更新 Smartsheet 中的某个子表里的一行或多行记录。 +**注意** +不能通过更新记录接口给创建时间、最后编辑时间、创建人和最后编辑人四种类型的字段更新记录。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_records?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", + "records": [ + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------------------------------------------------------------ | -------- | -------------------------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| key_type | string([CellValueKeyType](https://developer.work.weixin.qq.com/document/path/99909#cellvaluekeytype)) | 否 | 返回记录中单元格的key类型 | +| records | Object[]([UpdateRecord](https://developer.work.weixin.qq.com/document/path/99909#updaterecord)) | 是 | 由需要更新的记录组成的 JSON 数组 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99909#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99909#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "records": [ + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------------------------------------------------------------ | ------------------------------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| records | Object[]([CommonRecord](https://developer.work.weixin.qq.com/document/path/99909#commonrecord)) | 由更新成功的记录的具体内容组成的 JSON 数组 | + +### 参数详细说明 + +### CellValueKeyType + +记录([CommonRecord](https://developer.work.weixin.qq.com/document/path/99909#commonrecord))中key的类型 + +| 枚举类型 | 描述 | +| ------------------------------- | ----------------- | +| CELL_VALUE_KEY_TYPE_FIELD_TITLE | key用字段标题表示 | +| CELL_VALUE_KEY_TYPE_FIELD_ID | key用字段 ID 表示 | + +### UpdateRecord + +| 参数名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------------------------ | +| record_id | string | 记录 ID | +| values | Object | 记录的具体内容，key 为字段标题或字段 ID ，value 详见([Value](https://developer.work.weixin.qq.com/document/path/99909#53118/value)) | + +### CommonRecord + + + +| 参数名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------------------------ | +| record_id | string | 记录 ID | +| values | Object | 记录的具体内容，key 为字段标题或字段 ID ，value 详见([Value](https://developer.work.weixin.qq.com/document/path/99909#value)) | + +## 查询记录 + +本接口用于获取 Smartsheet 中某个子表下记录信息，该接口可以完成下面三种功能：获取全部记录信息、依据字段名和记录 ID 获取对应记录、对记录进行排序。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_records?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "view_id": "vCRl8n", + "record_ids": [], + "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", + "field_titles": [], + "field_ids": [], + "sort": [], + "offset": 0, + "limit": 100, + "ver": 160, + "filter_spec": { + "conjunction": "CONJUNCTION_AND", + "conditions": [{ + "field_id": "f53B4X", + "field_type": "FIELD_TYPE_TEXT", + "operator": "OPERATOR_CONTAINS", + "string_value": { + "value": [ + "123" + ] + } + }] + } +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | Smartsheet 子表ID | +| view_id | string | 否 | 视图 ID | +| record_ids | string[] | 否 | 由记录 ID 组成的 JSON 数组 | +| key_type | string([CellValueKeyType](https://developer.work.weixin.qq.com/document/path/101158#cellvaluekeytype)) | 否 | 返回记录中单元格的key类型 | +| field_titles | string[] | 否 | 返回指定列，由字段标题组成的 JSON 数组 ，key_type 为 `CELL_VALUE_KEY_TYPE_FIELD_TITLE` 时有效 | +| field_ids | string[] | 否 | 返回指定列，由字段 ID 组成的 JSON 数组 ，key_type 为 `CELL_VALUE_KEY_TYPE_FIELD_ID` 时有效 | +| sort | Object[]([Sort](https://developer.work.weixin.qq.com/document/path/101158#sort)) | 否 | 对返回记录进行排序 | +| offset | uint32 | 否 | 偏移量，初始值为 0 | +| limit | uint32 | 否 | 分页大小 , 每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 行记录，当总数小于 1000 时，返回全部记录；limit 最大值为 1000 | +| ver | uint32 | 否 | 版本号 | +| filter_spec | object([FilterSpec](https://developer.work.weixin.qq.com/document/path/101158#53112/filterspec)) | 否 | 过滤设置，不支持和sort一起使用 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101158#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101158#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "ver":160 +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| -------- | ------------------------------------------------------------ | ------------------------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| total | uint32 | 符合筛选条件的视图总数 | +| has_more | bool | 是否还有更多项 | +| next | uint32 | 下次下一个搜索结果的偏移量 | +| records | Object[]([Record](https://developer.work.weixin.qq.com/document/path/101158#record)) | 由查询记录的具体内容组成的 JSON 数组 | +| ver | uint32 | 版本号 | + +### 参数详细说明 + +### CellValueKeyType + +记录([Record](https://developer.work.weixin.qq.com/document/path/101158#record))中key的类型 + +| 枚举类型 | 描述 | +| ------------------------------- | ----------------- | +| CELL_VALUE_KEY_TYPE_FIELD_TITLE | key用字段标题表示 | +| CELL_VALUE_KEY_TYPE_FIELD_ID | key用字段 ID 表示 | + +### Sort + +**示例** +字段标题为`文本列`的降序排序，字段标题为`数字列`的升序序排序。需要一个Sort数组： + +```json +[ + { + "field_title": "文本列", + "desc": true + }, + { + "field_title": "数字列", + "desc": false + } +] +``` + +在 Smartsheet 的某个表格中对记录进行排序的参数： + +| 参数名 | 类型 | 是否必须 | 描述 | +| ----------- | ------ | -------- | -------------------------------- | +| field_title | string | 是 | 需要排序的字段标题 | +| desc | bool | 否 | 是否进行降序排序，默认值为 false | + +### Record + +Smartsheet 的某个表格中记录相关的参数： +**示例1** +按`字段标题`返回各行的单元格内容 + +```json +{ + "record_id": "r5ud8u", + "create_time": "1715846245084", + "update_time": "1715846248810", + "values": { + "文本字段1-标题": [ + { + "type": "text", + "text": "XXXX" + } + ], + "数字字段1-标题": 123 + }, + "creator_name":"NAME", + "updater_name":"NAME" +} +``` + +**示例2** +按`字段ID`返回各行的单元格内容 + +```json +{ + "record_id": "r5ud8u", + "create_time": "1715846245084", + "update_time": "1715846248810", + "values": { + "TextField1Id": [ + { + "type": "text", + "text": "XXXX" + } + ], + "NumField1Id": 123 + }, + "creator_name":"NAME", + "updater_name":"NAME" +} +``` + +| 参数名 | 类型 | 描述 | +| ------------ | ------ | ------------------------------------------------------------ | +| record_id | string | 记录 ID | +| create_time | string | 记录的创建时间 | +| update_time | string | 记录的更新时间 | +| values | Object | 记录的具体内容，key 为字段标题或字段 ID ，value 详见([Value](https://developer.work.weixin.qq.com/document/path/101158#value)) | +| creator_name | string | 创建者名字 | +| updater_name | string | 最后编辑者名字 | + + + +### Value + +各种类型的字段对应的单元格的值 + +| 字段类型 | 单元格值类型 | 描述 | +| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 文本(FIELD_TYPE_TEXT) | Object[]([CellTextValue](https://developer.work.weixin.qq.com/document/path/101158#celltextvalue)) | | +| 数字(FIELD_TYPE_NUMBER) | double | | +| 复选框(FIELD_TYPE_CHECKBOX) | bool | | +| 日期(FIELD_TYPE_DATE_TIME) | string(以毫秒为单位的unix时间戳) | | +| 图片(FIELD_TYPE_IMAGE) | Object[]([CellImageValue](https://developer.work.weixin.qq.com/document/path/101158#cellimagevalue)) | | +| 文件(FIELD_TYPE_ATTACHMENT) | Object[]([CellAttachmentValue](https://developer.work.weixin.qq.com/document/path/101158#cellattchmentvalue)) | | +| 成员(FIELD_TYPE_USER) | Object[]([CellUserValue](https://developer.work.weixin.qq.com/document/path/101158#celluservalue)) | | +| 链接(FIELD_TYPE_URL) | Object[]([CellUrlValue](https://developer.work.weixin.qq.com/document/path/101158#cellurlvalue)) | 数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接 | +| 多选(FIELD_TYPE_SELECT) | Object[]([Option](https://developer.work.weixin.qq.com/document/path/101158#option)) | | +| 进度(FIELD_TYPE_PROGRESS) | double | | +| 电话(FIELD_TYPE_PHONE_NUMBER) | string | | +| 邮箱(FIELD_TYPE_EMAIL) | string | | +| 单选(FIELD_TYPE_SINGLE_SELECT) | Object[]([Option](https://developer.work.weixin.qq.com/document/path/101158#option)) | | +| 地理位置(FIELD_TYPE_LOCATION) | Object[]([CellLocationValue](https://developer.work.weixin.qq.com/document/path/101158#celllocationvalue)) | 长度不大于1的数组。 | +| 关联(FIELD_TYPE_REFERENCE) | string [] | 关联的记录id | +| 货币(FIELD_TYPE_CURRENCY) | double | | +| 自动编号(FIELD_TYPE_AUTONUMBER) | Object[]([CellAutoNumberValue](https://developer.work.weixin.qq.com/document/path/101158#cellautonumbervalue) | | +| 百分数(FIELD_TYPE_PERCENTAGE) | double | | + + + +### CellTextValue + +文本类型字段的单元值类型 + +| 参数名 | 类型 | 描述 | +| ------ | ------ | --------------------------------------------- | +| type | string | 内容为文本(值为`text`)、内容为链接(值为`url`) | +| text | string | 单元格内容 | +| link | string | 当type时`url`时，表示链接跳转url | + +### CellImageValue + +| 参数名 | 类型 | 描述 | +| --------- | ------ | -------- | +| id | string | 图片 ID | +| title | string | 图片标题 | +| image_url | string | 图片url | +| width | int32 | 图片宽度 | +| height | int32 | 图片高度 | + +### CellAttachmentValue + +**示例** + +```json +{ + "doc_type": 2, + "file_ext": "SMARTSHEET", + "file_type": "70", + "file_url": "https://doc.weixin.qq.com/smartsheet/xxx", + "name": "智能表格", + "size": 3267 +} +``` + +| 参数名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------------------------ | +| name | string | 文件名 | +| size | int32 | 文件大小 | +| file_ext | string | 文件扩展名 | +| file_url | string | 文件url | +| file_type | string | 文件类型，文件夹为Folder，微盘文件为Wedrive，文件夹为Folder，微盘文件为Wedrive，收集表为30，文档为50，表格是51，幻灯片为52，思维导图为54，流程图为55，智能表为70 | +| doc_type | string | 接口返回的文件类型，1为文件夹，2为文件 | + +### CellUserValue + +| 参数名 | 类型 | 描述 | +| ------------------- | ------ | ------------------------------------------------------------ | +| user_id | string | 成员ID | +| tmp_external_userid | string | 外部用户临时id，同一个用户在不同的智能表中返回的该id不一致。可进一步通过[tmp_external_userid的转换](https://developer.work.weixin.qq.com/document/path/101158#46252)接口转换成external_userid，方便识别外部用户的身份。 | + +### CellUrlValue + +数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接 +**示例** + +```json +{ + "link": "https://developer.work.weixin.qq.com/document/path/97392", + "text": "企业微信开发者中心", + "type": "url" +} +``` + +| 参数名 | 类型 | 描述 | +| ------ | ------ | ------------ | +| type | string | 填`url` | +| text | string | 链接显示文本 | +| link | string | 链接跳转url | + + + +### Option + +**示例** + +```json +{ + "id": "1", + "style": 1, + "text": "one" +} +``` + +| 参数名 | 类型 | 描述 | +| ------ | ------ | ------------------------------------------------------------ | +| id | string | 选项ID | +| style | uint32 | 选项颜色[(Style)](https://developer.work.weixin.qq.com/document/path/101158#53117/style) | +| text | string | 选项内容 | + +### CellLocationValue + +**示例** + +```json +{ + "id": "14313005936863363130", + "latitude": "23.10647", + "longitude": "113.32446", + "source_type": 1, + "title": "广州塔" +} +``` + +| 参数名 | 类型 | 描述 | +| ----------- | ------ | --------------------------------------------------- | +| source_type | uint32 | 填`1`，表示来源为`腾讯地图`。目前只支持腾讯地图来源 | +| id | string | 地点ID | +| latitude | string | 纬度 | +| longitude | string | 经度 | +| title | string | 地点名称 | + +### CellAutoNumberValue + +**示例** + +```json +{ + "seq": "3", + "text": "3" +} +``` + +| 参数名 | 类型 | 描述 | +| ------ | ------ | ---------- | +| seq | string | 序号 | +| text | string | 展示的文本 | + +## 添加编组 + +本接口用于在智能表中的某个子表里添加编组。单表最多允许有150个编组。每个编组最多允许有150个字段。字段只能同时存在于一个编组。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_field_group?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "name":"编组名称", + "children": [ + { + "field_id": "field_id" + }, + { + "field_id": "field_id" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----------------- | -------- | -------- | ---------------------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| name | string | 是 | 编组名称，不能和已有名称重复 | +| children | object[] | 否 | 编组内容 | +| children.field_id | string | 否 | 字段id | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101100#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101100#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "field_group": { + "field_group_id": "FIELD_GROUP_ID", + "name": "编组名称", + "children": [{ + "field_id": "FIELD_ID" + }, + { + "field_id": "FIELD_ID" + } + ] + } +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ----------------------------- | -------- | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| field_group | object | 编组 | +| field_group.field_group_id | string | 编组id | +| field_group.name | string | 编组名称 | +| field_group.children | object[] | 编组内容 | +| field_group.children.field_id | string | 字段id | + +## 删除编组 + +本接口用于删除智能表的某个子表中的一个或多个编组。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_field_groups?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "123Abc", + "field_group_ids": [ + "fgCLYCF", + "fgCLYCM" + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| --------------- | -------- | -------- | --------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 子表ID | +| field_group_ids | string[] | 是 | 要删除的编组 ID | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101102#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101102#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 更新编组 + +本接口用于在智能表中的某个子表里更新已有编组。每个编组最多允许有150个字段。字段只能同时存在于一个编组。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_field_group?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "field_group_id":"FIELD_GROUP_ID", + "name":"编组名称", + "children": [ + { + "field_id": "FIELD_ID" + }, + { + "field_id": "FIELD_ID" + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----------------- | -------- | -------- | ---------------------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| field_group_id | string | 是 | 编组id | +| name | string | 否 | 编组名称，不能和已有名称重复 | +| children | object[] | 否 | 编组内容 | +| children.field_id | string | 否 | 字段id | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101101#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101101#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "field_group": { + "field_group_id": "FIELD_GROUP_ID", + "name": "编组名称", + "children": [{ + "field_id": "FIELD_ID" + }, + { + "field_id": "FIELD_ID" + } + ] + } +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ----------------- | -------- | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| field_group_id | string | 编组id | +| name | string | 编组名称 | +| children | object[] | 编组内容 | +| children.field_id | string | 字段id | + +## 获取编组 + +本接口用于在智能表中的某个子表里获取已有的编组。 + +**请求方式**：POST(HTTPS) +**请求地址**：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_field_groups?access_token=ACCESS_TOKEN + +**请求包体**： + +```json +{ + "docid": "DOCID", + "sheet_id": "SHEETID", + "offset":0, + "limit":10 +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------- | ------ | -------- | ----------------------------- | +| docid | string | 是 | 文档的docid | +| sheet_id | string | 是 | 表格ID | +| offset | uint32 | 否 | 偏移量，初始值为 0 | +| limit | uint32 | 否 | 分页大小 , 每页返回多少条数据 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/101103#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/101103#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "total": 1, + "has_more": false, + "next": 0, + "field_groups": [{ + "field_group_id": "FIELD_GROUP_ID", + "name": "编组名称", + "children": [{ + "field_id": "FIELD_ID" + }] + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------------------------------ | -------- | ---------------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| total | uint32 | 编组数量 | +| has_more | bool | 是否还有更多数据 | +| next | uint32 | 下一偏移位置 | +| field_groups | obj[] | 编组列表 | +| field_groups.field_group_id | string | 编组id | +| field_groups.name | string | 编组名称 | +| field_groups.children | object[] | 编组内容 | +| field_groups.children.field_id | string | 字段id | + +# 设置文档权限 + +## 获取文档权限信息 + +最后更新：2024/05/30 + +该接口用于获取文档、表格、智能表格的查看规则、文档通知范围及权限、安全设置信息 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/doc_get_auth?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid":"DOCID" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----- | ------ | -------- | ------ | +| docid | string | 是 | 文档id | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97461#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97461#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 +- 只能访问该应用创建的文档 + +**返回示例** + +```json +{ + "errcode":0, + "errmsg":"ok", + "access_rule":{ + "enable_corp_internal":true, + "corp_internal_auth":1, + "enable_corp_external":true, + "corp_external_auth":1, + "corp_internal_approve_only_by_admin":true, + "corp_external_approve_only_by_admin":true, + "ban_share_external":false + }, + "secure_setting":{ + "enable_readonly_copy":false, + "watermark":{ + "margin_type":2, + "show_visitor_name":false, + "show_text":false, + "text":"" + }, + "enable_readonly_comment":false + }, + "doc_member_list":[ + { + "type":1, + "userid":"USERID1", + "auth":7 + }, + { + "type":1, + "tmp_external_userid":"TMP_EXTERNAL_USERID2", + "auth":1 + } + ], + "co_auth_list":[ + { + "type":2, + "departmentid":1, + "auth":1 + } + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ----------------------------------- | ------ | ------------------------------------------------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| access_rule | object | 文档的查看规则 | +| enable_corp_internal | bool | 是否允许企业内成员浏览文档 | +| corp_internal_auth | uint32 | 企业内成员主动查看文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写） | +| enable_corp_external | bool | 是否允许企业外成员浏览文档 | +| corp_external_auth | uint32 | 企业内成员主动查看文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写） | +| corp_internal_approve_only_by_admin | bool | 企业内成员浏览文档是否必须由管理员审批，enable_corp_internal为false时，只能为true | +| corp_external_approve_only_by_admin | bool | 企业外成员浏览文档是否必须由管理员审批，enable_corp_external和ban_share_external均为false时，该参数只能为true | +| ban_share_external | bool | 是否允许企业外成员浏览文档 | +| enable_readonly_copy | bool | 仅浏览权限的成员是否允许导出、复制、打印 | +| watermark | object | 文档水印设置 | +| margin_type | uint32 | 水印密度 1:稀疏 2:紧密 | +| show_visitor_name | bool | 是否展示访问者名字 | +| show_text | bool | 是否展示水印文字 | +| text | bytes | 水印文字 | +| doc_member_list | obj[] | 文档通知范围及权限列表 | +| type | uint32 | 文档通知范围成员种类 1:user, 只支持成员 | +| userid | bytes | 企业成员的userid | +| tmp_external_userid | string | 外部用户临时id。同一个用户在不同的文档中返回的该id不一致。 | +| auth | uint32 | 该文档通知范围成员的权限 1:只读 2:读写（目前仅智能表可设置为读写） 7:管理员 | +| co_auth_list | object | 文档查看权限特定部门列表，可以直接浏览文档 | +| type | uint32 | 特定部门列表 2:部门, 目前只支持部门 | +| departmentid | uint64 | 特定部门id | +| auth | uint32 | 权限类型 1:只读,2:读写（目前仅智能表可设置为读写） | + +## 修改文档查看规则 + +最后更新：2024/08/21 + +该接口用于修改文档、表格、智能表格查看规则。 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/mod_doc_join_rule?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid":"DOCID", + "enable_corp_internal":true, + "corp_internal_auth":1, + "enable_corp_external":true, + "corp_external_auth":1, + "corp_internal_approve_only_by_admin":true, + "corp_external_approve_only_by_admin":true, + "ban_share_external":false, + "update_co_auth_list":true, + "co_auth_list":[ + { + "departmentid":1, + "auth":1, + "type":2 + } + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----------------------------------- | -------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 操作的docid | +| enable_corp_internal | bool | 否 | 是否允许企业内成员浏览文档, 有值则覆盖 | +| corp_internal_auth | uint32 | 否 | 企业内成员主动查看文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写）, 有值则覆盖 | +| enable_corp_external | uint32 | 否 | 是否允许企业外成员浏览文档, 有值则覆盖 | +| corp_external_auth | uint32 | 否 | 企业外成员主浏览文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写）, 有值则覆盖 | +| corp_internal_approve_only_by_admin | bool | 否 | 企业内成员加入文档是否必须由管理员审批，enable_corp_internal为false时，只能为true，有值则覆盖。设置为true之前，文档需要有至少一个管理员。 | +| corp_external_approve_only_by_admin | bool | 否 | 企业外成员加入文档是否必须由管理员审批，enable_corp_external和ban_share_external均为false时，该参数只能为true，有值则覆盖。设置为true之前，文档需要有至少一个管理员。 | +| ban_share_external | bool | 否 | 是否禁止文档分享到企业外, 有值则覆盖 | +| update_co_auth_list | bool | 否 | 是否更新文档查看权限的特定部门, true时更新特定部门列表 | +| co_auth_list | object[] | 否 | 需要更新文档查看权限特定部门时, 覆盖之前部门, 特别的: 列表为空则清空 | +| departmentid | uint64 | 否 | 文档查看权限特定部门id | +| auth | uint32 | 否 | 文档特定部门权限 1:只读 2:读写（目前仅智能表可设置为读写） | +| type | uint32 | 否 | 文档特定部门类型 2:部门, 目前只支持部门 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97778#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97778#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 +- 只能操作该应用创建的文档 + + + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 修改文档通知范围及权限 + +最后更新：2024/05/30 + +该接口用于修改文档、表格、智能表格通知范围列表，可以新增文档、表格、智能表格通知范围并设置权限、修改已有范围的权限以及删除文档、表格、智能表格通知范围内的人员 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/mod_doc_member?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid":"DOCID", + "update_file_member_list":[ + { + "type":1, + "auth":7, + "userid":"USERID1" + } + ], + "del_file_member_list":[ + { + "type":1, + "userid":"USERID2" + }, + { + "type":1, + "tmp_external_userid":"TMP_EXTERNAL_USERID2" + } + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----------------------- | ------ | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 操作的文档id | +| update_file_member_list | obj[] | 否 | 更新文档通知范围的列表, 批次大小最大100 | +| type | uint32 | 是 | 文档通知范围的类型 1:用户。文档通知范围仅支持按人配置 | +| auth | uint32 | 是 | 文档通知范围内人员获得的权限 1:只读权限 2:读写权限（目前仅智能表可设置为读写权限） 7:管理员权限，文档管理员最多三个 | +| userid | string | 否 | 企业内成员的ID | +| tmp_external_userid | string | 否 | 外部用户临时id。同一个用户在不同的文档中返回的该id不一致。 | +| del_file_member_list | obj[] | 否 | 删除的文档通知范围列表，批次大小最大一百 | +| type | uint32 | 是 | 文档通知范围的类型 1:用户。文档通知范围仅支持按人配置 | +| userid | string | 否 | 企业内成员的ID | +| tmp_external_userid | string | 否 | 外部用户临时id。同一个用户在不同的文档中返回的该id不一致。 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97781#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97781#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 +- 只能操作该应用创建的文档 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 修改文档安全设置 + +最后更新：2024/05/30 + +该接口用于修改文档、表格、智能表格的安全设置 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/mod_doc_safty_setting?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid":"DOCID", + "enable_readonly_copy":false, + "watermark":{ + "margin_type":1, + "show_visitor_name":true, + "show_text":true, + "text":"test mark" + } +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| -------------------- | ------ | -------- | ------------------------------------------ | +| docid | string | 是 | 操作的文档id | +| enable_readonly_copy | bool | 否 | 是否允许只读成员复制、下载文档，有值则覆盖 | +| watermark | object | 否 | 水印设置 | +| margin_type | uint32 | 否 | 水印疏密度，1:稀疏，2:紧密 | +| show_visitor_name | bool | 否 | 是否展示访问者名字水印，有值则覆盖 | +| show_text | bool | 否 | 是否展示文本水印，有值则覆盖 | +| text | string | 否 | 文字水印的文字，有值则覆盖 | + + + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/97782#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/97782#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 +- 只能操作该应用创建的文档 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 管理智能表格内容权限 + +最后更新：2024/11/21 + +### 智能表内容权限概述 + +智能表格可设置**内容权限**以详细配置文档成员对表格内容的操作权限。 +内容权限由全员权限以及至多20条成员额外权限组成。 + +### 权限明细 + +每条权限可以针对不同子表配置字段权限、记录权限、视图权限。 + +### 生效成员 + +对于全员权限，生效成员即是全部文档成员。 +对于成员额外权限，可以配置生效的成员范围。 + +## 查询智能表格子表权限 + +该接口用于查询智能表格子表权限详情 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/get_sheet_priv?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "type": 2, + "rule_id_list": [ + "RULEID1", "RULEID2" + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------ | --------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 智能表ID，通过[新建文档接口](https://developer.work.weixin.qq.com/document/path/99935#43939)创建后获得 | +| type | uint32 | 是 | 权限规则类型，1-全员权限，2-额外权限 | +| rule_id_list | uint32 [] | 否 | 需要查询的规则id列表，查询额外权限时填写 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99935#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99935#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "rule_list": [{ + "rule_id": 1, + "type": 1, + "name": "全员权限", + "priv_list": [{ + "sheet_id": "q979lj", + "priv": 2, + "can_insert_record": true, + "can_delete_record": true, + "record_priv": { + "record_range_type": 1 + }, + "field_priv": { + "field_range_type": 2, + "field_rule_list": [{ + "field_id": "fsMGQS", + "field_type": "FIELD_TYPE_TEXT", + "can_edit": false, + "can_insert": true, + "can_view": true + }], + "field_default_rule": { + "can_edit": false, + "can_insert": false, + "can_view": true + } + }, + "can_create_modify_delete_view": true + }, + { + "sheet_id": "kQ65QQ", + "priv": 1 + } + ] + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ----------------------------------------------------------- | -------- | ------------------------------------------------------------ | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| rule_list | object[] | 权限列表 | +| rule_list.type | uint32 | 权限规则类型，1-全员权限，2-额外权限。每个智能表格有且只有一个全员权限 | +| rule_list.rule_id | uint32 | 当type为2时必填 | +| rule_list.name | string | 权限名称，仅当type为2时有效 | +| rule_list.priv_list | object[] | 针对不同子表设置内容权限 | +| rule_list.priv_list.sheet_id | string | 子表ID | +| rule_list.priv_list.priv | string | 子表权限: 1-全部权限；2-可编辑；3-仅浏览；4-无权限 | +| rule_list.priv_list.can_insert_record | bool | 是否可以新增记录。仅当子表权限为`可编辑`时有意义 | +| rule_list.priv_list.can_delete_record | bool | 是否可以删除记录。仅当子表权限为`可编辑`时有意义 | +| rule_list.priv_list.can_create_modify_delete_view | bool | 是否可以增、删、改视图。 | +| rule_list.priv_list.field_priv | object | 按字段配置权限 | +| rule_list.priv_list.field_priv.field_range_type | uint32 | 子表权限对所有字段生效还是部分字段生效：1-所有字段；2-部分字段。当值为2时可以配置各个字段独立的权限 | +| rule_list.priv_list.field_priv.field_rule_list | object[] | 按字段分别配置权限 | +| rule_list.priv_list.field_priv.field_rule_list.field_id | string | 字段id | +| priv_list.priv_list.field_priv.field_rule_list.field_type | string | 字段类型，见[FieldType](https://developer.work.weixin.qq.com/document/path/99935#53114/fieldtype) | +| rule_list.priv_list.field_priv.field_rule_list.can_edit | bool | 可编辑 | +| rule_list.priv_list.field_priv.field_rule_list.can_insert | bool | 可首次提交 | +| rule_list.priv_list.field_priv.field_rule_list.can_view | bool | 可查看 | +| rule_list.priv_list.field_priv.field_default_rule | object | field_rule_list里未指定字段和后续新增字段的默认配置，与field_rule_list一样可指定can_edit/can_insert/can_view三个权限 | +| rule_list.priv_list.record_priv | object | 按记录配置权限，priv=2或3时必填 | +| rule_list.priv_list.record_priv.record_range_type | uint32 | 子表权限对记录生效范围：1-全部记录；2-满足任意条件的记录；3-满足全部条件的记录 | +| rule_list.priv_list.record_priv.record_rule_list | object[] | 记录的条件列表，当record_range_type为2或3时生效 | +| rule_list.priv_list.record_priv.record_rule_list.field_id | string | 字段id，只有人员、单选、多选三种类型的字段有效。当field_id为`CREATED_USER`时表示记录创建者 | +| rule_list.priv_list.record_priv.record_rule_list.field_type | string | 是字段类型，见[FieldType](https://developer.work.weixin.qq.com/document/path/99935#53114/fieldtype) | +| rule_list.priv_list.record_priv.record_rule_list.oper_type | uint32 | 逻辑判断类型：1-包含自己（人员字段）；2-包含value；3-不包含value；4-等于value；5-不等于value；6-为空；7-非空； | +| rule_list.priv_list.record_priv.record_rule_list.value | string[] | 用于单选、多选字段的option_id | +| rule_list.priv_list.record_priv.other_priv | uint32 | 当记录不满足条件的时的权限类型：1-不可编辑 2-不可查看 | +| rule_list.priv_list.clear | bool | 清除子表的设置，恢复默认权限 | + +## 更新智能表格子表权限 + +该接口用于设置全员权限或者成员额外权限的权限详情 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/update_sheet_priv?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "type": 2, + "rule_id": 2, + "name": "NAME", + "priv_list": [{ + "sheet_id": "SHEETID", + "priv": 1, + "can_insert_record": true, + "can_delete_record": true, + "can_create_modify_delete_view": true, + "field_priv": { + "field_range_type": 2, + "field_rule_list": [{ + "field_id": "FIELDID1", + "can_edit": true, + "can_insert": true, + "can_view": true + }, + { + "field_id": "FIELDID2", + "can_edit": false, + "can_insert": true, + "can_view": true + } + ] + }, + "record_priv": { + "record_range_type": 2, + "record_rule_list": [{ + "field_id": "FIELDI1", + "field_type": "FIELD_TYPE_TEXT", + "oper_type": 1 + }, + { + "field_id": "CREATED_USER", + "oper_type": 1 + }, + { + "field_id": "FIELDID2", + "oper_type": 2, + "field_type": "FIELD_TYPE_SELECT", + "value": [ + "OPTION1", "OPTION2", "OPTION3" + ] + } + ] + }, + "clear": false + }] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------------------------------------------- | -------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 智能表ID，通过[新建文档接口](https://developer.work.weixin.qq.com/document/path/99935#43939)创建后获得 | +| type | uint32 | 是 | 权限规则类型，1-全员权限，2-额外权限。每个智能表格有且只有一个全员权限 | +| rule_id | uint32 | 否 | 当type为2时必填 | +| name | string | 否 | 更新权限名称，仅当type为2时有效 | +| priv_list | object[] | 否 | 针对不同子表设置内容权限 | +| priv_list.sheet_id | string | 是 | 子表ID | +| priv_list.priv | string | 是 | 子表权限: 1-全部权限；2-可编辑；3-仅浏览；4-无权限 | +| priv_list.can_insert_record | bool | 否 | 是否可以新增记录。仅当子表权限为`可编辑`时有意义 | +| priv_list.can_delete_record | bool | 否 | 是否可以删除记录。仅当子表权限为`可编辑`时有意义 | +| priv_list.can_create_modify_delete_view | bool | 否 | 是否可以增、删、改视图。 | +| priv_list.field_priv | object | 否 | 按字段配置权限 | +| priv_list.field_priv.field_range_type | uint32 | 是 | 子表权限对所有字段生效还是部分字段生效：1-所有字段；2-部分字段。当值为2时可以配置各个字段独立的权限 | +| priv_list.field_priv.field_rule_list | object[] | 是 | 按字段分别配置权限 | +| priv_list.field_priv.field_rule_list.field_id | string | 是 | 字段id | +| priv_list.field_priv.field_rule_list.field_type | string | 是 | 字段类型，见[FieldType](https://developer.work.weixin.qq.com/document/path/99935#53114/fieldtype) | +| priv_list.field_priv.field_rule_list.can_edit | bool | 是 | 可编辑 | +| priv_list.field_priv.field_rule_list.can_insert | bool | 是 | 可首次提交 | +| priv_list.field_priv.field_rule_list.can_view | bool | 是 | 可查看 | +| priv_list.field_priv.field_default_rule | object | 否 | field_rule_list里未指定字段和后续新增字段的默认配置，与field_rule_list一样可指定can_edit/can_insert/can_view三个权限。type为1时必填，type为2时不可指定field_default_rule | +| priv_list.record_priv | object | 否 | 按记录配置权限，priv=2或3时必填 | +| priv_list.record_priv.record_range_type | uint32 | 是 | 子表权限对记录生效范围：1-全部记录；2-满足任意条件的记录；3-满足全部条件的记录 | +| priv_list.record_priv.record_rule_list | object[] | 否 | 记录的条件列表，当record_range_type为2或3时生效 | +| priv_list.record_priv.record_rule_list.field_id | string | 是 | 字段id，只有人员、单选、多选三种类型的字段有效。当field_id为`CREATED_USER`时表示记录创建者 | +| priv_list.record_priv.record_rule_list.field_type | string | 否 | 字段类型[FieldType](https://developer.work.weixin.qq.com/document/path/99935#53114/fieldtype)，当field_id为`CREATED_USER`时不填此字段，其他类型必填 | +| priv_list.record_priv.record_rule_list.oper_type | uint32 | 是 | 逻辑判断类型：1-包含自己（人员字段）；2-包含value；3-不包含value；4-等于value；5-不等于value；6-为空；7-非空； | +| priv_list.record_priv.record_rule_list.value | string[] | 是 | 用于单选、多选字段的option_id | +| priv_list.record_priv.other_priv | uint32 | 是 | 当记录不满足条件的时的权限类型：1-不可编辑 2-不可查看 | +| priv_list.clear | bool | 否 | 清除子表的设置，恢复默认权限 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99935#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99935#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + + + +## 新增智能表格指定成员额外权限 + +该接口用于新增智能表格指定成员额外权限 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/create_rule?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "name": "NAME" +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ----- | ------ | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 智能表ID，通过[新建文档接口](https://developer.work.weixin.qq.com/document/path/99935#43939)创建后获得 | +| name | string | 是 | 权限规则名称，不可重复 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99935#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99935#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok", + "rule_id": 1 +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | -------------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | +| rule_id | uint32 | 成员权限规则id | + +## 更新智能表格指定成员额外权限 + +该接口用于更新智能表格指定成员额外权限，成员最多可设置50个 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/mod_rule_member?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "rule_id": 3, + "add_member_range": { + "userid_list": [ + "userid1" + ] + }, + "del_member_range": { + "userid_list": [ + "userid2" + ] + } +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ---------------------------- | --------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 智能表ID，通过[新建文档接口](https://developer.work.weixin.qq.com/document/path/99935#43939)创建后获得 | +| rule_id | uint32 | 是 | 需要更新的id | +| add_member_range | object | 否 | 新增成员 | +| add_member_range.userid_list | string [] | 否 | 新增成员的userid | +| del_member_range | object | 否 | 删除成员 | +| del_member_range.userid_list | string [] | 否 | 删除成员的userid | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99935#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99935#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | + +## 删除智能表格指定成员额外权限 + +该接口用于删除智能表格指定成员额外权限 + +**请求方式**：POST（**HTTPS**） +**请求地址**: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/delete_rule?access_token=ACCESS_TOKEN + +**请求包体** + +```json +{ + "docid": "DOCID", + "rule_id_list": [ + 2 + ] +} +``` + +**参数说明** + +| 参数 | 类型 | 是否必须 | 说明 | +| ------------ | --------- | -------- | ------------------------------------------------------------ | +| docid | string | 是 | 智能表ID，通过[新建文档接口](https://developer.work.weixin.qq.com/document/path/99935#43939)创建后获得 | +| rule_id_list | uint32 [] | 是 | 需要删除的规则id列表 | + +**权限说明** + +- 自建应用需配置到“[可调用应用](https://developer.work.weixin.qq.com/document/path/99935#43883)”列表中的应用secret所获取的accesstoken来调用（[accesstoken如何获取？](https://developer.work.weixin.qq.com/document/path/99935#10013/第三步：获取access_token)） +- 第三方应用需具有“文档”权限 +- 代开发自建应用需具有“文档”权限 + +**返回示例** + +```json +{ + "errcode": 0, + "errmsg": "ok" +} +``` + +**参数说明** + +| 参数 | 类型 | 说明 | +| ------- | ------ | ---------- | +| errcode | int32 | 错误码 | +| errmsg | string | 错误码说明 | \ No newline at end of file diff --git a/需求文档.md b/需求文档.md new file mode 100644 index 0000000..d049f3c --- /dev/null +++ b/需求文档.md @@ -0,0 +1,55 @@ +# **Debug阶段自动开单工具需求** + +## **一、功能概述** + +策划在腾讯智能表格填写bug信息，工具定时扫描并自动在TAPD创建bug单，实现表格到TAPD的单向同步。 + + + +## **二、表格字段设计** + +| **列** | **说明** | **备注** | +| -------- | -------- | ---------------- | +| 标题 | 必填 | 同步为TAPD标题 | +| 详细描述 | 必填 | | +| 优先级 | 必填 | 单选 | +| 严重程度 | 必填 | 单选 | +| 处理人 | 必填 | | +| 验证人 | 必填 | | +| 发现版本 | 必填 | | +| 模块 | 必填 | | +| 开单状态 | 工具回写 | ✅成功 / ❌失败 | +| TAPD单号 | 工具回写 | 可点击跳转 | +| bug状态 | 工具回写 | 同步TAPD当前状态 | + +## + +## **三、处理逻辑** + +​ 1. 定时扫描"开单状态"为空的行 + +​ 2. 校验必填项是否完整 + +​ 3. 调用TAPD API创建bug单 + +​ 4. 回写结果到表格 + +## + +## **四、异常处理** + +​ ● 开单成功：开单状态列打✅，回写单号和状态 + +​ ● 开单失败：开单状态列打❌，企业微信推送报错信息给相关人员 + +## + +## **五、运行机制** + +​ ● 轮询频率：建议5分钟一次（可配置） + +​ ● bug状态同步频率：建议15分钟一次（可配置） + +# + + \ No newline at end of file