RestAPI接口文档
前置条件
本接口文档只提供AI调用相关的接口,AI接口调用有两种模式:
第一种模式是配合Chat2DB产品的数据源管理和AI数据集管理功能进行使用,由Chat2DB完成数据库表结构的管理。
第二种模式是自行管理自己的数据库表结构,只使用Chat2DB的自然语言转SQL功能。
第一种模式可以使用Chat2DB的自然语言转SQL,自然语言转报表等AI能力;第二种模式无法使用自然语言转报表的能力,其它AI能力均可使用。
具体使用流程分为以下几个步骤,第一种模式需要执行以下所有步骤,缺一不可;第二种模式只需要执行标注为(必须)的步骤;
第一步:创建数据源
在Chat2DB产品内创建数据源,创建数据源不提供rest接口,必须在产品内部使用产品交互界面进行创建,具体创建方式请参考创建MySql数据源 (opens in a new tab)
第二步:创建AI数据集
创建完数据源需要创建AI数据集才能将相关表结构同步给AI,此接口不提供rest接口,必须在产品内部使用产品交互界面进行创建,具体使用方式请参考AI数据集 (opens in a new tab)
创建完数据集之后拷贝数据集ID,AI数据集右击选择拷贝数据集ID
第三步:创建Rest接口调用的API key(必须)
创建ApiKey的接口不提供rest接口,必须在产品内部使用产品交互界面进行创建,参考下图点击头像,再点击创建ApiKey,创建完ApiKey之后请一定要在本地保存好,后续在本平台无法查看ApiKey的具体内容。
第四步:查询自然语言匹配到的表
拿到第二步创建的AI数据集ID和第三步创建的API key,输入自然语言,查询自然语言可能使用到的库表结构,具体API接口定义如下。
获取匹配表接口
接口地址:https://app.chat2db-ai.com/api/ai/rest/mapping_a (opens in a new tab)
接口方法:POST
认证方式
拿到第二步获取的API key,在请求接口中的Header添加Authorization,value值为Bearer API key
Header名称 | Header值 | 必选 | 说明 |
---|---|---|---|
Authorization | Bearer API key | 是 | 替换API key为你真实的API key |
请求参数
名称 | 类型 | 必选 | 说明 |
---|---|---|---|
input | string | 是 | 自然语言输入 |
tableSize | integer | 否 | 返回匹配的表数量,默认为10 |
dataSourceCollectionId | long | 否 | AI数据集ID,从第二步骤中获取 |
Body 请求参数样例
{
"input": "近3天的销售额",
"tableSize": "10",
"dataSourceCollectionId": 12
}
返回示例
返回结果为自然语言匹配到的数据库表结构列表,以下为返回结果json样例,data中的每一个对象即为一个表结构相关数据。
成功:
{
"success": true,
"errorCode": "",
"errorMessage": "",
"data": [
{
"dataSourceId": 0,
"databaseName": "",
"schemaName": "",
"tableName": "",
"tableSchema": ""
}
],
"traceId": "",
"errorDetail": "",
"solutionLink": ""
}
返回结果data中对象的属性
名称 | 类型 | 说明 |
---|---|---|
dataSourceId | integer | 数据源连接ID |
databaseName | string / null | 数据库名称 |
schemaName | string / null | schema名称 |
tableName | string | 表名 |
tableSchema | string | 表schema |
第五步:获取AI调用的token(必须)
传入数据库表结构以及AI类型,获取AI调用的token,此步骤中的数据库表结构可以是从第4步获取,也可以是用户自己管理的库表结构
获取AI调用的token
接口地址:https://api.chat2db-ai.com/api/ai/rest/prompt_a (opens in a new tab)
接口方法:POST
认证方式
拿到第三步获取的API key,在请求接口中的Header添加Authorization,value值为Bearer API key
Header名称 | Header值 | 必选 | 说明 |
---|---|---|---|
Authorization | Bearer API key | 是 | 替换API key为你真实的API key |
请求参数
名称 | 类型 | 必选 | 说明 |
---|---|---|---|
questionType | string | 是 | AI问题类型,可以传入以下枚举值,默认值为NL_2_SQL。使用第一种模式进行调用时可使用下面的所有AI功能,使用第二种模式进行调用时不可使用DASHBOARD_GENERATION。 // 自然语言转换成SQL NL_2_SQL // 解释SQL SQL_EXPLAIN //SQL优化 SQL_OPTIMIZER //报表生成 DASHBOARD_GENERATION |
input | string | 是 | 自然语言输入 |
databaseType | string | 否 | 数据库类型,当使用自然语言转SQL和报表生成时必传,否则只能生成mysql的方言 |
tableSchemas | RestPromptTableRequest / null | 否 | AI提问需要使用到的表结构对象RestPromptTableRequest列表,RestPromptTableRequest对象属性参考下面的表格 |
language | string / null | 否 | 值为EN/ZH,当值为ZH时返回中文,当值为EN时返回英文,默认值为ZH |
RestPromptTableRequest属性
名称 | 类型 | 必选 | 约束 | 说明 |
---|---|---|---|---|
dataSourceId | integer / null | 否 | 无 | 数据源连接ID |
databaseName | string / null | 否 | 无 | 数据库名称 |
schemaName | string / null | 否 | 无 | schema名称 |
tableName | string / null | 否 | 无 | 表名 |
tableSchema | string / null | 否 | 无 | 表schema |
Body 请求参数样例
{
"questionType": "NL_2_SQL",
"input": "近三个月销售额",
"databaseType": "MYSQL",
"tableSchemas": [
{
"dataSourceId": 0,
"databaseName": "数据库database名称",
"schemaName": "数据库schema名称",
"tableName": "表名",
"tableSchema": "表ddl"
}
],
"language": "ZH"
}
返回示例
成功:
{
"success": true,
"errorCode": "",
"errorMessage": "",
"errorDetail": "",
"solutionLink": "",
"data": {
"token": "API调用的token",
"apiParams": ""
},
"traceId": ""
}
返回结果属性
名称 | 类型 | 说明 |
---|---|---|
success | boolean / null | 是否成功 |
errorCode | string / null | 错误编码 |
errorMessage | string / null | 错误信息 |
errorDetail | string / null | error detail |
solutionLink | string / null | solution link |
data | RestPromptVO | AI调用Token信息,RestPromptVO对象属性请参考下表 |
traceId | string / null | traceId |
RestPromptVO属性
名称 | 类型 | 说明 |
---|---|---|
token | string / null | token |
apiParams | string / null | 请求参数附加信息 |
第六步:AI调用(必须)
通过第五步骤获取的token,即可进行AI接口调用,AI接口支持流式调用和非流式调用
AI调用接口
接口地址:https://api.chat2db-ai.com/api/ai/rest/chat_a (opens in a new tab)
接口方法:GET
认证方式
拿到第二步获取的API key,在请求接口中的Header添加Authorization,value值为Bearer API key
Header名称 | Header值 | 必选 | 说明 |
---|---|---|---|
Authorization | Bearer API key | 是 | 替换API key为你真实的API key |
请求参数
名称 | 类型 | 必选 | 说明 |
---|---|---|---|
token | string | 是 | 第五步骤中获取的token,因为此接口是GET方法,所以最好对token进行URLEncode,否则token中的特殊字符可能会丢失 |
stream | string | 是 | 是否流式,true为流式调用,false为非流式调用 |
timeout | long | 否 | 流式对话超时时间,单位为分钟,默认为30分钟 |
请求示例
https://api.chat2db-ai.com/api/ai/rest/chat_a?token=sd***as&stream=true&timeout=30
返回示例
本接口采用SseEmitter协议,SseEmitter每次返回结果对象示例如下,当输出结果为[DONE]时表示输出结束,否则每次输出一个数据对象。其中content的值即为AI输出的内容。
流式输出样例:
第一次输出
{
"role": "assistant",
"content": "SELECT "
}
第二次输出
{
"role": "assistant",
"content": "*\n"
}
第三次输出
{
"role": "assistant",
"content": "FROM "
}
第四次输出
{
"role": "assistant",
"content": "table_name;\n"
}
最后输出
[DONE]
非流式输出样例:
结果全部输出
{
"role": "assistant",
"content": "SELECT *\nFROM table_name;\n"
}
最后输出
[DONE]