Open API

概述

SERVICEME Open API 调用基本流程：

第一步，采用身份认证章节提供的接口进行身份认证，获取 access token

认证分为两类，一类是用户认证，另一类是客户端认证。

用户认证：基于个人账号身份进行认证的方式。
客户端认证：用SERVICEME颁发的客户端code与secret进行认证的方式。

第二步，携带access token调用对应的API

身份认证方式

用户AAD认证

该方式属于用户认证的一种，需要使用到AAD的access token作为身份认证的依据。

AAD access token 获取方式：

AAD 与 React 集成文档：前往->

AAD 与 .Net 集成文档：前往->

AAD 与 Java 集成文档：前往->
接口地址：/openapi/auth/user/aad
请求方式：post
请求body：

参数名称	必填	类型	参数解释
token	是	string	用户AAD access token（对接方自己提供）

接口请求示例：

curl --location 'https://localhost/openapi/auth/user/aad' \
--header 'Content-Type: application/json' \
--data '{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlhSdmtvOFA3QTNVYVdTblU3Yk05blQwTWpoQSJ9.eyJhdWQiOiIzZTEwNjVhYS1jZWYxLTRiYTgtOWRiOS1kMWQ1Y2UzMGYyZDgiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNDRjMjRmNDItZDQ5Yi00MT......"
}'

响应body：

参数名称	参数二级	类型	参数解释
data		object	响应数据
	access_token	string	SERVICEME系统 access token
	expires_in	number	过期时间，单位分钟
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0V4dGVybmFsIjpmYWxzZSwidXNlcklkIjoiNDAzMDUwMjEwMTEyODgzOTE2OCIsImFjY291bnQiOiJlY210cmlhbEBzZXJ2aWNlbWUub25taWNyb3NvZ......",
        "expires_in": 1440
    },
    "success": true,
    "msg": ""
}

客户端与用户账户认证

这种认证方式采用客户端认证和用户账户认证相结合的方式。通过用户账户进行身份认证，同时需要使用客户端凭证(client code和secret)来确保接口调用的安全性。调用此接口时需要进行签名验证。

如何获取client和secret?

请联系系统管理员，管理员将通过以下地址为您创建并分配客户端凭证:

https://xxx/#/super-admin/client-management

接口地址：/openapi/auth/client_with_account
请求方式：post
请求body：

参数名称	必填	类型	参数解释
client	是	string	客户端code（SERVICEME提供）
account	是	string	用户账户（对接方提供）
timestamp	是	number	时间戳（13位数字，精度到毫秒，如 1711537596897 ）
nonce	是	string	6位随机数（数字或字母的组合均可）
signature	是	string	签名，五分钟内有效（签名格式：用冒号拼接后再MD5 `client:{client}secret:{secret}account:{account}timestamp:{timestamp}nonce:{nonce}` 得到的MD5 32位长度的值转小写）

javascript 签名示例：

请新建一个 html 文件粘贴以下内容后使用浏览器打开

<html>
  <head>
    <style>
      .box {
         width: 100%;
         height: 100%;
         padding: 50px 50px;
       }
       .row {
            display: flex;
            height: 50px;
            width: 100%;
          }
          .col1 {
            flex: 1;
       }
       .col2 {
         flex: 3;
       }
     </style>
   </head>
   <body>
      <div class="box">
      <div class="row">
           <div class="col1">client:</div>
           <div class="col2" id="client"></div>
         </div>
         <div class="row">
           <div class="col1">secret:</div>
           <div class="col2" id="secret"></div>
         </div>
        <div class="row">
        <div class="col1">account:</div>
        <div class="col2" id="account"></div>
      </div>
      <div class="row">
         <div class="col1">timestamp:</div>
         <div class="col2" id="timestamp"></div>
       </div>
       <div class="row">
         <div class="col1">nonce:</div>
         <div class="col2" id="nonce"></div>
       </div>
       <div class="row">
         <div class="col1">signature:</div>
         <div class="col2" id="signature"></div>
       </div>
     </div>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/crypto-js.min.js"></script>
     <script>
       const client = "openapi"
       const secret = "DzYwyICrKbUCEseYthCK0PfSfX7NPEuV"
       const account = "test@serviceme.com"
       const timestamp = +new Date()
       const nonce = "123abc"
       const message = `client:${client}secret:${secret}account:${account}timestamp:${timestamp}nonce:${nonce}` // 签名明文
       const md5Hash = CryptoJS.MD5(message).toString().toLowerCase(); // MD5 32位转小写
   
       console.log(`签名明文：${message}`)
       console.log(`签名结果：${md5Hash}`)
  
       document.getElementById('client').innerText = client;
       document.getElementById('secret').innerText = secret;
       document.getElementById('account').innerText = account;
       document.getElementById('timestamp').innerText = timestamp;
       document.getElementById('nonce').innerText = nonce;
       document.getElementById('signature').innerText = md5Hash;
     </script>
   </body>
   </html>

接口请求示例：

curl --location 'https://localhost/openapi/auth/client_with_account' \
--header 'Content-Type: application/json' \
--data '{
    "client": "openapi",
    "account": "test@serviceme.com",
    "timestamp": 1711537596456,
    "nonce": "123abc",
    "signature": "182be0c5cdcd5072bb1864cdee4d3d6e"
}'

响应body

参数名称	参数二级	类型	参数解释
data		object	响应数据
	access_token	string	SERVICEME系统 access token
	expires_in	number	过期时间，单位分钟
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

接口响应示例：

{
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0V4dGVybmFsIjpmYWxzZSwidXNlcklkIjoiNDAzMDUwMjEwMTEyODgzOTE2OCIsImFjY291bnQiOiJlY210cmlhbEBzZXJ2ub25ta......",
        "expires_in": 1440
    },
    "success": true,
    "msg": ""
}

用户

添加用户（支持批量）

接口地址：v1/openapi/user
**请求方式: **post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`userName`	是	`string`	无	账号/用户名
`password`	否	`string`	''	密码
`active`	否	`boolean`	true	激活状态
`userInfo`	否	`object`	无	用户信息
`userInfo.realName`	否	`string`	userName的值	真实姓名
`userInfo.spell`	否	`string`	无	真实姓名的拼音
`userInfo.serialNumber`	否	`string`	无	工号
`userInfo.nickName`	否	`string`	无	昵称
`userInfo.gender`	否	`number`	0	性别 0:FEMALE, 1:MALE
`userInfo.birthday`	否	`string`	无	生日
`userInfo.mobilePhone`	否	`string`	无	手机号
`userInfo.email`	否	`string`	无	邮箱
`userInfo.weChat`	否	`string`	无	微信号
`userInfo.avatar`	否	`string`	无	头像
`userInfo.region`	否	`string`	无	地区
`userInfo.joinTime`	否	`string`	无	入职日期
`userInfo.sort`	否	`number`	0	排序号
`userInfo.enable`	否	`boolean`	false	启动/禁用
`userInfo.description`	否	`string`	无	描述
`userInfo.external`	否	`boolean`	false	内外部用户标识 false: 内部用户, true: 外部用户
`userInfo.officePhoneNumber`	否	`string`	无	办公电话
`userInfo.isAad`	否	`string`	无	账号是否来自AAD(microsoft Entra ID)

请求示例：

curl --location 'http://localhost/v1/openapi/user' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "userName": "user1",  
    "password": "abc123",  
    "active": true,  
    "userInfo": {  
        "realName": "张三",  
        "spell": "zhangsan",
        "serialNumber": "123456",
        "nickName": "张三",
        "gender": 0,
        "birthday": "1990-01-01",
        "mobilePhone": "13800138000",
        "email": "zhangsan@email.com",
        "weChat": "zhangsan",
        "avatar": "/icons/e5392a9c9efb423cab69ce040dcb04e7.png",
        "region": "中国",
        "joinTime": "2023-01-01",
        "sort": 101,
        "enable": true,
        "description": "张三的描述",
        "external": false,
        "officePhoneNumber": "010-12345678",
        "isAad": false
    },  
}  '

响应body：

字段名	类型	说明
`data`	`object`	响应数据对象
`data.accountId`	`string`	账号 ID
`data.userId`	`string`	用户 ID
`data.userName`	`string`	用户名
`data.realName`	`string`	用户真名
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
	]
}

修改用户

接口地址：v1/openapi/user
**请求方式: **put
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`userName`	否	`string`	无	账号/用户名,只用来找到用户不会被修改,和id不能都为空
`id`	否	`string`	''	id,和userName不能都为空
`active`	否	`boolean`	true	激活状态
`realName`	否	`string`	userName的值	真实姓名
`spell`	否	`string`	无	真实姓名的拼音
`serialNumber`	否	`string`	无	工号
`nickName`	否	`string`	无	昵称
`gender`	否	`number`	0	性别 0:FEMALE, 1:MALE
`birthday`	否	`string`	无	生日
`mobilePhone`	否	`string`	无	手机号
`email`	否	`string`	无	邮箱
`weChat`	否	`string`	无	微信号
`avatar`	否	`string`	无	头像
`region`	否	`string`	无	地区
`joinTime`	否	`string`	无	入职日期
`sort`	否	`number`	0	排序号
`enable`	否	`boolean`	false	启动/禁用
`description`	否	`string`	无	描述
`external`	否	`boolean`	false	内外部用户标识 false: 内部用户, true: 外部用户
`officePhoneNumber`	否	`string`	无	办公电话
`isAad`	否	`string`	无	账号是否来自AAD(microsoft Entra ID)

请求示例：

curl --location 'http://localhost/v1/openapi/user' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "id": "123456",
    "userName": "user1",   
    "realName": "张三",  
    "spell": "zhangsan",
    "serialNumber": "123456",
    "nickName": "张三",
    "gender": 0,
    "birthday": "1990-01-01",
    "mobilePhone": "13800138000",
    "email": "zhangsan@email.com",
    "weChat": "zhangsan",
    "avatar": "/icons/e5392a9c9efb423cab69ce040dcb04e7.png",
    "region": "中国",
    "joinTime": "2023-01-01",
    "sort": 101,
    "enable": true,
    "description": "张三的描述",
    "external": false,
    "officePhoneNumber": "010-12345678",
    "isAad": false
}  '

响应body：

| 字段名 | 类型 | 说明 |
|----------------------|-------------|-------------------------------------------------------------| | | success | boolean | 请求是否成功 | | msg | string | 请求返回的消息（如果有） |

响应示例：

{
	"success": true,
	"msg": ""
}

删除用户

接口地址：v1/openapi/user
**请求方式: **delete
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
	是	`array`	无	用户Id数组或用户名数组. 数组里只能全都是Id或全都是用户名.

请求示例：

curl --location 'http://localhost/v1/openapi/user' \
--header 'Authorization: openapi {access_token}' \
--data '['user1','user2']'

响应body：

响应示例：

{
	"success": true,
	"msg": ""
}

启用用户

接口地址：v1/openapi/user/{userCode}/enable
**请求方式: **put
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
route参数：

参数名称	必填	类型	默认值	参数解释
userCode	是	`string`	无	用户Id数组或用户名

请求示例：

curl --location 'http://localhost/v1/openapi/user/123456/enable' \
--header 'Authorization: openapi {access_token}' \

响应body：

响应示例：

{
	"success": true,
	"msg": ""
}

禁用用户

接口地址：v1/openapi/user/{userCode}/disable
**请求方式: **put
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
route参数：

参数名称	必填	类型	默认值	参数解释
userCode	是	`string`	无	用户Id数组或用户名

请求示例：

curl --location 'http://localhost/v1/openapi/user/123456/disable' \
--header 'Authorization: openapi {access_token}' \

响应body：

响应示例：

{
	"success": true,
	"msg": ""
}

启用/禁用用户（支持批量）

接口地址：v1/openapi/user/enable
**请求方式: **put
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
codes	是	`array`	无	用户Id数组或用户名数组. 数组里只能全都是Id或全都是用户名.
operation	是	`boolean`	true	true: 启用, false: 禁用

请求示例：

curl --location 'http://localhost/v1/openapi/user/enable' \
--header 'Authorization: openapi {access_token}' \
--data '{
  "codes": ['user1', 'user2'],
  "operation": true
}'

响应body：

响应示例：

{
	"success": true,
	"msg": ""
}

获取用户列表（分页）

接口地址：v1/openapi/user/pageList
**请求方式: **post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`orderField`	是	`string`	无	用于排序的字段,Id含有时间信息,可以用id排序来用作创建时间的排序
`orderType`	是	`string`	无	排序类型, asc: 正序, desc: 倒序
`conditions`	否	`array`	无	查询条件,传多个时相互之间是 and 的关系
`conditions.fieldName`	否	`string`	无	查询条件的名称,如realName
`conditions.fieldValue`	否	`string`	无	查询条件的值
`conditions.conditionalType`	否	`number`	0	查询条件的比较类型 0: 精确匹配, 1: 模糊匹配, 2: 大于, 3: 大于等于, 4:小于, 5: 小于等于, 6: 包含(in), 7: 不包含(not in), 8: 向左模糊匹配, 9:向右模糊匹配, 10: 不等于, 11: nullOrEmpty, 12: 不为空, 13: notLike
`pageIndex`	是	`number`	无	页码
`pageSize`	是	`number`	无	每页的数量

请求示例：

curl --location 'http://localhost/v1/openapi/user/pageList' \
--header 'Authorization: openapi {access_token}' \
{
  "orderField": "id",
  "orderType": "desc",
  "conditions": [
    {
      "fieldName": "realName",
      "fieldValue": "张三",
      "conditionalType": 0
    }
  ],
  "pageIndex": 1,
  "pageSize": 15
}

响应body：

字段名	类型	说明
`data`	`array`	分页数据
`data.id`	`string`	账号 ID
`data.userId`	`string`	用户 ID
`data.userName`	`string`	用户名
`data.active`	`boolean`	是否激活
`data.avatar`	`string`	头像
`data.birthday`	`string`	生日
`data.created`	`string`	用户数据创建日期
`data.modified`	`string`	用户数据最后修改日期
`data.description`	`string`	描述
`data.gender`	`number`	性别 0:FEMALE, 1:MALE
`data.mobilePhone`	`string`	手机号
`data.nickName`	`string`	昵称
`data.email`	`string`	邮箱
`data.joinTime`	`string`	入职日期
`data.region`	`string`	地区
`data.weChat`	`string`	微信号
`data.spell`	`string`	真实姓名的拼音
`data.serialNumber`	`string`	工号
`data.accountId`	`string`	用户所属的账号Id
`data.sort`	`number`	排序号
`data.officePhoneNumber`	`string`	办公电话
`data.external`	`boolean`	内外部用户标识 false: 内部用户, true: 外部用户
`data.isAad`	`boolean`	账号是否来自AAD(microsoft Entra ID)
`data.enable`	`boolean`	启动/禁用
`pageIndex`	`number`	当前页码
`pageSize`	`number`	页码大小
`totalCount`	`number`	总条数
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
    "data": [
        {
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
    ],
    "pageSize": 15,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": null
}

获取用户信息

接口地址：v1/openapi/user/{userCode}
**请求方式: **get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
route参数：

参数名称	必填	类型	默认值	参数解释
userCode	是	`string`	无	用户Id数组或用户名

请求示例：

curl --location 'http://localhost/v1/openapi/user/123456' \
--header 'Authorization: openapi {access_token}' \

响应body：

字段名	类型	说明
`data`	`object`	响应数据对象
`data.id`	`string`	账号 ID
`data.userId`	`string`	用户 ID
`data.userName`	`string`	用户名
`data.Active`	`boolean`	是否激活
`data.Avatar`	`string`	头像
`data.Birthday`	`string`	生日
`data.Created`	`string`	用户数据创建日期
`data.Modified`	`string`	用户数据最后修改日期
`data.Description`	`string`	描述
`data.Gender`	`number`	性别 0:FEMALE, 1:MALE
`data.MobilePhone`	`string`	手机号
`data.NickName`	`string`	昵称
`data.Email`	`string`	邮箱
`data.JoinTime`	`string`	入职日期
`data.Region`	`string`	地区
`data.WeChat`	`string`	微信号
`data.Spell`	`string`	真实姓名的拼音
`data.SerialNumber`	`string`	工号
`data.AccountId`	`string`	用户所属的账号Id
`data.Sort`	`number`	排序号
`data.OfficePhoneNumber`	`string`	办公电话
`data.External`	`boolean`	内外部用户标识 false: 内部用户, true: 外部用户
`data.IsAad`	`boolean`	账号是否来自AAD(microsoft Entra ID)
`data.Enable`	`boolean`	启动/禁用
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
	]
}

获取当前登录用户的信息

接口地址：v1/openapi/user/me
**请求方式: **get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求示例：

curl --location 'http://localhost/v1/openapi/user/me' \
--header 'Authorization: openapi {access_token}' \

响应body：

字段名	类型	说明
`data`	`object`	响应数据对象
`data.id`	`string`	账号 ID
`data.userId`	`string`	用户 ID
`data.userName`	`string`	用户名
`data.Active`	`boolean`	是否激活
`data.Avatar`	`string`	头像
`data.Birthday`	`string`	生日
`data.Created`	`string`	用户数据创建日期
`data.Modified`	`string`	用户数据最后修改日期
`data.Description`	`string`	描述
`data.Gender`	`number`	性别 0:FEMALE, 1:MALE
`data.MobilePhone`	`string`	手机号
`data.NickName`	`string`	昵称
`data.Email`	`string`	邮箱
`data.JoinTime`	`string`	入职日期
`data.Region`	`string`	地区
`data.WeChat`	`string`	微信号
`data.Spell`	`string`	真实姓名的拼音
`data.SerialNumber`	`string`	工号
`data.AccountId`	`string`	用户所属的账号Id
`data.Sort`	`number`	排序号
`data.OfficePhoneNumber`	`string`	办公电话
`data.External`	`boolean`	内外部用户标识 false: 内部用户, true: 外部用户
`data.IsAad`	`boolean`	账号是否来自AAD(microsoft Entra ID)
`data.Enable`	`boolean`	启动/禁用
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
	]
}

获取当前登录用户的角色

接口地址：v1/openapi/user/roles
**请求方式: **get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求示例：

curl --location 'http://localhost/v1/openapi/user/me/roles' \
--header 'Authorization: openapi {access_token}' \

响应body：

字段名	类型	说明
`data`	`array`	响应数据对象
`data.roleId`	`string`	角色ID
`data.roleName`	`string`	角色名称
`data.dataPermissionList`	`array`	用户在这个角色下的数据权限
`data.dataPermissionList.BusinessTreeType`	`number`	应用类型
`data.dataPermissionList.DataPermissionObjectId`	`string`	数据权限对象Id,比如如果是知识库权限就是那个知识库的Id
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"roleId": "123456",
			"roleName": "知识库访客",
			"dataPermissionList": [
                {
                    "BusinessTreeType": 1,
                    "DataPermissionObjectId": "123456"
                }
            ]
		}
	]
}

获取用户已关联的角色

接口地址：v1/openapi/user/{userCode}/roles
**请求方式: **get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
route参数：

参数名称	必填	类型	默认值	参数解释
userCode	是	`string`	无	用户Id数组或用户名

请求示例：

curl --location 'http://localhost/v1/openapi/user/123456/roles' \
--header 'Authorization: openapi {access_token}' \

响应body：

字段名	类型	说明
`data`	`array`	响应数据对象
`data.roleId`	`string`	角色ID
`data.roleName`	`string`	角色名称
`data.dataPermissionList`	`array`	用户在这个角色下的数据权限
`data.dataPermissionList.BusinessTreeType`	`number`	应用类型
`data.dataPermissionList.DataPermissionObjectId`	`string`	数据权限对象Id,比如如果是知识库权限就是那个知识库的Id
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"roleId": "123456",
			"roleName": "知识库访客",
			"dataPermissionList": [
                {
                    "BusinessTreeType": 1,
                    "DataPermissionObjectId": "123456"
                }
            ]
		}
	]
}

用户角色关系修改

接口地址：v1/openapi/user/{userCode}/roles
**请求方式: **put
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
route参数：

参数名称	必填	类型	默认值	参数解释
userCode	是	`string`	无	用户Id数组或用户名

请求body：

参数名称	必填	类型	默认值	参数解释
	是	`array`	无	角色Id数组或角色名称数组. 数组里只能全都是Id或全都是名称.

请求示例：

curl --location 'http://localhost/v1/openapi/user/123456/roles' \
--header 'Authorization: openapi {access_token}' \

响应body：

字段名	类型	说明
`data`	`array`	响应数据对象
`data.roleId`	`string`	角色ID
`data.roleName`	`string`	角色名称
`data.dataPermissionList`	`array`	用户在这个角色下的数据权限
`data.dataPermissionList.BusinessTreeType`	`number`	应用类型
`data.dataPermissionList.DataPermissionObjectId`	`string`	数据权限对象Id,比如如果是知识库权限就是那个知识库的Id
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"roleId": "123456",
			"roleName": "知识库访客",
			"dataPermissionList": [
                {
                    "BusinessTreeType": 1,
                    "DataPermissionObjectId": "123456"
                }
            ]
		}
	]
}

组织

添加组织

接口地址：v1/openapi/organization
**请求方式: **post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`code`	是	`string`	无	组织代号,在系统中唯一，不可重复
`parentId`	否	`string`	无	父级组织机构Id和父级组织名称至少要填一项
`parentName`	否	`string`	无	父级组织机构名称,和父级组织Id至少要填一项
`name`	是	`string`	无	名称
`location`	否	`string`	无	地址
`remarks`	否	`string`	无	备注
`contact`	否	`string`	无	联系方式
`Info`	否	`string`	无	机构信息
`Extension`	否	`string`	无	扩展信息
`IsSubsidiary`	否	`boolean`	false	是否子公司
`sort`	否	`number`	0	排序号
`isEnable`	否	`boolean`	false	启动/禁用
`external`	否	`boolean`	false	内外部组织标识 false: 内部, true: 外部

请求示例：

curl --location 'http://localhost/v1/openapi/organization' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "code": "123456",
    "parentId": "12345",
    "name": "组织名称",
    "location": "地址"
}  '

响应body：

字段名	类型	说明
`data`	`object`	响应数据对象
`data.id`	`string`	组织ID
`data.code`	`string`	组织代号
`data.parentId`	`string`	父级组织Id
`data.parentName`	`string`	是否激活
`data.name`	`string`	名称
`data.location`	`string`	地址
`data.remarks`	`string`	备注
`data.contact`	`string`	联系方式
`data.Info`	`string`	机构信息
`data.Extension`	`number`	扩展信息
`data.IsSubsidiary`	`boolean`	是否子公司
`data.sort`	`number`	排序号
`data.isEnable`	`boolean`	启动/禁用
`data.external`	`boolean`	内外部组织标识
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"id": "123456",
            "code": "123456",
            "parentId": "12345",
            "name": "组织名称",
            "location": "地址"
		}
	]
}

更新组织

接口地址：v1/openapi/organization
**请求方式: **put
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`id`	否	`string`	无	组织id,和code至少要填一项
`code`	否	`string`	无	组织代号,和id至少要填一项
`parentId`	否	`string`	无	父级组织机构Id和父级组织名称至少要填一项
`parentName`	否	`string`	无	父级组织机构名称,和父级组织Id至少要填一项
`name`	是	`string`	无	名称
`location`	否	`string`	无	地址
`remarks`	否	`string`	无	备注
`contact`	否	`string`	无	联系方式
`Info`	否	`string`	无	机构信息
`Extension`	否	`string`	无	扩展信息
`IsSubsidiary`	否	`boolean`	false	是否子公司
`sort`	否	`number`	0	排序号
`isEnable`	否	`boolean`	false	启动/禁用
`external`	否	`boolean`	false	内外部组织标识 false: 内部, true: 外部

请求示例：

curl --location 'http://localhost/v1/openapi/organization' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "code": "123456",
    "parentId": "12345",
    "name": "组织名称",
    "location": "地址"
}  '

响应body：

字段名	类型	说明
`data`	`object`	响应数据对象
`data.id`	`string`	组织ID
`data.code`	`string`	组织代号
`data.parentId`	`string`	父级组织Id
`data.parentName`	`string`	是否激活
`data.name`	`string`	名称
`data.location`	`string`	地址
`data.remarks`	`string`	备注
`data.contact`	`string`	联系方式
`data.Info`	`string`	机构信息
`data.Extension`	`number`	扩展信息
`data.IsSubsidiary`	`boolean`	是否子公司
`data.sort`	`number`	排序号
`data.isEnable`	`boolean`	启动/禁用
`data.external`	`boolean`	内外部组织标识
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
		{
			"id": "123456",
            "code": "123456",
            "parentId": "12345",
            "name": "组织名称",
            "location": "地址"
		}
	]
}

删除组织

接口地址：v1/openapi/organization
**请求方式: **delete
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
	是	`array`	无	组织Id数组或组织名数组. 数组里只能全都是Id或全都是组织名.

请求示例：

curl --location 'http://localhost/v1/openapi/organization' \
--header 'Authorization: openapi {access_token}' \
--data '['org1','org2']'

响应body：

响应示例：

{
	"success": true,
	"msg": ""
}

获取树状组织结构

接口地址：v1/openapi/organization/tree
**请求方式: **get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求query：

参数名称	必填	类型	默认值	参数解释
`external`	否	`boolean`	false	是否外部组织

请求示例：

curl --location 'http://localhost/v1/openapi/organization/tree' \
--header 'Authorization: openapi {access_token}' \

响应body：

字段名	类型	说明
`data`	`array`	响应数据对象
`data.nodeId`	`string`	组织ID
`data.nodeName`	`string`	组织名称
`data.parentNodeId`	`string`	父级组织Id
`data.code`	`string`	组织代号
`data.path`	`string`	根节点至当前节点的路径--节点走过的id(用'/'来分开)
`data.external`	`boolean`	内外部组织标识
`data.childNodeList`	`array`	子组织
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": "",
	"data": [
        {
            "isExternal": false,
            "sort": 1,
            "nodeId": "4034994050380595200",
            "nodeName": "内部组织",
            "path": "4034994050380595200/4419926899526991872",
            "parentNodeId": "-1",
            "childNodeList": [
                {
                    "isExternal": false,
                    "sort": 1,
                    "nodeId": "4419926899526991872",
                    "nodeName": "IT",
                    "path": "4034994050380595200/4419926899526991872",
                    "parentNodeId": "4034994050380595200",
                }
            ]
        }
    ]
}

根据用户组织关系获取用户（分页）

接口地址：v1/openapi/organization/getAllOrgUserPageList
**请求方式: **post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`orderField`	是	`string`	无	用于排序的字段,Id含有时间信息,可以用id排序来用作创建时间的排序
`orderType`	是	`string`	无	排序类型, asc: 正序, desc: 倒序
`conditions`	否	`array`	无	查询条件,传多个时相互之间是 and 的关系
`conditions.fieldName`	否	`string`	无	查询条件的名称,如organizationId
`conditions.fieldValue`	否	`string`	无	查询条件的值
`conditions.conditionalType`	否	`number`	0	查询条件的比较类型 0: 精确匹配, 1: 模糊匹配, 2: 大于, 3: 大于等于, 4:小于, 5: 小于等于, 6: 包含(in), 7: 不包含(not in), 8: 向左模糊匹配, 9:向右模糊匹配, 10: 不等于, 11: nullOrEmpty, 12: 不为空, 13: notLike
`pageIndex`	是	`number`	无	页码
`pageSize`	是	`number`	无	每页的数量

请求示例：

curl --location 'http://localhost/v1/openapi/organization/getAllOrgUserPageList' \
--header 'Authorization: openapi {access_token}' \
{
  "orderField": "id",
  "orderType": "desc",
  "conditions": [
    {
      "fieldName": "organizationName",
      "fieldValue": "123456",
      "conditionalType": 0
    }
  ],
  "pageIndex": 1,
  "pageSize": 15
}

响应body：

字段名	类型	说明
`data`	`array`	分页数据
`data.userId`	`string`	用户 ID
`data.account`	`string`	用户名
`data.accountId`	`boolean`	账号 ID
`data.realName`	`string`	真实姓名
`data.organizationName`	`string`	组织名称
`data.organizationId`	`string`	组织ID
`data.organizationParentId`	`string`	父级组织ID
`data.Email`	`string`	邮箱
`data.Sort`	`number`	排序号
`data.External`	`boolean`	内外部用户标识 false: 内部用户, true: 外部用户
`pageIndex`	`number`	当前页码
`pageSize`	`number`	页码大小
`totalCount`	`number`	总条数
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
    "data": [
        {
            "account": "user1",
            "accountId": "123456",
            "userId": "123456",
            "realName": "user1",
            "organizationName": "org1",
            "organizationId": "123456",
            "external": false,
            "organizationParentId": "12345",
            "sort": 1,
            "email": ""
        }
    ],
    "pageSize": 15,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": null
}

添加用户组织关系

接口地址：v1/openapi/organization/relationship
**请求方式: **post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`organizationId`	是	`string`	无	组织Id
`userId`	是	`string`	无	用户Id
`sort`	否	`number`	0	排序号

请求示例：

curl --location 'http://localhost/v1/openapi/organization/relationship' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "organizationId": "123456",
    "userId": "12345"
}  '

响应body：

字段名	类型	说明
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": ""
}

删除用户组织关系

接口地址：v1/openapi/organization/relationship
**请求方式: **delete
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`organizationIds`	是	`array`	无	组织Id
`userIds`	是	`array`	无	用户Id

请求示例：

curl --location 'http://localhost/v1/openapi/organization/relationship' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "organizationIds": ["123456"],
    "userIds": ["12345"]
}  '

响应body：

字段名	类型	说明
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
	"success": true,
	"msg": ""
}

查询组织下的用户(分页)

接口地址：v1/openapi/organization/getUserPages
**请求方式: **post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：application/json
请求body：

参数名称	必填	类型	默认值	参数解释
`orderField`	是	`string`	无	用于排序的字段,Id含有时间信息,可以用id排序来用作创建时间的排序
`orderType`	是	`string`	无	排序类型, asc: 正序, desc: 倒序
`conditions`	否	`array`	无	查询条件,传多个时相互之间是 and 的关系
`conditions.fieldName`	否	`string`	无	查询条件的名称,必须至少传入OrganizationId或OrganizationCode作为筛选条件
`conditions.fieldValue`	否	`string`	无	查询条件的值
`conditions.conditionalType`	否	`number`	0	查询条件的比较类型 0: 精确匹配, 1: 模糊匹配, 2: 大于, 3: 大于等于, 4:小于, 5: 小于等于, 6: 包含(in), 7: 不包含(not in), 8: 向左模糊匹配, 9:向右模糊匹配, 10: 不等于, 11: nullOrEmpty, 12: 不为空, 13: notLike
`pageIndex`	是	`number`	无	页码
`pageSize`	是	`number`	无	每页的数量

请求示例：

curl --location 'http://localhost/v1/openapi/user/pageList' \
--header 'Authorization: openapi {access_token}' \
{
  "orderField": "id",
  "orderType": "desc",
  "conditions": [
    {
      "fieldName": "OrganizationCode",
      "fieldValue": "org1",
      "conditionalType": 0
    }
  ],
  "pageIndex": 1,
  "pageSize": 15
}

响应body：

字段名	类型	说明
`data`	`array`	分页数据
`data.id`	`string`	用户 ID
`data.account`	`string`	用户名
`data.name`	`string`	真实姓名
`data.ownerMainDepartment`	`string`	用户主岗
`data.sort`	`number`	排序号
`data.status`	`boolean`	用户启用状态
`data.create`	`datetime`	用户的创建时间
`pageIndex`	`number`	当前页码
`pageSize`	`number`	页码大小
`totalCount`	`number`	总条数
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
    "data": [
        {
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
    ],
    "pageSize": 15,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": null
}

聊天

向Copilot发送消息

接口地址：/openapi/chat/expert
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求body：

参数名称	必填	类型	参数解释
expertCode	是	string	SERVICEME系统中的Copilot code（见SERVICEME系统）
content	是	string	提问内容
sessionId	否	string	会话id，代表一个聊天上下文，传null表示开启新会话，新会话的id会在接口响应中返回，从第二次问答开始需要携带上一次返回的session id继续
stream	否	boolean	是否开启流式（true：开；false：关）,默认不会开启
includeThought	否	boolean	是否需要在返回内容里包含想法（true：包含；false：不包含）

**问答code如何获得？**请见下图：

请求示例：

curl --location 'https://localhost/vee/openapi/chat/expert' \
--header 'Authorization: openapi {access_token}' \
--header 'Content-Type: application/json' \
--data '{
    "expertCode": "CHATES",
    "content": "加班申请",
    "sessionId": null,
    "stream": false,
    "includeThought": true
}'

响应body：

参数	参数二级	参数三级	参数四级	类型	参数解释
data				object	响应数据
	chatRecordId			string	会话记录id
	sessionId			string	会话id
	content			string	文本类型的回答信息
	medias			object	媒体类型的回答信息数组（图片和文件等）
		type		string	image：图片；file：文件
		name		string	名称
	suggestionQuestions			array string	建议问题
	thoughts			array	想法
		thought		string	想法内容
		pluginName		string	插件名称
		elapsedTime		object	插件耗时信息
			model	float	模型耗时
			action	float	动作耗时
			total	float	总耗时
		state		string	状态（success：成功）
	finish_reason			string	是否结束回答，当值为stop时表示结束，回答过程中值为null
success				boolean	是否成功
msg				string	当success为false时，该处有值，会有部分错误提示

非流式响应示例：

{
    "data": {
        "chatRecordId": "4299234148041625600",
        "sessionId": "4292755814873047040",
        "content": "团队负责人发布工作任务，明确完成节点和验收标准等，员工与上级达成一致后方可加班。加班完毕后由员工在工时系统填写加班工时，在系统提交加班流程，备注内容需清楚列明加班任务，在工作地记录完整的上下班打卡记录，团队负责人/上级验收加班成果后，批准加班申请流程。HR确认打卡记录后，核算调休假额度。",
        "medias": [
			{
        		"type": "image",
                "name": null,
                "url":"http://localhost:3978/openapi/chat/media/image/FE680A9CCFB1B56E80737FB28562DC33F4A37DEF52A65F046464788B83E0BE77"
            },
            {
        		"type": "file",
                "name": "答案参考文件.pdf",
                "url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"
            },
        ],
        "suggestionQuestions": [],
        "thoughts": [
            {
                "thought": "为了回答这个问题，我需要查询知识库中的相关信息。",
                "pluginName": "Search Knowledgebase",
                "elapsedTime": {
                    "model": 3612.4722,
                    "action": 689.5891,
                    "total": 4302.0613
                },
                "state": "success"
            }
        ],
        "finish_reason": "stop"
    },
    "success": true,
    "msg": ""
}

流式响应示例：

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[],"suggestionQuestions":[],"thoughts":[{"thought":"为了回答这个问题，我需要查询知识库中的相关信息。","pluginName":"Search Knowledgebase","elapsedTime":{"model": 3612.4722,"action": 689.5891,"total": 4302.0613},"state": "success"}],"finish_reason":null},"success":true,"msg":""}

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"团队负责人发布工作任务，明确完成节点和验收标准等，员工与上级达成一致后方可加班。加班完毕后由员工在工时系统填写加班工时，在系统提交加班流程，备注内容需清楚列明加班任务，在工作地记录完整的上下班打卡记录，团队负责人/上级验收加班成果后，批准加班申请流程。HR确认打卡记录后，核算调休假额度。","medias":[],"suggestionQuestions":[],"thoughts":[],"finish_reason":null},"success":true,"msg":""}

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[{"type":"image","name":null,"url":"http://localhost:3978/openapi/chat/media/image/FE680A9CCFB1B56E80737FB28562DC33F4A37DEF52A65F046464788B83E0BE77"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":null},"success":true,"msg":""}

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[{"type":"file","name":"答案参考文件.pdf","url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":"stop"},"success":true,"msg":""}

获取对话的参考资料

接口地址：/openapi/chat/record/{chatRecordId}/reference
请求方式：get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求url传参：

参数名称	必填	类型	参数解释
chatRecordId	是	string	从问答接口返回的chatRecordId字段里取值

请求示例：

curl --location 'http://localhost/openapi/chat/record/4299234148041625600/reference' \
--header 'Authorization: openapi {access_token}'

响应body：

参数名称	参数二级	类型	参数解释
data		object array	响应数据
	title	string	标题
	content	string	该会话记录引用的片段内容
	score	float	相关程度（0到1，越接近1表示越相关）
	url	string	链接（暂时只有文件类型的引用有链接）
	type	string	类型枚举：document(文档)、image(图片)、QnA、other
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": [
        {
            "title": "公司行政制度.pdf",
            "content": "片段一 ......",
            "score": 0.95,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        },
        {
            "title": "公司行政制度.pdf",
            "content": "片段二 ......",
            "score": 0.81,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        },
        {
            "title": "公司行政制度.pdf",
            "content": "片段三 ......",
            "score": 0.76,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        }
    ],
    "success": true,
    "msg": ""
}

文件空间

单文件上传

接口地址：v1/openapi/workspace/file/upload
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：form-data
请求body：

参数名称	必填	类型	参数解释
workspace	是	string	文件空间
file	是	file	文件（单个）
eponymousCover	否	bool	如果存在同名文件是否要覆盖（默认不覆盖）

请求示例：

curl --location 'http://localhost/v1/openapi/workspace/file/upload' \
--header 'Authorization: openapi {access_token}' \
--form 'workspace="测试空间"' \
--form 'file=@"/C:/test.doc"' \
--form 'eponymousCover="false"'

响应body：

参数名称	参数二级	类型	参数解释
data		object	响应数据
	fileId	string	文件id
	fileName	string	文件名称
	uploader	string	上传人
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": {
        "fileId": "4345229404125790208",
        "fileName": "test.doc",
        "uploader": "test@serviceme.com"
    },
    "success": true,
    "msg": ""
}

多文件上传

提交文件

接口地址：v1/openapi/workspace/file/upload/batchSubmit
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

Content Type：form-data
请求body：

参数名称	必填	类型	参数解释
workspace	是	string	文件空间
files	是	file	文件（多个）
eponymousCover	否	bool	如果存在同名文件是否要覆盖（默认不覆盖）

请求示例：

curl --location 'http://localhost/v1/openapi/workspace/file/upload/batchSubmit' \
--header 'Authorization: openapi {access_token}' \
--form 'workspace="测试空间"' \
--form 'files=@"/C:/test1.doc"' \
--form 'files=@"/C:/test2.docx"' \
--form 'eponymousCover="false"'

响应body：

参数名称	参数二级	类型	参数解释
data		object	响应数据
	stateId	string	上传的状态id，可以使用这个状态id不断轮询获得最新的上传结果
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": {
        "stateId": "4345229404125790208"
    },
    "success": true,
    "msg": ""
}

查询上传结果

接口地址：v1/openapi/workspace/file/upload/batchSubmit/{stateId}
请求方式：get
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求url传参：

参数名称	必填	类型	参数解释
stateId	是	string	多文件提交上传接口返回给你的那个stateId字段值

请求示例：

curl --location 'http://localhost/v1/openapi/workspace/file/upload/batchSubmit/4345227891722682368' \
--header 'Authorization: openapi {access_token}'

响应body：

参数名称	参数二级	类型	参数解释
data		object array	响应数据
	fileId	string	文件Id
	fileName	string	文件名
	state	string	状态枚举：underway（排队处理中）、success（成功）、fail（失败）
	uploader	string	上传人
	errorMsg	string	当状态为 fail 时，这里会存放导致失败的原因
	finishTime	string	文件处理完成的时间
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": [
        {
            "fileId": "4345227925730099200",
            "fileName": "test1.doc",
            "state": "success",
            "uploader": "test@serviceme.com",
            "errorMsg": "",
            "finishTime": "2024-08-17T05:04:30.0128596Z"
        },
        {
            "fileId": "4345227924266287104",
            "fileName": "test2.docx",
            "state": "success",
            "uploader": "test@serviceme.com",
            "errorMsg": "",
            "finishTime": "2024-08-17T05:04:29.7952274Z"
        }
    ],
    "success": true,
    "msg": ""
}

QnA 创建

接口地址：v1/openapi/workspace/qna/create
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求body：

参数名称	参数二级	必填	类型	参数解释
workspace		是	string	文件空间
questions		是	string array	问题数组，可多个
answer		是	string	答案
metadatas		否	object array	元数据
	typeCode	是	string	元数据类型
	content	是	string	内容

请求示例：

curl --location 'http://localhost/v1/openapi/workspace/qna/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: openapi {access_token}' \
--data '{
    "questions": [
        "测试问题"
    ],
    "answer": "测试答案",
    "workspace": "测试空间",
    "metadatas": [
        {
            "typeCode": "Document type",
            "content": "测试元数据"
        }
    ]
}'

响应body：

参数名称	类型	参数解释
success	boolean	是否成功
msg	string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "success": true,
    "msg": ""
}

查询文件

接口地址：v1/openapi/workspace/file
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求body：

参数名称	必填	类型	参数解释
workspace	是	string	文件空间
pageIndex	否	number	页码，默认第一页
pageSize	否	number	获取数量，默认10条

请求示例：

curl --location 'http://localhost/v1/openapi/workspace/file' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "workspace": "测试空间",
    "pageIndex": 1,
    "pageSize": 10
}'

响应body：

参数名称	参数二级	参数三级	类型	参数解释
data			object array	响应数据
	id		string	文件id
	name		string	文件名
	size		number	文件大小，单位字节
	description		string	描述
	fullPath		string	文件路径
	tags		object array	文件标签信息
		id	string	标签id
		value	string	标签内容
	chunkingState		string	文件索引状态：waiting(等候处理中)、success(成功)、fail(失败)、underway(进行中)
	previewState		string	文件预览状态：waiting(等候处理中)、success(成功)、fail(失败)、underway(进行中)
	fileCanPreview		boolean	文件是否可预览，true：可以；false：不可以
	previewUrl		string	文件预览地址
	createdByRealName		string	文件创建者名称
	createdByAccount		string	文件创建者账号
	created		datetime	文件创建时间
	modifiedByRealName		string	文件编辑者名称
	modifiedByAccount		string	文件编辑者账号
	modified		datetime	文件编辑时间
success			boolean	是否成功
msg			string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": [
        {
            "id": "4339013367831199744",
            "name": "test.docx",
            "size": 15113,
            "description": null,
            "fullPath": "/",
            "tags": [],
            "chunkingState": "success",
            "previewState": "success",
            "fileCanPreview": true,
            "previewUrl": "http://localhost.com/#/share/preview?fileId=4339013367831199744&objectType=2&previewType=file&mode=login",
            "createdByRealName": "test",
            "createdByAccount": "test",
            "created": "2024-07-31T01:30:02.88",
            "modifiedByRealName": "test",
            "modifiedByAccount": "test",
            "modified": "2024-07-31T01:30:02.88"
        }
    ],
    "pageSize": 10,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": ""
}

查询文件片段

接口地址：v1/openapi/workspace/file/chunk
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求body：

参数名称	必填	类型	参数解释
fileId	是	string	文件id
imageFormat	否	string	图片格式，markdown或html，默认使用markdown输出
pageIndex	否	number	页码，默认第一页
pageSize	否	number	获取数量，默认10条

请求示例：

curl --location 'http://localhost/v1/openapi/workspace/file/chunk' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "fileId": "4344174161665458176",
    "imageFormat": "html",
    "pageIndex": 1,
    "pageSize": 10
}'

响应body：

参数名称	参数二级	类型	参数解释
data		object array	响应数据
	id	string	片段id
	content	string	片段内容
success		boolean	是否成功
msg		string	当success为false时，该处有值，会有部分错误提示

响应示例：

{
    "data": [
        {
            "id": "4339013367831199744",
            "content": "test"
        }
    ],
    "pageSize": 10,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": ""
}

RAG

接口地址：/v1/openapi/rag
请求方式：post
请求header：

参数名称	必填	类型	参数解释
Authorization	是	string	填SERVICEME access token，值填写格式：openapi `{access_token}`

请求body：

参数名	类型	必填	默认值	说明
`query`	`string`	否	无	需要检索的问题或内容。和Keywords参数不能都为`null`。
`keywords`	`string`	否	无	关键词，多个关键词用 `\|` 分隔。和Query参数不能都为`null`。为`null`时会根据需要提取关键字，不为空时直接使用传入的关键字。
`workspaces`	`array`	否	无	本次 RAG 将要检索的文件空间名称或Id。如果传了这个值，则会只从这几个空间里检索
`ragObject`	`RagObject`	是	`0`	RAG 对象类型，枚举值（详见 RagObject 枚举）。
`topk`	`number`	是	无	返回结果的数量。
`minSimilarity`	`double`	否	`0.8`	最低相似度，范围为 `[0, 1]`。
`metadataFilter`	`array`	否	无	要使用的元数据过滤器类型。目前只支持default过滤器
`ragMode`	`SearchMode`	是	`0`	RAG 模式，枚举值（详见 SearchMode 枚举）。
`weights`	`object`	否	无	各路索引的RRF权重，仅在 `RagMode` 为 `Hybrid` 时有效。若为 `null` 则使用默认权重。
`reranker`	`string`	否	无	如果为 `null` 则不使用 `reranker`

请求示例：

curl --location 'http://localhost/v1/openapi/rag' \
--header 'Authorization: ••••••' \
--header 'Content-Type: application/json' \
--data '{  
    "query": "什么是人工智能？",  
    "keywords": "AI|机器学习",  
    "workspaces": ["workspace1", "workspace2"],  
    "ragObject": 0,  
    "topk": 3,  
    "minSimilarity": 0.8,  
    "metadataFilter": ["default"],  
    "ragMode": 1,  
    "weights": {  
        "Embedding": 0.9,  
        "FullText": 0.8  
    },  
    "reranker": "default"  
}  '

响应body：

字段名	类型	说明
`data`	`object`	响应数据对象，包含搜索结果和搜索 ID 等信息。
`data.results`	`array`	搜索结果列表，每个元素是一个包含片段信息的对象。
`data.results[].chunkId`	`string`	片段 ID
`data.results[].fileId`	`string`	片段所属的文件 ID
`data.results[].fileName`	`string`	片段所属的文件名
`data.results[].content`	`string`	片段内容
`data.results[].metadata`	`json`	片段元数据
`data.results[].url`	`string`	片段的 URL 地址（如果有）
`data.results[].searchScore`	`double`	近似度得分
`data.results[].rrfScore`	`double`	RRF 得分
`data.results[].rerankScore`	`double`	重排得分
`data.results[].workspaceId`	`string`	文件所属的文件空间 ID
`data.results[].workspaceName`	`string`	文件所属的文件空间名称
`data.searchId`	`string`	本次搜索操作的唯一标识
`success`	`boolean`	请求是否成功
`msg`	`string`	请求返回的消息（如果有）

响应示例：

{
    "data": {
        "results": [
            {
                "chunkId": "4422442085118906369",
                "fileId": "4417076017114382336",
                "fileName": "文件1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "https://……",
                    "FileName": "文件1.pdf",
                    "WorkspaceName": "workspace1",
                    "FileId": "4417076017114382336",
                    "FilePath": "/",
                    "Created": "2025-03-03T11:23:08.803",
                    "Size": "1160594"
                },
                "url": "https://……",
                "searchScore": 0.153852914388501,
                "rrfScore": 0.8768274796195331,
                "rerankScore": 0.0,
                "workspaceId": "4417069258022846464",
                "workspaceName": ""
            },
            {
                "chunkId": "4422442085114712073",
                "fileId": "4417076017114382336",
                "fileName": "文件1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "https://……",
                    "FileName": "文件1.pdf",
                    "WorkspaceName": "workspace1",
                    "FileId": "4417076017114382336",
                    "FilePath": "/",
                    "Created": "2025-03-03T11:23:08.803",
                    "Size": "1160594"
                },
                "url": "https://……",
                "searchScore": 0.152822583517241,
                "rrfScore": 0.8670604574184315,
                "rerankScore": 0.0,
                "workspaceId": "4417069258022846464",
                "workspaceName": ""
            },
            {
                "chunkId": "4422442085114712071",
                "fileId": "4417076017114382336",
                "fileName": "文件1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "……",
                    "FileName": "文件1.pdf",
                    "WorkspaceName": "workspace1",
                    "FileId": "4417076017114382336",
                    "FilePath": "/",
                    "Created": "2025-03-03T11:23:08.803",
                    "Size": "1160594"
                },
                "url": "……",
                "searchScore": 0.153708375384407,
                "rrfScore": 0.8661891817471927,
                "rerankScore": 0.0,
                "workspaceId": "4417069258022846464",
                "workspaceName": ""
            }
        ],
        "searchId": "4423568945336811520"
    },
    "success": true,
    "msg": ""
}

枚举类型

RagObject 枚举

枚举值	枚举数字	说明
`Both`	0	同时检索 Q&A 和文档内容。
`Qna`	1	仅检索 Q&A 内容。
`Doc`	2	仅检索文档内容。

SearchMode 枚举

枚举值	枚举数字	说明
`Hybrid`	1	混合检索模式，结合嵌入向量和全文检索。
`Embedding`	2	仅基于嵌入向量的检索模式。
`FullText`	3	仅基于全文检索的检索模式。

Rerank模型配置方式 以cohere-rerank-v3.5模型的配置方式为例：

INSERT INTO dbo.AI_LLM (Id,ModelName,TokenCount,Config,Enable,[Default],Display,DisplayName) VALUES
(4183721090264072898,N'rerank-v3.5',255454,N'{"RerankerName":"cohere","Uri":"https://域名/v2/rerank","Token":"bearer token"}',1,0,0,N'cohere-rerank-v3.5');

注意：如果使用的是Cohere官网的API，Token字段的值为bearer token，如果使用的是Azure AI Foundry的API，Token字段的值要去掉bearer。

概述​

身份认证方式​

用户AAD认证​

客户端与用户账户认证​

用户​

添加用户（支持批量）​

修改用户​

删除用户​

启用用户​

禁用用户​

启用/禁用用户（支持批量）​

获取用户列表（分页）​

获取用户信息​

获取当前登录用户的信息​

获取当前登录用户的角色​

获取用户已关联的角色​

用户角色关系修改​

组织​

添加组织​

更新组织​

删除组织​

获取树状组织结构​

根据用户组织关系获取用户（分页）​

添加用户组织关系​

删除用户组织关系​

查询组织下的用户(分页)​

聊天​

向Copilot发送消息​

获取对话的参考资料​

文件空间​

单文件上传​

多文件上传​

提交文件​

查询上传结果​

QnA 创建​

查询文件​

查询文件片段​

RAG​

概述