文件知识API对接 - Udesk

查询文件列表

GET /sdk/knowledgeBases/{knowledgeBaseId:^[1-9]\d*$}/materialRepositorys

请求参数

名称	位置	类型	必选	说明
knowledgeBaseId:^[1-9]\d*$	path	string	是	none
knowledgeBaseId	query	integer	是	知识空间id
categoryId	query	integer	否	分类id
name	query	string	否	文件名称（模糊匹配）
status	query	integer	否	知识状态：1-已发布，4-未生效
accessLevel	query	integer	否	访问权限，0：可对外，1：仅内部
pageSize	query	integer	是	none
pageNum	query	integer	是	none
Content-Type	header	string	否	none

请求示例

curl --location 'https://kcs.t1.in.tryudesk.com/api/sdk/knowledgeBases/281/materialRepositorys?knowledgeBaseId=281' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrbSIsImNvbXBhbnlJZCI6MzAwMDAwMDIsImFwcElkIjoiNDY3Yzk4N2EtMjk0YS00NDk2LTRhZDctYzIyM2Y4ZDdiZjhmIiwiaXNzIjoia20iLCJ1c2VyVHlwZSI6MiwiZXhwIjoxNzYyMzA4NDg0LCJpYXQiOjE3NjIzMDU0ODQsInVzZXJJZCI6Mn0.puGWiu8FXVA9gqkHq5WB8F5mddZyk9EjzyEnCJMfZGf-EG-x8nZO0whRO-w0Vzr4smoEMYQlXhgwQvYxVH69xFQrLwpqQKVhq1pDjzoT46OTTAEGKMblFxWvf1FUEyQjr7yoqqBlxBcXOcDSjaohxDrRHZBJse0EMo8jijHPqKA'

返回示例

{
    "succeed": true,
    "code": 200,
    "bizCode": "000000",
    "message": "OK",
    "visible": false,
    "paging": {
        "pageNum": 1,
        "pageSize": 20,
        "total": 1
    },
    "data": [
        {
            "id": 101198,
            "createUserId": 2,
            "createUserUsername": "Admin123456",
            "createTime": "2025-09-18 16:47:36",
            "updateUserId": 2,
            "updateTime": "2025-11-04 15:26:12",
            "deleteFlag": 0,
            "categoryIdMultiple": [
                11913
            ],
            "knowledgeCreateBool": true,
            "knowledgeManageBool": true,
            "knowledgeBaseId": 281,
            "name": "ChatGPT 常见问题解答.docx",
            "url": "https://staging-udesk.oss-cn-beijing.aliyuncs.com/Data/30000002/9241aa18-acab-448d-8fe9-b234a3413f4c/ChatGPT 常见问题解答.docx",
            "encodingUrl": "https://staging-udesk.oss-cn-beijing.aliyuncs.com/Data/30000002/9241aa18-acab-448d-8fe9-b234a3413f4c/ChatGPT%20%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E8%A7%A3%E7%AD%94.docx",
            "previewUrl": "https://espreview.s4.udesk.cn/onlinePreview?url=RDZDQUNBQ0VDRDg0OTE5MUNEQ0FERkQ5RDdEMEQ5OTNDQkRBREJDREQ1OTBEMUNEQ0Q5M0RERDA5M0RDREJEN0Q0RDdEMEQ5OTBERkQyRDdDN0NCRDBERENEOTBEREQxRDM5MUZBREZDQURGOTE4RDhFOEU4RThFOEU4RThDOTE4NzhDOEE4RkRGREY4Rjg2OTNERkREREZEQzkzOEE4QTg2REE5Mzg2RDhEQjg3OTNEQzhDOEQ4QURGOEQ4QThGOEREODhBREQ5MUZERDZERkNBRjlFRUVBOUU1QjA2MDY1NjE5M0Y1NzI5MTA1NzFDMjY1NjE5MUQ1OTEzMkE5MERBRDFEREM2ODFEREQxRDBDQURCRDBDQTgz",
            "uid": "9570882d-a3ba-42ee-936d-483ffd828d5d",
            "type": "ATTACHMENT",
            "source": 2,
            "size": 47777,
            "shareOutside": false,
            "shareFlag": true,
            "downloadFlag": true,
            "generateOutlineStatus": 0,
            "sdkSendFlag": 0,
            "sdkUseFlag": 0,
            "tags": [
                {
                    "id": 142,
                    "createUserId": 2,
                    "createTime": "2025-11-04 14:57:23",
                    "updateUserId": 2,
                    "updateTime": "2025-11-04 14:57:23",
                    "deleteFlag": 0,
                    "company": {
                        "id": 30000002,
                        "deleteFlag": 0
                    },
                    "knowledgeBaseId": 281,
                    "knowledgeId": 101198,
                    "tagId": 782,
                    "tagName": "标签-带固定时长"
                }
            ],
            "langCode": "ZH-CN",
            "availableTimeType": 1,
            "startTime": "2025-11-04 00:00:00",
            "endTime": "2025-11-24 23:59:59",
            "accessLevel": 0,
            "favoriteFlag": 0,
            "browseCount": 0,
            "valid": true,
            "status": 1,
            "uagentSyncStatus": 1,
            "uagentTaskId": "f862e875-13c9-4865-94a8-877cd1a976bf",
            "uagentLastSyncTime": "2025-11-04 15:29:25",
            "uagentSyncRetryTimes": 0
        }
    ]
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» succeed	boolean	true	none	none
» code	integer	true	none	none
» bizCode	string	true	none	none
» message	string	true	none	none
» visible	boolean	true	none	none
» paging	object	true	none	none
»» pageNum	integer	true	none	none
»» pageSize	integer	true	none	none
»» total	integer	true	none	none
» data	[object]	true	none	none
»» id	integer	false	none	文件id
»» createUserId	integer	false	none	创建用户id
»» createUserUsername	integer	false	none	创建用户名称
»» createTime	string	false	none	创建时间
»» updateUserId	string	false	none	更新用户id
»» updateTime	string	true	none	更新时间
»» deleteFlag	string	false	none	删除标识
»» categoryIdMultiple	string	false	none	分类id
»» knowledgeCreateBool	string	false	none	权限标志
»» knowledgeManageBool	string	true	none	权限标志
»» knowledgeBaseId	string	true	none	知识空间id
»» name	integer	true	none	文件名称
»» url	integer	true	none	素材地址
»» encodingUrl	integer	true	none	文件存储地址
»» previewUrl	integer	true	none	文件预览地址
»» uid	integer	true	none	文件uid
»» type	integer	true	none	文件类型
»» source	integer	true	none	1Q&A同步 2手动上传，3：SG工单，4：UD工单
»» size	integer	true	none	文件大小
»» shareOutside	boolean	true	none	能否分享到外部
»» shareFlag	boolean	true	none	是否能分享
»» downloadFlag	boolean	true	none	是否能下载
»» generateOutlineStatus	integer	true	none	生成目录状态
»» sdkSendFlag	integer	true	none	SDK发送开关
»» sdkUseFlag	integer	true	none	SDK使用开关
»» tags	[object]	true	none	标签
»»» id	integer	true	none	知识绑定标签id
»»» createUserId	integer	true	none	创建人id
»»» createTime	string	true	none	创建时间
»»» updateUserId	integer	true	none	更新人id
»»» updateTime	string	true	none	更新时间
»»» deleteFlag	integer	true	none	删除标志
»»» company	{object}	true	none	租户信息
»»»» id	integer	true	none	租户id
»»»» deleteFlag	integer	true	none	删除标志
»»» knowledgeBaseId	integer	true	none	知识空间id
»»» knowledgeId	integer	true	none	知识id
»»» tagId	integer	true	none	标签id
»»» tagName	string	true	none	标签名称
»» langCode	string	true	none	语言
»» availableTimeType	integer	true	none	生效类型，0-永久生效，1-固定日期生效
»» startTime	string	true	none	生效开始时间
»» endTime	string	true	none	生效结束时间
»» accessLevel	integer	true	none	访问权限，0：可对外，1：仅内部
»» favoriteFlag	integer	true	none	收藏个数
»» browseCount	integer	true	none	观看量
»» valid	boolean	true	none	是否生效
»» status	integer	true	none	知识状态
»» uagentSyncStatus	integer	true	none	同步Uagent任务状态
»» uagentTaskId	string	true	none	任务id
»» uagentLastSyncTime	string	true	none	最后同步时间
»» uagentSyncRetryTimes	integer	true	none	同步重试次数

上传文件第一步：获取沃丰oss签名url

GET /oss/efficiency

请求参数

名称	位置	类型	必选	说明
knowledgeBaseId	query	integer	是	知识空间id
dataType	query	string	是	文件类型，document，
filename	query	string	是	文件名称
verify	query	integer	是	固定传1
Content-Type	header	string	否	none

请求示例

curl  'https://kcs.t1.in.tryudesk.com/api/oss/efficiency?filename=ChatGPT%20%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E8%A7%A3%E7%AD%94.docx&knowledgeBaseId=193&verify=1&dataType=document' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrbSIsImNvbXBhbnlJZCI6MzAwMDAwMDIsImFwcElkIjoiNDY3Yzk4N2EtMjk0YS00NDk2LTRhZDctYzIyM2Y4ZDdiZjhmIiwiaXNzIjoia20iLCJ1c2VyVHlwZSI6MiwiZXhwIjoxNzYyMzA4NDg0LCJpYXQiOjE3NjIzMDU0ODQsInVzZXJJZCI6Mn0.puGWiu8FXVA9gqkHq5WB8F5mddZyk9EjzyEnCJMfZGf-EG-x8nZO0whRO-w0Vzr4smoEMYQlXhgwQvYxVH69xFQrLwpqQKVhq1pDjzoT46OTTAEGKMblFxWvf1FUEyQjr7yoqqBlxBcXOcDSjaohxDrRHZBJse0EMo8jijHPqKA'

返回示例

{
  "succeed": true,
  "code": 200,
  "bizCode": "000000",
  "message": "OK",
  "visible": false,
  "data": {
    "host": "https://staging-udesk.oss-cn-beijing.aliyuncs.com",
    "bucket": "staging-udesk",
    "dir": "Data",
    "key": "Data/30000002/28a99648-ec66-4883-bced-a1f91a5f5735/ChatGPT 常见问题解答.docx",
    "region": "oss-cn-beijing",
    "temporaryId": "STS.NY9njknYUtg8jaa5S9hb2EJCr",
    "policy": "9T8zvs6VmgSTX6KhdipkPWXHVccTNQHMneBN5jYfXDrf",
    "signature": "CAISuQJ1q6Ft5B2yfSjIr5qMJdDfg4Z0w6XTaEfQ0VNsZO0eqo/okDz2IHhMeHZrBeAevv4xlWFX6PcclqpwQIQd9dVSiwYrvPpt6gqET9frma7ctM4p6vCMHWyUFGSIvqv7aPn4S9XwY+qkb0u++AZ43br9c0fJPTXnS+rr76RqddMKRAK1QCNbDdNNXGtYpdQdKGHaOITGUHeooBKJVRA55VIt0D8ktvrjk5DM0HeE0g2mkN1yjp/qP52pY/NrOJpCSNqv1IR0DPGZiHIPsEQarPcs0v0VpmmW4Mv+GEVKphaNKK/T6cZ/mrjLzy6888SuxdmLdp0Q0oS7/+yfQMZUPOLiaS+Wggz0dQd4vCcN4sp4FNC1cj2Gucv0FeK+iChvWklQT3gRGNFMRDIOT3JlJF7UQrDqdM2XCm/LGoABetv44Kexvrek/PvCA2Jlna0KLDGkpBGSNwYGxTHxAARMgqfLzskkCBaVj9VEzoE7r8fnR5b10k7W7FKDfQL2iQ4zbqPUxEv2j22j5X4nZpkxRo+hduBINdOVqDXhoZ9BVjBnv5EnmAPoXNeekd4c/55c0/Vsq9nd+kF4rxkn6EUgAA==",
    "storageType": "oss"
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» succeed	boolean	true	none	none
» code	integer	true	none	none
» bizCode	string	true	none	none
» message	string	true	none	none
» visible	boolean	true	none	none
» data	[object]	true	none	none
»» host	string	true	none	none
»» bucket	string	true	none	none
»» dir	string	true	none	none
»» key	string	true	none	none
»» region	string	true	none	none
»» temporaryId	string	true	none	none
»» policy	string	true	none	none
»» signature	string	true	none	none
»» storageType	string	true	none	固定填oss

上传文件第二步：上传沃丰oss签名url

PUT /域名/第一步获取的key

请求示例

curl  'https://staging-udesk.oss-cn-beijing.aliyuncs.com/Data/30000002/28a99648-ec66-4883-bced-a1f91a5f5735/ChatGPT%20%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E8%A7%A3%E7%AD%94.docx' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrbSIsImNvbXBhbnlJZCI6MzAwMDAwMDIsImFwcElkIjoiNDY3Yzk4N2EtMjk0YS00NDk2LTRhZDctYzIyM2Y4ZDdiZjhmIiwiaXNzIjoia20iLCJ1c2VyVHlwZSI6MiwiZXhwIjoxNzYyMzA4NDg0LCJpYXQiOjE3NjIzMDU0ODQsInVzZXJJZCI6Mn0.puGWiu8FXVA9gqkHq5WB8F5mddZyk9EjzyEnCJMfZGf-EG-x8nZO0whRO-w0Vzr4smoEMYQlXhgwQvYxVH69xFQrLwpqQKVhq1pDjzoT46OTTAEGKMblFxWvf1FUEyQjr7yoqqBlxBcXOcDSjaohxDrRHZBJse0EMo8jijHPqKA'

请求参数

名称	位置	类型	必选	说明
key	query	string	是	取上传第一步的formData.key
Content-Type	header	string	否	none

返回示例

200 Response

{}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

无

上传文件第三步：保存文件

POST /sdk/knowledgeBases/{knowledgeBaseId:^[1-9]\d*$}/materialRepositorys/batchSave

Body 请求参数

{
  "materials": [
    {
      "key": "Data/30000002/28a99648-ec66-4883-bced-a1f91a5f5735/ChatGPT 常见问题解答.docx",
      "url": "https://staging-udesk.oss-cn-beijing.aliyuncs.com/Data/30000002/28a99648-ec66-4883-bced-a1f91a5f5735/ChatGPT 常见问题解答.docx",
      "name": "ChatGPT 常见问题解答.docx",
      "percent": 100,
      "size": 47777,
      "status": 1,
      "uid": "4700e785-3fb0-4849-98b8-c99055a0df8b"
    }
  ],
  "knowledgeBaseId": "193",
  "categoryIdList": [
    11192
  ],
  "langCode": "ZH-CN",
  "tags": [],
  "accessLevel": 0,
  "availableTimeType": 0
}

请求参数

名称	位置	类型	必选	说明
knowledgeBaseId:^[1-9]\d*$	path	string	是	none
knowledgeBaseId	query	integer	是	知识空间id
» categoryIdList	body	[string]	是	分类id集合
» materials	body	[object]	是	文件对象集合
»» key	body	string	是	取上传第一步的formData.key
»» name	body	string	是	文件名称
»» percent	body	string	是	百分比
»» size	body	integer	是	文件大小
»» status	body	integer	是	文件状态，固定传1发布
»» uid	body	string	是	取上传第二步返回参数
»» url	body	string	是	取上传第二步返回参数
» langCode	body	string	是	none
» tags	body	[object]	是	标签
» accessLevel	body	integer	是	访问权限，0：可对外，1：仅内部
» availableTimeType	body	integer	是	none

请求示例

curl  'https://kcs.t1.in.tryudesk.com/api/sdk/knowledgeBases/193/materialRepositorys/batchSave' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrbSIsImNvbXBhbnlJZCI6MzAwMDAwMDIsImFwcElkIjoiNDY3Yzk4N2EtMjk0YS00NDk2LTRhZDctYzIyM2Y4ZDdiZjhmIiwiaXNzIjoia20iLCJ1c2VyVHlwZSI6MiwiZXhwIjoxNzYyMzA4NDg0LCJpYXQiOjE3NjIzMDU0ODQsInVzZXJJZCI6Mn0.puGWiu8FXVA9gqkHq5WB8F5mddZyk9EjzyEnCJMfZGf-EG-x8nZO0whRO-w0Vzr4smoEMYQlXhgwQvYxVH69xFQrLwpqQKVhq1pDjzoT46OTTAEGKMblFxWvf1FUEyQjr7yoqqBlxBcXOcDSjaohxDrRHZBJse0EMo8jijHPqKA'

返回示例

200 Response

{
  "succeed": true,
  "code": 200,
  "bizCode": "000000",
  "message": "OK",
  "visible": false
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» succeed	boolean	true	none	none
» code	integer	true	none	none
» bizCode	string	true	none	none
» message	string	true	none	none
» visible	boolean	true	none	none

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

查询文件列表

请求参数

返回结果

返回数据结构

上传文件第一步：获取沃丰oss签名url

请求参数

返回结果

返回数据结构

上传文件第二步：上传沃丰oss签名url

请求参数

返回结果

返回数据结构

上传文件第三步：保存文件

请求参数

返回结果

返回数据结构

文档反馈