cloudcc-openapi-withobject

技能信息

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

安装配置

配置参数

获取配置信息

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

安装步骤

# 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 (/api/customObject/* 和 /api/fieldSetup/*) 可能需要额外的权限或使用 Setup 服务域名。推荐使用 getAllTabs 方法查找对象 API 名称。

3. 数据操作

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

4. 文件服务

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

5. 消息服务

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

6. 审批流程

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

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

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

使用方法

快速开始

# 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 新增）

# 查看最近的日志
~/.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 格式，包含以下字段：

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

日志类型

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

获取标准对象列表

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

返回示例:

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

获取自定义对象列表

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

返回示例:

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

获取对象字段列表

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

返回示例:

{
  "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"}
    ]
  }
}

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

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

返回示例:

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

数据查询示例

普通查询 (cquery)

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

分页查询 (pageQuery)

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

插入数据 (insert)

{
  "serviceName": "insert",
  "objectApiName": "Contact",
  "data": "[{\"name\":\"张三\",\"phone\":\"13800138000\",\"email\":\"zhangsan@example.com\"}]"
}

更新数据 (update)

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

删除数据 (delete)

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

Upsert (插入或更新)

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

API 接口列表

认证相关

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

查询服务

数据操作

文件服务

消息服务

Chatter 服务

审批服务

其他服务

返回码说明

最佳实践

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

# 步骤 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 地址，组织网关可能根据负载漂移：

# 每次启动时获取
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.net.URLEncoder.encode("%", "UTF-8")

6. 字段命名规范

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

API 配额限制

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

故障排查

常见问题

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

调试技巧

# 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/