1. 段落

1.1. 段落说明

1.1.1. 段落定义

段落是一个笔记中的一个代码片段，由多个语句构成，来共同完成特定的数据处理功能。段落中的代码支持SQL和HQL，但是同一个段落中代码只能是同一种的，不能混合包含不同类型的代码。

段落结构说明

字段	类型	描述
id	INTEGER	段落的 id
previousId	INTEGER	段落的前一个段落的 id
notebookId	INTEGER	段落所属的笔记的 id
createdAt	DATETIME	段落创建的时间
createdBy	INTEGER	段落创建用户的 id
updatedAt	DATETIME	段落最后修改的时间
updatedBy	INTEGER	段落最后修改用户的 id
code	STRING	段落的代码，每个语句用英文分号分隔
lang	STRING	段落的代码类型，见段落语言说明，默认是SQL
connectionId	INTEGER	段落的执行目标连接的 id
hsVersion	INTEGER	段落的编辑版本号，从0开始，修改段落提交的时候，需要带上修改前的版本号
options	OBJECT	段落配置信息
options.path	STRING 数组	段落的执行目标连接的路径（schema），有些数据源比如SQL Server有多层

段落语言说明

状态值	意义
SQL	native SQl，默认值，语法和具体的连接类型相关
HQL	HQL，衡石定义的通用语言

1.2. 接口说明

1.2.1. 新增段落

请求URL

POST /api/v1/notebooks/{notebookId}/paragraphs

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明

Request Body 参数

字段	类型	是否必须	描述
previousId	INTEGER	分情况	段落的前一个段落的 id。笔记的第一个段落的前一个段落id是null，可不填；后续的段落必须填
code	STRING	可选	段落的代码，每个语句用英文分号分隔，默认为空
lang	STRING	可选	段落的代码类型，见段落语言说明，默认是SQL
connectionId	INTEGER	可选	段落的执行目标连接的 id，默认为null，可以后续再修改
options	OBJECT	可选	段落配置信息
options.path	STRING 数组	可选	段落的执行目标连接的路径（schema），有些数据源比如SQL Server有多层

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见段落结构说明

接口示例: 创建笔记的第一个段落

POST /api/v1/notebooks/{notebookId}/paragraphs

{
}

{
    "code": 0,
    "data": {
        "id": 1,
        "notebookId": 1,
        "createdBy": 1,
        "createdAt": "2020-02-25 17:19:40",
        "updatedBy": 1,
        "updatedAt": "2020-02-25 17:19:40",
        "code": "",
        "lang": "SQL",
        "hsVersion": 0,
        "options": {},
        "isDelete": false
    },
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

接口示例: 创建笔记的第二个段落

POST /api/v1/notebooks/{notebookId}/paragraphs

{
    "previousId": 1
}

{
    "code": 0,
    "data": {
        "id": 2,
        "previousId": 1,
        "notebookId": 1,
        "createdBy": 1,
        "createdAt": "2020-02-26 17:19:40",
        "updatedBy": 1,
        "updatedAt": "2020-02-26 17:19:40",
        "code": "",
        "lang": "SQL",
        "hsVersion": 0,
        "options": {},
        "isDelete": false
    },
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

1.2.2. 删除段落

请求URL

DELETE /api/v1/notebooks/{notebookId}/paragraphs/{paragraphId}

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明

Request Body 参数

字段	类型	是否必须	描述

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
code	错误码	请求成功返回0
msg	STRING	请求成功返回success

接口示例:

DELETE /api/v1/notebooks/{notebookId}/paragraphs/{paragraphId}

{
    "code": 0,
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

1.2.3. 修改段落

请求URL

PUT /api/v1/notebooks/{notebookId}/paragraphs/{paragraphId}

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明

Request Body 参数

只能修改connectionId，options.path，code，lang这4个参数中的一个或者多个。不能全部为（空或者null）

字段	类型	是否必须	描述
code	STRING	可选	段落的代码，每个语句用英文分号分隔，默认为空
lang	STRING	可选	段落的代码类型，见段落语言说明，默认是SQL
connectionId	INTEGER	可选	段落的执行目标连接的 id，默认为null，可以后续再修改
options	OBJECT	可选	段落配置信息
options.path	STRING 数组	可选	段落的执行目标连接的路径（schema），有些数据源比如SQL Server有多层
hsVersion	INTEGER	可选	段落的编辑版本号，从0开始，修改段落提交的时候，需要带上修改前的版本号。不带版本号不检查版本冲突

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见段落结构说明

接口示例: 修改代码

PUT /api/v1/notebooks/{notebookId}/paragraphs/{paragraphId}

{
    "code": "select * from movie limit 10"
}

{
    "code": 0,
    "data": {
        "id": 1,
        "notebookId": 1,
        "createdBy": 1,
        "createdAt": "2020-02-25 17:19:40",
        "updatedBy": 1,
        "updatedAt": "2020-02-27 17:19:40",
        "code": "select * from movie limit 10",
        "lang": "SQL",
        "hsVersion": 1,
        "options": {},
        "isDelete": false
    },
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

接口示例: 修改默认执行schema和执行连接

PUT /api/v1/notebooks/{notebookId}/paragraphs/{paragraphId}

{
    "connectionId": 1,
    "options": {
        "path": ["sqlserverdb","schema"]
    }
}

{
    "code": 0,
    "data": {
        "id": 1,
        "notebookId": 1,
        "createdBy": 1,
        "createdAt": "2020-02-25 17:19:40",
        "updatedBy": 1,
        "updatedAt": "2020-02-27 18:19:40",
        "code": "select * from movie limit 10",
        "lang": "SQL",
        "hsVersion": 2,
        "connectionId": 1,
        "options": {
            "path": ["sqlserverdb","schema"]
        },
        "isDelete": false
    },
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

1.2.4. 获取段落

请求URL

GET /api/v1/notebooks/{notebookId}/paragraphs/{paragraphId}

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明

Request Body 参数

字段	类型	是否必须	描述

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见段落结构说明

接口示例:

GET /api/v1/notebooks/{notebookId}/paragraphs/{paragrapId}

{
    "code": 0,
    "data": {
        "id": 1,
        "notebookId": 1,
        "createdBy": 1,
        "createdAt": "2020-02-25 17:19:40",
        "updatedBy": 1,
        "updatedAt": "2020-02-27 18:19:40",
        "code": "select * from movie limit 10",
        "lang": "SQL",
        "hsVersion": 2,
        "connectionId": 1,
        "options": {
            "path": ["sqlserverdb","schema"]
        },
        "isDelete": false
    },
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

1.2.5. 获取笔记的段落列表

请求URL

GET /api/v1/notebooks/{notebookId}/paragraphs

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明
offset	INTEGER	可选	分页偏移量，默认是0
limit	INTEGER	可选	分页获取个数，默认是1000

Request Body 参数

字段	类型	是否必须	描述

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
totalHits	INTEGER	段落的总个数
offset	INTEGER	当前分页偏移量
data	OBJECT 数组	数组的元素是一个段落，见段落结构说明

接口示例:

GET /api/v1/notebooks/{notebookId}/paragraphs

{
    "code": 0,
    "data": [
        {
            "id": 1,
            "notebookId": 1,
            "createdBy": 1,
            "createdAt": "2020-02-25 17:19:40",
            "updatedBy": 1,
            "updatedAt": "2020-02-27 18:19:40",
            "code": "select * from movie limit 10",
            "lang": "SQL",
            "hsVersion": 2,
            "connectionId": 1,
            "options": {
                "path": ["sqlserverdb","schema"]
            },
            "isDelete": false
        },
        {
            "id": 2,
            "previousId": 1,
            "notebookId": 1,
            "createdBy": 1,
            "createdAt": "2020-02-26 17:19:40",
            "updatedBy": 1,
            "updatedAt": "2020-02-28 18:19:40",
            "code": "select * from movie limit 10",
            "lang": "SQL",
            "hsVersion": 2,
            "connectionId": 1,
            "options": {
                "path": ["sqlserverdb","schema"]
            },
            "isDelete": false
        }
    ],
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567",
    "totalHits": 2,
    "offset": 0
}

1.2.6. 执行一个段落

请求URL

POST /api/v1/notebooks/{notebookId}/paragraphs/{paragrapId}/executions

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明
requestId	STRING	是	请求唯一的id
isTest	BOOL	是	是否是测试执行

Request Body 参数

字段	类型	是否必须	描述

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	包含日志和执行结果
data.logs	STRING 数组	每条都是执行日志
data.schema	OBJECT 数组	每一个元素表示一个字段的属性，与数据集的字段结构相同
data.data	OBJECT 数组	每一个元素是表示一行数据的数组

接口示例:

POST /api/v1/notebooks/{notebookId}/paragraphs/{paragrapId}/executions?requestId=xxx123&isTest=true

{
}

{
    "code": 0,
    "data": {
        "logs": [
            "2020-03-03 17:10:08.13 [77] [pipelineId: 1 jobId: 1 nodeId: 2 taskId: 1] task start",
            "2020-03-03 17:10:08.409 [77] [pipelineId: 1 jobId: 1 nodeId: 2 taskId: 1] task done"
        ],
        "schema": [...],
        "data": [...]
    },
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

1.2.7. 取消执行一个段落

请求URL

PUT /api/v1/notebooks/{notebookId}/paragraphs/{paragrapId}/executions/cancel

需要认证：是

请求参数

URL 参数

字段	类型	是否必须	说明
requestId	STRING	是	执行时发送的请求id

Request Body 参数

字段	类型	是否必须	描述

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
code	错误码	请求成功返回0
msg	STRING	请求成功返回success

接口示例:

PUT /api/v1/notebooks/{notebookId}/paragraphs/{paragrapId}/executions/cancel?requestId=xxx123

{
}

{
    "code": 0,
    "msg": "success",
    "version": "3.1-SNAPSHOT@@git.commit.id.abbrev@#1234567"
}

1. 段落

1.1. 段落说明

1.1.1. 段落定义

段落结构说明

段落语言说明

1.2. 接口说明

1.2.1. 新增段落

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例: 创建笔记的第一个段落

接口示例: 创建笔记的第二个段落

1.2.2. 删除段落

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例:

1.2.3. 修改段落

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例: 修改代码

接口示例: 修改默认执行schema和执行连接

1.2.4. 获取段落

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例:

1.2.5. 获取笔记的段落列表

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例:

1.2.6. 执行一个段落

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例:

1.2.7. 取消执行一个段落

请求URL

请求参数

URL 参数

Request Body 参数

返回对象的格式说明

接口示例:

results matching ""

No results matching ""

衡石文档