cloudcc-openapi-withobject

CloudCC OpenAPI 调用技能 - 提供完整的 REST API 接口调用能力，支持对象/字段元数据查询

技能信息

• 名称: cloudcc-openapi-withobject
• 版本: 2.0.0
• 作者: 鲁班
• 创建日期: 2026-03-20
• 更新日期: 2026-03-20
• 适用范围: CloudCC One 版本 OpenAPI 接口调用

安装配置

配置参数

参数	说明	默认值	必填
orgId	组织 ID	-	是
username	登录用户名	-	是
safetyMark	安全标记（邮箱获取）	-	是
clientId	连接应用的 clientId	-	是
secretKey	连接应用的 secretKey	-	是
apiDomain	API 网关地址（动态获取）	-	否（自动获取）

获取配置信息

1. 组织 ID (orgId): 系统设置 - 公司信息中查看
2. 安全标记 (safetyMark): 个人信息 - 重置我的安全标记（发送到邮箱）
3. clientId/secretKey: 管理设置 - 安全性控制 - 连接的应用程序

安装步骤

bash

# 1. 创建技能目录
mkdir -p ~/.openclaw/skills/cloudcc-openapi-withobject

# 2. 创建配置文件
cat > ~/.openclaw/skills/cloudcc-openapi-withobject/config.json << 'EOF'
{
  "orgId": "your-org-id",
  "username": "your-username",
  "safetyMark": "your-safety-mark",
  "clientId": "your-client-id",
  "secretKey": "your-secret-key"
}
EOF

核心功能

1. 认证管理

• 动态获取组织 API 网关地址
• 获取 accessToken 并自动刷新
• accessToken 有效性验证
• 认证事件日志记录

2. 元数据查询（新增 v2.0.0）

方法	说明	API 端点
getAllTabs	获取所有选项卡（推荐用于查找对象）	/openApi/common (getAllTabs)
pageQuery	查询对象数据（不带 fields 返回所有字段）	/openApi/common (pageQuery)
getStandardObjects	获取标准对象列表	/api/customObject/standardObjList
getCustomObjects	获取自定义对象列表	/api/customObject/list
getObjectFields	获取对象字段列表	/api/fieldSetup/queryField

注意: 元数据查询 API (/api/customObject/* 和 /api/fieldSetup/*) 可能需要额外的权限或使用 Setup 服务域名。推荐使用 getAllTabs 方法查找对象 API 名称。

3. 数据操作

• 查询: 普通查询、分页查询、带权限查询、SQL 查询
• 插入: 普通插入、带权限插入
• 更新: 普通更新、带权限更新
• 删除: 普通删除、带权限删除
• Upsert: 插入或更新

4. 文件服务

• 图片上传（单张/多张）
• 文件上传（流/base64）
• 文件下载
• 附件管理

5. 消息服务

• 发送邮件
• 发送手机短信
• Chatter 微帖操作

6. 审批流程

• 查询待审批项目
• 批准/拒绝/重新分配
• 提交审批

7. 安全日志（v2.1.0 新增）

• 自动记录所有 API 调用（服务名、对象、响应码、耗时）
• 记录认证事件（token 请求、刷新、过期）
• 日志自动清理（保留最近 3 天）
• 支持日志查询、统计、导出

使用方法

快速开始

bash

# 1. 获取 API 网关地址
curl -X GET "https://developer.apis.cloudcc.cn/oauth/apidomain?scope=cloudccCRM&orgId=YOUR_ORG_ID"

# 返回示例:
# {"result":true,"returnInfo":"","returnCode":"1","orgapi_address":"https://xxxx.apis.cloudcc.cn/lightningapi"}

# 2. 获取 accessToken
curl -X POST "https://xxxx.apis.cloudcc.cn/lightningapi/api/cauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username":"your-username",
    "safetyMark":"your-safety-mark",
    "clientId":"your-client-id",
    "secretKey":"your-secret-key",
    "orgId":"your-org-id",
    "grant_type":"password"
  }'

# 返回示例:
# {"data":{"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."},"returnCode":"1","result":true}

日志管理（v2.1.0 新增）

bash

# 查看最近的日志
~/.openclaw/skills/cloudcc-openapi-withobject/scripts/logger.sh view 50

# 查看统计信息
~/.openclaw/skills/cloudcc-openapi-withobject/scripts/logger.sh stats 3

# 搜索日志
~/.openclaw/skills/cloudcc-openapi-withobject/scripts/logger.sh search "productuplist"

# 导出日志
~/.openclaw/skills/cloudcc-openapi-withobject/scripts/logger.sh export

# 清理旧日志（保留最近 3 天）
~/.openclaw/skills/cloudcc-openapi-withobject/scripts/logger.sh cleanup 3

日志格式

每条日志为 JSON 格式，包含以下字段：

json

{
  "timestamp": "2026-03-20 12:15:30",
  "type": "API_REQUEST",
  "service": "pageQuery",
  "objectApi": "productuplist",
  "responseCode": "1",
  "durationMs": "125"
}

日志类型

类型	说明	示例
API_REQUEST	API 调用记录	记录所有 OpenAPI 调用
AUTH_EVENT	认证事件	token 请求、刷新、过期

元数据查询示例（v2.0.0 新增）

获取标准对象列表

bash

curl -X POST "$API_DOMAIN/api/customObject/standardObjList" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

返回示例:

json

{
  "result": true,
  "data": [
    {"id": "account", "objname": "客户", "label": "Account", "objprefix": "001"},
    {"id": "contact", "objname": "联系人", "label": "Contact", "objprefix": "003"},
    {"id": "opportunity", "objname": "业务机会", "label": "Opportunity", "objprefix": "002"}
  ]
}

获取自定义对象列表

bash

curl -X POST "$API_DOMAIN/api/customObject/list" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":""}'

返回示例:

json

{
  "result": true,
  "data": {
    "objList": [
      {"id": "2021A51AA0D3785lBzwh", "objLabel": "产品需求研发报备记录", "schemetable_name": "productuplist", "prefix": "b70"},
      {"id": "2023D181015EDF0f7G1y", "objLabel": "需求池", "schemetable_name": "requirementpool", "prefix": "c75"}
    ]
  }
}

获取对象字段列表

bash

curl -X POST "$API_DOMAIN/api/fieldSetup/queryField" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"b70"}'

返回示例:

json

{
  "result": true,
  "data": {
    "obj": {"id": "2021A51AA0D3785lBzwh", "label": "产品需求研发报备记录"},
    "stdFields": [
      {"id": "1", "labelName": "名称", "schemefieldName": "name", "schemefieldType": "S"}
    ],
    "cusFields": [
      {"id": "c1", "labelName": "产品", "schemefieldName": "product", "schemefieldType": "S"},
      {"id": "c2", "labelName": "状态", "schemefieldName": "zhuangtai", "schemefieldType": "L"}
    ]
  }
}

通过选项卡查找对象（实用技巧）

bash

# 搜索包含关键词的选项卡
curl -X POST "$API_DOMAIN/openApi/common" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceName":"getAllTabs"}' | jq '.data[] | select(.tab_name | test("产品 | 需求"))'

返回示例:

json

{
  "tab_name": "产品需求研发报备记录",
  "objectApi": "productuplist",
  "prefix": "b70",
  "objId": "2021A51AA0D3785lBzwh"
}

数据查询示例

普通查询 (cquery)

json

{
  "serviceName": "cquery",
  "objectApiName": "Contact",
  "expressions": "name='test'",
  "isAddDelete": "false",
  "fields": "name,createdate,createbyid"
}

分页查询 (pageQuery)

json

{
  "serviceName": "pageQuery",
  "objectApiName": "Account",
  "fields": "id,name,phone",
  "expressions": "industry='Technology'",
  "pageNUM": 1,
  "pageSize": 20
}

插入数据 (insert)

json

{
  "serviceName": "insert",
  "objectApiName": "Contact",
  "data": "[{\"name\":\"张三\",\"phone\":\"13800138000\",\"email\":\"[e-mail]\"}]"
}

更新数据 (update)

json

{
  "serviceName": "update",
  "objectApiName": "Contact",
  "data": "[{\"id\":\"003202100BDF459HcI1R\",\"name\":\"李四\",\"phone\":\"13900139000\"}]"
}

删除数据 (delete)

json

{
  "serviceName": "delete",
  "objectApiName": "Contact",
  "data": "[{\"id\":\"003202100BDF459HcI1R\"}]"
}

Upsert (插入或更新)

json

{
  "serviceName": "upsert",
  "objectApiName": "Contact",
  "data": "[{\"id\":\"003202100BDF459HcI1R\",\"name\":\"王五\"}]"
}

API 接口列表

认证相关

接口	服务名	说明
获取网关	GET /oauth/apidomain	动态获取组织 API 地址
获取 token	POST /api/cauth/token	获取 accessToken
验证 token	isValidWithBinding	验证 accessToken 有效性

元数据查询（v2.0.0 新增）

接口	端点	说明
获取标准对象	POST /api/customObject/standardObjList	返回所有标准对象
获取自定义对象	POST /api/customObject/list	返回所有自定义对象
获取对象字段	POST /api/fieldSetup/queryField	根据 prefix 查询字段
获取选项卡	POST /openApi/common (getAllTabs)	返回所有选项卡配置

查询服务

接口	服务名	说明
普通查询	cquery	基础查询
带权限查询	cqueryWithRoleRight	含权限控制的查询
分页查询	pageQuery	分页数据查询
分页带权限查询	pageQueryWithRoleRight	含权限的分页查询
获取查询权限	getQueryPermisson	获取对象查询权限
SQL 查询	cqlQueryWithLogInfo	自定义 SQL 查询
静态查询	cqlQueryWithStatic	支持游标的静态查询

数据操作

接口	服务名	说明
插入	insert	插入数据
带权限插入	insertWithRoleRight	含权限控制的插入
更新	update	更新数据
带权限更新	updateWithRoleRight	含权限控制的更新
删除	delete	删除数据
带权限删除	deleteWithRoleRight	含权限控制的删除
Upsert	upsert	插入或更新
Upsert 带权限	upsertWithRoleRight	含权限的 upsert

文件服务

接口	服务名	地址	说明
上传图片	uploadImg	/openApi/file	单张图片上传
上传多图	uploadImgMany	/openApi/file	最多 9 张
获取图片属性	getImgProperty	/openApi/common	查询图片信息
上传文件	uploadFile	/openApi/file	文件流上传
上传附件	uploadAttachement	/openApi/common	base64 上传
下载文件	downloadFile	/openApi/downloadFile	GET 请求
下载附件	downloadAttachement	/openApi/common	base64 下载
删除附件	deleteAttachment	/openApi/common	删除附件
删除文件	deleteFile	/openApi/common	删除文件

消息服务

接口	服务名	说明
发送邮件	sendEmail	支持模板变量
发送短信	telMessage	手机消息服务

Chatter 服务

接口	服务名	说明
获取 Chatter	getChatters01	查询微帖内容
获取我的 Chatter	getMyChatter01	我追随的内容
获取追随者	getFollowUsers	查询追随关系
发布帖子	addMicroPostF	普通帖子
发布文件帖	addMicroPostD	带文件的帖子
发布链接帖	addMicroPostL	带链接的帖子
发布投票帖	addMicroPostV	投票类型帖子
投票	voteMicroPost	对帖子投票
发布评论	addMicroComment	普通评论
文件评论	addMicroCommentFile	带文件评论
点赞帖子	praiseFeed	喜欢/取消喜欢
点赞评论	praiseComment	评论点赞
收藏帖子	favoriteFeed	收藏/取消收藏
删除帖子	removeMicroPost	删除微帖
删除评论	removeMicroComment	删除评论
追随操作	operateFollowRelation	追随/取消追随

审批服务

接口	服务名	说明
待审批列表	getApprovalPaddingList	查询待审批项目
批准	doApproved	批准操作
拒绝	doRejected	拒绝操作
重新分配	doReassign	重新分配审批人
调回	reCall	调回审批
提交审批	submitForApproval	提交审批流程

其他服务

接口	服务名	说明
获取应用列表	getAppList	应用程序列表
获取选项卡	getAllTabs	选项卡信息
获取应用和选项卡	getAppAndTabList	合并查询
获取搜索设置	getMySetupObjs	搜索配置
获取选项列表值	getPickListValue	字段选项值
保存依赖关系	saveDependency	选项依赖配置
自助服务	customService	MongoDB 数据操作

返回码说明

代码	说明
1	调用成功
-1	调用成功但接口异常
-2	调用不成功（如失效）
-3	参数输入有误

最佳实践

1. 查找对象的完整流程（v2.0.0）

bash

# 步骤 1: 通过选项卡名称查找对象（最直观）
curl -X POST "$API_DOMAIN/openApi/common" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceName":"getAllTabs"}' | jq '.data[] | select(.tab_name | test("产品需求"))'

# 返回：{"objectApi":"productuplist","prefix":"b70","objId":"2021A51AA0D3785lBzwh"}

# 步骤 2: 使用 objectApi 查询数据
curl -X POST "$API_DOMAIN/openApi/common" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceName":"pageQuery","objectApiName":"productuplist","pageNUM":1,"pageSize":20}'

# 步骤 3: 使用 prefix 查询字段结构
curl -X POST "$API_DOMAIN/api/fieldSetup/queryField" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"b70"}'

2. 网关地址动态获取

禁止写死 API 地址，组织网关可能根据负载漂移：

bash

# 每次启动时获取
API_DOMAIN=$(curl -s "https://developer.apis.cloudcc.cn/oauth/apidomain?scope=cloudccCRM&orgId=$ORG_ID" | jq -r '.orgapi_address')

3. accessToken 管理

• accessToken 放入请求头：accessToken: <value>
• 定期验证有效性（使用 isValidWithBinding）
• 失效时重新获取

4. 批量操作

• 插入/更新/删除支持批量操作
• data 参数为 JSON 数组：[{...}, {...}]
• 注意 API 调用配额限制

5. 特殊字符处理

URL 中的特殊字符需要 URL 编码：

java

java.net.URLEncoder.encode("%", "UTF-8")

6. 字段命名规范

• 服务名和参数名首字母小写
• 如文档中大写，请改为小写

API 配额限制

版本	基础次数	每用户额外	最大限额/24h
专业版	5000	用户数×150	10000
企业版	50000	用户数×300	200000
旗舰版	50000	用户数×500	500000
超级版	50000	用户数×500	500000

⚠️ 禁止超负荷请求，否则 API Client 可能被停用

故障排查

常见问题

1. accessToken 失效: 重新调用 /api/cauth/token
2. 网关地址变化: 重新获取 /oauth/apidomain
3. 权限不足: 检查简档权限或使用带权限接口
4. 参数错误: 检查字段名是否小写、JSON 格式是否正确
5. 对象不存在: 使用 getAllTabs 或 getCustomObjects 确认对象 API 名称

调试技巧

bash

# 1. 验证 token 有效性
curl -X POST "$API_DOMAIN/openApi/common" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceName":"isValidWithBinding"}'

# 2. 检查返回码
# returnCode: "1" 表示成功
# returnCode: "-1" 表示接口异常
# returnCode: "-2" 表示 token 失效
# returnCode: "-3" 表示参数错误

# 3. 查找对象 API 名称
curl -X POST "$API_DOMAIN/openApi/common" \
  -H "accessToken: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceName":"getAllTabs"}' | jq '.data[] | select(.tab_name | test("关键词"))'

版本历史

v2.1.0 (2026-03-20)

• ✅ 新增安全日志功能
• ✅ 支持 logger.sh - 日志管理工具
• ✅ 自动记录所有 API 调用（服务名、对象、响应码、耗时）
• ✅ 自动记录认证事件（token 请求、刷新、过期）
• ✅ 日志自动清理（保留最近 3 天）
• ✅ 支持日志查询、统计、导出

v2.0.0 (2026-03-20)

• ✅ 新增元数据查询能力
• ✅ 支持 getStandardObjects - 获取标准对象列表
• ✅ 支持 getCustomObjects - 获取自定义对象列表
• ✅ 支持 getObjectFields - 获取对象字段列表
• ✅ 支持 getAllTabs - 获取选项卡信息
• ✅ 新增对象查找最佳实践文档

v1.0.0 (2026-03-20)

• ✅ 初始版本
• ✅ 完整 API 接口文档
• ✅ 认证管理
• ✅ 数据 CRUD 操作
• ✅ 文件服务
• ✅ 消息服务
• ✅ Chatter 接口
• ✅ 审批流程

---

维护人: 鲁班
参考文档: https://help.cloudcc.cn/product03/apigai-lan/