leoyeai/cloudcc-openapi-withobject

技能信息

• 名称: 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\":\"zhangsan@example.com\"}]"
}

更新数据 (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/