腾讯云代码助手第三方开发集成

腾讯云代码助手支持配置第三方开发集成，支持通过开发第三方服务的方式，实现对接其他身份管理平台。通过本文档，您将了解到配置第三方开发集成的具体步骤，包括相关接口规范和在腾讯云代码助手平台上所需进行的配置。
说明：
本文档适用于：CodeBuddy 专享版、企业版。
CodeBuddy 旗舰版使用 腾讯统一身份 进行登录认证管理，如需配置详见腾讯统一身份-企业级登录。
操作步骤
步骤一：第三方服务开发
按照下文中的接口规范，开发第三方服务。
步骤二：启用第三方集成
进入企业域名后台 <企业id>.copilot.qq.com/admin，选择开放与集成 > 组织架构同步，单击任意第三方系统；
﻿
根据页面提示，输入上游系统名称、服务域名、token 信息；
﻿
配置关联规则，支持根据用户 ID、邮箱、手机号匹配，选择完成后提交即可。
﻿
步骤三：效果验证
配置完成，在开放与集成 > 组织架构同步页面，可以看到从第三方服务获取到的组织架构和人员信息，能查看到即代表获取成功，单击手动关联，系统会将该成员从第三方服务中同步至 CodeBuddy；
﻿
接口规范
1. 概述
custom provider 通过 HTTP 代理对接外部组织架构服务。组织服务需要实现一组固定的 REST 接口，返回符合约定的数据结构。
2. 接入流程
2.1 部署自定义组织服务，实现本文所列 API。
2.2 配置组织服务访问参数（BaseURL、AuthToken、EnterpriseID 等）。
2.3 使用 /org/health 校验可用性。
3. 配置项（custom）
{
  "name": "custom-org",
  "base_url": "https://example.com",
  "enterprise_id": "ent-xxx",
  "timeout_seconds": 15,
  "auth_header": "Authorization",
  "auth_token": "token-value",
  "bearer_token": true,
  "extra_headers": {
    "X-From": "org-service"
  },
  "account_id_header": "X-Account-Id",
  "account_id_query": "account_id",
  "success_code": 0,
  "config_header": "X-Custom-Config"
}
字段说明：
base_url：必填，自定义组织服务的根地址。
enterprise_id：默认会作为 enterprise_id 查询参数附加。
timeout_seconds：请求超时，默认 15 秒。
auth_token：鉴权 token，发送 Authorization: Bearer <token>。
auth_header / bearer_token：当前实现未生效，仅用于日志。
extra_headers：会附加到所有请求。
account_id_header：如果设置，会将 AccountID 放入该请求头。
account_id_query：如果设置，会将 AccountID 作为该 query 参数。
success_code：响应包装 code 成功值，默认 0。
config_header：默认 X-Custom-Config，值为 base64(json(config))。
4. 请求公共规则
请求头
Authorization: Bearer <auth_token>（auth_token 非空时）
X-Custom-Config: <base64(config-json)>（配置完整 JSON 编码）
extra_headers 中所有键值
若配置了 account_id_header 且本次请求有 AccountID，则附加该头
查询参数拼装
布尔值：仅当 true 才追加
整数值：仅当 > 0 才追加
字符串：trim 后非空才追加
切片：逗号拼接
默认追加 enterprise_id（若未显式提供）
路径参数
node_id / user_id 使用 url.PathEscape 转义
响应格式
支持两种格式：
1.1.1 直接返回目标结构 JSON
1.1.2 包装结构：
{ "code": 0, "message": "ok", "data": { ... } }
code 必须等于 success_code（默认 0）
5. 数据结构（JSON）
组织节点（OrgNode）字段说明（Swagger 类型）：
id（string）：节点唯一标识
name（string）：节点名称
display_name（string）：展示名称
parent_id（string）：父节点 ID
full_path（string）：节点完整路径
has_child（boolean）：是否有子节点
member_count（integer）：成员数量（可选）
user_count（integer）：已登录系统的用户数量（可选）
order（integer）：排序权重（可选）
attributes（object<string,string>）：自定义属性（键值对）
external_data（object）：扩展数据（任意 JSON）
组织节点（OrgNode）示例：
{
  "id": "dept-1",
  "name": "研发部",
  "display_name": "研发部",
  "parent_id": "root",
  "full_path": "/公司/研发部",
  "has_child": true,
  "member_count": 10,
  "user_count": 5,
  "order": 1,
  "attributes": { "cost_center": "R&D" },
  "external_data": { "raw": "..." }
}
成员（OrgMember）字段说明（Swagger 类型）：
id（string）：成员唯一标识
name（string）：成员名称（用户名/昵称）
display_name（string）：展示名称
email（string）：邮箱
mobile（string）：手机号
employee_number（string）：工号
title（string）：职级/职位
department_path（array<string>）：部门名称路径（不含 ID）
department_full_path（array<string>）：部门完整路径（可包含前缀）
is_leader（boolean）：是否负责人
status（string）：状态（如 active/disabled）
extra（object<string,string>）：扩展字段（键值对）
成员（OrgMember）示例：
{
  "id": "m-100",
  "name": "zhangsan",
  "display_name": "张三",
  "email": "a@b.com",
  "mobile": "13800000000",
  "employee_number": "E123",
  "title": "SDE",
  "department_path": ["公司", "研发部"],
  "department_full_path": ["/公司", "/公司/研发部"],
  "is_leader": false,
  "status": "active",
  "extra": { "location": "SZ" }
}
用户（OrgUser）字段说明（Swagger 类型）：
member（OrgMember）：成员信息
nodes（array<OrgNode>）：所属节点列表
用户（OrgUser）示例：
{
  "member": { ...OrgMember... },
  "nodes": [ ...OrgNode... ]
}
6. API 列表
6.1 健康检查
GET /org/health
响应：HealthStatus
响应字段说明（Swagger 类型）：
enterprise_id（string）：企业 ID
provider（string）：提供方名称（固定为 custom）
status（string）：状态（healthy/unhealthy）
message（string）：异常信息
last_synced_at（string(date-time)）：最近同步时间
cache_refreshed_at（string(date-time)）：最近缓存刷新时间
{
  "enterprise_id": "ent-xxx",
  "provider": "custom",
  "status": "healthy",
  "message": "",
  "last_synced_at": "2024-01-01T00:00:00Z",
  "cache_refreshed_at": "2024-01-01T00:00:00Z"
}
6.2 获取部门树
GET /org/nodes
Query 字段说明（Swagger 类型）
root_id（string）：起始节点 ID（为空表示从根开始）
depth（integer）：展开深度（正数才生效）
include_members（boolean）：是否返回成员信息（true 时生效）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
响应字段说明（Swagger 类型）
nodes（array<OrgNode>）：节点数组
{ "nodes": [ ...OrgNode... ] }
6.3 获取单个部门
GET /org/nodes/{id}
Query 字段说明（Swagger 类型）
include_path（boolean）：是否附带路径信息（true 时生效）
include_members（boolean）：是否返回成员信息（true 时生效）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
响应：OrgNode
6.4 批量获取部门
POST /org/nodes/batch
Query 字段说明（Swagger 类型）
include_path（boolean）：是否附带路径信息（true 时生效）
include_members（boolean）：是否返回成员信息（true 时生效）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
Body 字段说明（Swagger 类型）
node_ids（array<string>）：节点 ID 列表（必填）
include_path（boolean）：是否附带路径信息
include_members（boolean）：是否返回成员信息
use_cache（boolean）：是否允许缓存
account_id（string）：请求账号（可选）
{
  "node_ids": ["id1","id2"],
  "include_path": true,
  "include_members": false,
  "use_cache": true,
  "account_id": "acc-1"
}
响应字段说明（Swagger 类型）
nodes（array<OrgNode>）：节点数组
{ "nodes": [ ...OrgNode... ] }
6.5 子部门列表
GET /org/nodes/{id}/children
Query 字段说明（Swagger 类型）
include_members（boolean）：是否返回成员信息（true 时生效）
limit（integer）：分页大小（正数才生效）
offset（integer）：分页偏移（正数才生效）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
响应字段说明（Swagger 类型）
nodes（array<OrgNode>）：节点数组
{ "nodes": [ ...OrgNode... ] }
6.6 部门成员列表
GET /org/nodes/{id}/members
Query 字段说明（Swagger 类型）
include_subtree（boolean）：是否包含子部门成员（true 时生效）
use_cache（boolean）：是否允许缓存（true 时生效）
limit（integer）：分页大小（正数才生效）
offset（integer）：分页偏移（正数才生效）
role（string）：成员角色过滤
keyword（string）：关键词过滤
fields（string）：指定返回字段（逗号分隔）
account_id（string）：请求账号（用于审计/鉴权透传）
响应字段说明（MemberListResult, Swagger 类型）
members（array<OrgMember>）：成员数组
next_offset（integer）：下一页偏移
next_token（string）：下一页令牌
total（integer）：总数量
exhausted（boolean）：是否已返回完毕
{
  "members": [ ...OrgMember... ],
  "next_offset": 20,
  "next_token": "xxx",
  "total": 100,
  "exhausted": false
}
6.7 路径解析节点
GET /org/path
Query 字段说明（Swagger 类型）
delimiter（string）：路径分隔符（默认 /）
path（string）：路径字符串（segments 按 delimiter 拼接）
include_members（boolean）：是否返回成员信息（true 时生效）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
响应：OrgNode
6.8 搜索
GET /org/search
Query 字段说明（Swagger 类型）
type（string）：搜索类型（node/user：node 为部门，user 为用户）
keyword（string）：关键词
fuzzy（boolean）：是否模糊搜索（true 时为模糊搜索，false 时为精准搜索，注：接口需要支持两种搜索方式，否则页面可能报错）
limit（integer）：分页大小（正数才生效）
offset（integer）：分页偏移（正数才生效）
fields（string）：指定返回字段（逗号分隔）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
响应字段说明（SearchResult, Swagger 类型）
nodes（array<OrgNode>）：匹配的节点列表
users（array<OrgMember>）：匹配的成员列表
next_offset（integer）：下一页偏移
next_token（string）：下一页令牌
total（integer）：总数量
exhausted（boolean）：是否已返回完毕
{
  "nodes": [ ...OrgNode... ],
  "users": [ ...OrgMember... ],
  "next_offset": 20,
  "next_token": "xxx",
  "total": 100,
  "exhausted": false
}
6.9 用户详情
GET /org/users/{id}
Query 字段说明（Swagger 类型）
use_cache（boolean）：是否允许缓存（true 时生效）
account_id（string）：请求账号（用于审计/鉴权透传）
响应：OrgUser
6.10 刷新缓存
POST /org/cache/refresh
Body 字段说明（Swagger 类型）
enterprise_id（string）：企业 ID（可选）
node_ids（array<string>）：需要刷新的节点 ID 列表（可选）
full_path（string）：部门路径（可选）
force（boolean）：是否强制刷新
{
  "enterprise_id": "ent-xxx",
  "node_ids": ["id1","id2"],
  "full_path": "/公司/研发部",
  "force": true
}
响应字段说明（Swagger 类型）
succeeded（array<string>）：成功刷新节点列表
failed（object<string,string>）：失败节点与原因映射
{
  "succeeded": ["id1"],
  "failed": { "id2": "reason" }
}
6.11 同步状态
GET /org/sync/status
响应：任意 JSON（RawMessage）
6.12 根据账号解析用户（内部逻辑）
SDK 会调用 /org/search（type=user, fuzzy=false, limit=1）
该接口无需额外实现
6.13 解析成员 ID
POST /org/members/resolve
Body 字段说明（Swagger 类型，注意：无 JSON tag，字段名为驼峰）
EnterpriseID（string）：企业 ID
UserID（string）：用户 ID
Username（string）：用户名/账号
Email（string）：邮箱
PhoneNumber（string）：手机号
{
  "EnterpriseID": "ent-xxx",
  "UserID": "u-1",
  "Username": "zhangsan",
  "Email": "a@b.com",
  "PhoneNumber": "13800000000"
}
响应字段说明（Swagger 类型）
member_id（string）：解析后的成员 ID
member（OrgMember）：成员详情（可选）
响应示例：
{
  "member_id": "m-1",
  "member": { ...OrgMember... }
}
7. 常见问题
响应包装是否必须？
不必须，可以直接返回数据结构 JSON；如果使用包装结构，需要提供 code/message/data。
鉴权头可以自定义吗？
当前实现是固定的 Authorization: Bearer <auth_token>。auth_header/bearer_token 仅在日志中显示，不参与实际请求。
Config Header 做什么？
SDK 会在 X-Custom-Config（或自定义 config_header）里传递完整配置的 Base64 JSON，用于自定义服务侧识别上下文（如 enterprise_id 等）。
﻿
第三方开发集成

本页目录：

操作步骤

步骤一：第三方服务开发

步骤二：启用第三方集成

步骤三：效果验证

接口规范

1. 概述

2. 接入流程

3. 配置项（custom）

4. 请求公共规则

5. 数据结构（JSON）

6. API 列表

6.1 健康检查

6.2 获取部门树

6.3 获取单个部门

6.4 批量获取部门

6.5 子部门列表

6.6 部门成员列表

6.7 路径解析节点

6.8 搜索

6.9 用户详情

6.10 刷新缓存

6.11 同步状态

6.12 根据账号解析用户（内部逻辑）

6.13 解析成员 ID

7. 常见问题
