linzelong/G41_TAPD_BUG_SYNC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
G41_TAPD_BUG_SYNC/智能表格接口文档.md
zelong 6e51a505bd 'phase3'
2025-12-17 15:50:12 +08:00

4279 lines
190 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 概述
最后更新：2025/07/16
企业和开发者通过文档接口可以便捷地新建文档和表格，将项目进展、业务数据等通知给成员，提高信息流转效率；也可通过文档接口新建智能表格（目前仅支持企业新建），邀请成员协作编辑，与业务系统结合更紧密；还可通过接口新建收集表，收集员工信息。
调用接口的应用自动成为文档创建者，所建的文档、表格和收集表，仅应用可编辑内容；所建的智能表格，应用和成员均可编辑内容，内容也可被应用获取。创建后，应用可通过接口管理文档，也可指定成员作为文档管理员辅助管理。
提示
应用仅可读取和编辑自己创建的文档，无法编辑成员创建的文档；应用通过接口创建文档后，即可获得docid。docid仅在创建时返回，需要开发者妥善保存。
## 接口创建文档表现
- 接口创建的文档和收集表将在文档应用中标识出应用创建的信息，文档图标也将替换为应用图标。
- 接口创建的文档和收集表可添加企业成员进入通知范围，仅应用可编辑文档内容，成员无法编辑，但指定的管理员可以修改通知范围和获取收集表数据。
- 通过接口创建、修改、删除文档或收集表后，文档应用将自动向文档或收集表相关成员推送通知。
## 接口创建智能表格的表现
- 接口创建的智能表格将在智能表格中标识出应用创建的信息。
- 应用自动加入智能表格，成员可查询应用信息。
- 成员首次编辑智能表格时，展示 应用可获取编辑内容 提示。
## 配置可调用文档接口的应用
应用在调用文档接口前，需要先获得文档的使用权限。
**自建应用**
登录企业微信管理端，进入「协作」-「文档」-「API」，配置「可调用接口的应用」。
**第三方应用**
第三方服务商创建应用的时候，需要开启“文档接口权限”，企业授权安装第三方应用之后，第三方应用即拥有了调用文档接口的权限
**代开发应用**
第三方服务商为企业配置代开发应用时，需要开启「文档接口权限」，企业管理员确认之后，应用即拥有文档权限。
# 频率控制
对于 OpenAPI 的频率控制，我们使用维度加频率的描述方式如下：
| 维度 | 限制频率（次 / 分钟） |
| :----- | :-------------------- |
| fileID | 150 |
| openID | 300 |
这代表着当前 API 对于每个一篇文档的限制是每分钟 150 次，对于每个 openID（每个用户）的调用限制是每分钟 300 次。
## [#](https://docs.qq.com/open/document/app/openapi/v2/frequency_control.html#对文件操作的频率控制约定)对文件操作的频率控制约定
对于文件操作（如新建文件、智能表格新建子表），如无特殊说明频率限制如下：
| 维度 | 限制频率（次 / 分钟） |
| :----- | :-------------------- |
| openID | 300 |
频控标签为：
[openID](https://docs.qq.com/open/document/app/openapi/v2/frequency_control/)
[300](https://docs.qq.com/open/document/app/openapi/v2/frequency_control/)
对于导入接口：
[openID](https://docs.qq.com/open/document/app/openapi/v2/frequency_control/)
[60](https://docs.qq.com/open/document/app/openapi/v2/frequency_control/)
对于导出接口：
| 维度 | 限制频率（次 / 天） |
| :----- | :------------------ |
| openID | 9 |
## [#](https://docs.qq.com/open/document/app/openapi/v2/frequency_control.html#对于文档操作的频率控制约定)对于文档操作的频率控制约定
对于单篇文档的内容操作（如表格中添加一行数据），如无特殊说明频率限制如下：
| 维度 | 限制频率（次 / 分钟） |
| :----- | :-------------------- |
| fileID | 150 |
频控标签为：
[fileID](https://docs.qq.com/open/document/app/openapi/v2/frequency_control/)
[150](https://docs.qq.com/open/document/app/openapi/v2/frequency_control/)
# 获取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 | 错误码说明 |
Reference in New Issue View Git Blame Copy Permalink