0ct0pu5/siyuan
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

📝 API 英文文档 https://github.com/siyuan-note/siyuan/issues/4095

Browse source
This commit is contained in:
Liang Ding 2022-02-24 23:23:13 +08:00
parent a13f8cd02a
commit 7bebb700e2
No known key found for this signature in database
GPG key ID: 136F30F901A2231D
2 changed files with 1012 additions and 178 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

356
API.md
View file

@ -1,5 +1,5 @@
* [规范](#规范)
* [参数和返回值](#参数和返回值)
* [Specification](#Specification)
* [Parameters and return values](#Parameters-and-return-values)
* [鉴权](#鉴权)
* [笔记本](#笔记本)
* [列出笔记本](#列出笔记本)
@ -41,38 +41,38 @@
---
## 规范
## Specification
### 参数和返回值
### Parameters and return values
* 端点：`http://127.0.0.1:6806`
* 均是 POST 方法
* 需要带参的接口，参数为 JSON 字符串，放置到 body 里，标头 Content-Type 为 `application/json`
* 返回值
* Endpoint: `http://127.0.0.1:6806`
* Both are POST methods
* An interface with parameters is required, the parameter is a JSON string, placed in the body, and the header Content-Type is `application/json`
* Return value
```json
{
"code": 0,
"msg": "",
"data": {}
}
```
````json
{
"code": 0,
"msg": "",
"data": {}
}
````
* `code`：非 0 为异常情况
* `msg`：正常情况下是空字符串，异常情况下会返回错误文案
* `data`：可能为 `{}`、`[]` 或者 `NULL`，根据不同接口而不同
* `code`: non-zero for exceptions
* `msg`: an empty string under normal circumstances, an error text will be returned under abnormal conditions
* `data`: may be `{}`, `[]` or `NULL`, depending on the interface
### 鉴权
### Authentication
在 <kbd>设置 - 关于</kbd> 里查看 API token，请求标头：`Authorization: Token xxx`
View API token in <kbd>Settings - About</kbd>, request header: `Authorization: Token xxx`
## 笔记本
## Notebooks
### 列出笔记本
### List notebooks
* `/api/notebook/lsNotebooks`
* 不带参
* 返回值
* No parameters
* Return value
```json
{
@ -82,14 +82,14 @@
"notebooks": [
{
"id": "20210817205410-2kvfpfn",
"name": "测试笔记本",
"name": "Test Notebook",
"icon": "1f41b",
"sort": 0,
"closed": false
},
{
"id": "20210808180117-czj9bvb",
"name": "思源笔记用户指南",
"name": "SiYuan User Guide",
"icon": "1f4d4",
"sort": 1,
"closed": false
@ -99,10 +99,10 @@
}
```
### 打开笔记本
### Open a notebook
* `/api/notebook/openNotebook`
* 参数
* Parameters
```json
{
@ -110,8 +110,8 @@
}
```
* `notebook`：笔记本 ID
* 返回值
* `notebook`: Notebook ID
* Return value
```json
{
@ -121,10 +121,10 @@
}
```
### 关闭笔记本
### Close a notebook
* `/api/notebook/closeNotebook`
* 参数
* Parameters
```json
{
@ -132,8 +132,8 @@
}
```
* `notebook`：笔记本 ID
* 返回值
* `notebook`: Notebook ID
* Return value
```json
{
@ -143,20 +143,20 @@
}
```
### 重命名笔记本
### Rename a notebook
* `/api/notebook/renameNotebook`
* 参数
* Parameters
```json
{
"notebook": "20210831090520-7dvbdv0",
"name": "笔记本的新名称"
"name": "New name for notebook"
}
```
* `notebook`：笔记本 ID
* 返回值
* `notebook`: Notebook ID
* Return value
```json
{
@ -166,17 +166,17 @@
}
```
### 创建笔记本
### Create a notebook
* `/api/notebook/createNotebook`
* 参数
* Parameters
```json
{
"name": "笔记本的名称"
"name": "Notebook name"
}
```
* 返回值
* Return value
```json
{
@ -185,7 +185,7 @@
"data": {
"notebook": {
"id": "20220126215949-r1wvoch",
"name": "笔记本的名称",
"name": "Notebook name",
"icon": "",
"sort": 0,
"closed": false
@ -194,10 +194,10 @@
}
```
### 删除笔记本
### Remove a notebook
* `/api/notebook/removeNotebook`
* 参数
* Parameters
```json
{
@ -205,8 +205,8 @@
}
```
* `notebook`：笔记本 ID
* 返回值
* `notebook`: Notebook ID
* Return value
```json
{
@ -216,10 +216,10 @@
}
```
### 获取笔记本配置
### Get notebook configuration
* `/api/notebook/getNotebookConf`
* 参数
* Parameters
```json
{
@ -227,8 +227,8 @@
}
```
* `notebook`：笔记本 ID
* 返回值
* `notebook`: Notebook ID
* Return value
```json
{
@ -237,28 +237,28 @@
"data": {
"box": "20210817205410-2kvfpfn",
"conf": {
"name": "测试笔记本",
"name": "Test Notebook",
"closed": false,
"refCreateSavePath": "",
"createDocNameTemplate": "",
"dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
"dailyNoteTemplatePath": ""
},
"name": "测试笔记本"
"name": "Test Notebook"
}
}
```
### 保存笔记本配置
### Save notebook configuration
* `/api/notebook/setNotebookConf`
* 参数
* Parameters
```json
{
"notebook": "20210817205410-2kvfpfn",
"conf": {
"name": "测试笔记本",
"name": "Test Notebook",
"closed": false,
"refCreateSavePath": "",
"createDocNameTemplate": "",
@ -268,15 +268,15 @@
}
```
* `notebook`：笔记本 ID
* 返回值
* `notebook`: Notebook ID
* Return value
```json
{
"code": 0,
"msg": "",
"data": {
"name": "测试笔记本",
"name": "Test Notebook",
"closed": false,
"refCreateSavePath": "",
"createDocNameTemplate": "",
@ -286,12 +286,12 @@
}
```
## 文档
## Documents
### 通过 Markdown 创建文档
### Create a document with Markdown
* `/api/filetree/createDocWithMd`
* 参数
* Parameters
```json
{
@ -301,10 +301,10 @@
}
```
* `notebook`：笔记本 ID
* `path`：文档路径，需要以 / 开头，中间使用 / 分隔层级（这里的 path 对应数据库 hpath 字段）
* `markdown`：GFM Markdown 内容
* 返回值
* `notebook`: Notebook ID
* `path`: Document path, which needs to start with / and separate levels with / (path here corresponds to the database hpath field)
* `markdown`: GFM Markdown content
* Return value
```json
{
@ -314,25 +314,25 @@
}
```
* `data`：创建好的文档 ID
* 如果使用同一个 `path` 重复调用该接口，不会覆盖已有文档，而是新建随机数结尾的文档
* `data`: Created document ID
* If you use the same `path` to call this interface repeatedly, the existing document will not be overwritten, but a new document ending with a random number will be created
### 重命名文档
### Rename a document
* `/api/filetree/renameDoc`
* 参数
* Parameters
```json
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210902210113-0avi12f.sy",
"title": "文档新标题"
"title": "Document new title"
}
```
* `notebook`：笔记本 ID
* `path`：文档路径
* 返回值
* `notebook`: Notebook ID
* `path`: Document path
* Return value
```json
{
@ -342,10 +342,10 @@
}
```
### 删除文档
### Remove a document
* `/api/filetree/removeDoc`
* 参数
* Parameters
```json
{
@ -354,9 +354,9 @@
}
```
* `notebook`：笔记本 ID
* `path`：文档路径
* 返回值
* `notebook`: Notebook ID
* `path`: Document path
* Return value
```json
{
@ -366,10 +366,10 @@
}
```
### 移动文档
### Move a document
* `/api/filetree/moveDoc`
* 参数
* Parameters
```json
{
@ -380,11 +380,11 @@
}
```
* `fromNotebook`：源笔记本 ID
* `fromPath`：源路径
* `toNotebook`：目标笔记本 ID
* `toPath`：目标路径
* 返回值
* `fromNotebook`: Source notebook ID
* `fromPath`: Source path
* `toNotebook`: Target notebook ID
* `toPath`: Target path
* Return value
```json
{
@ -394,10 +394,10 @@
}
```
### 根据路径获取人类可读路径
### Get human-readable path based on path
* `/api/filetree/getHPathByPath`
* 参数
* Parameters
```json
{
@ -406,9 +406,9 @@
}
```
* `notebook`：笔记本 ID
* `path`：路径
* 返回值
* `notebook`: Notebook ID
* `path`: Document path
* Return value
```json
{
@ -418,22 +418,22 @@
}
```
## 资源文件
## Assets
### 上传资源文件
### Upload assets
* `/api/asset/upload`
* 参数为 HTTP Multipart 表单
* The parameter is an HTTP Multipart form
* `assetsDirPath`：资源文件存放的文件夹路径，实参有以下三种情况
* `assetsDirPath`: The folder path where the assets are stored. The arguments have the following three cases
1. `"/assets/"`：工作空间/data/assets 文件夹
2. `"/测试笔记本/assets/"`：测试笔记本下的 assets 文件夹
3. `"/测试笔记本/foo/assets/"`：测试笔记本下 foo 文件夹下的 assets 文件夹
1. `"/assets/"`: Workspace/data/assets folder
2. `"/Test Notebook/assets/"`: Assets folder under `Test Notebook`
3. `"/Test Notebook/foo/assets/"`: Assets folder under foo folder under `Test notebook`
建议用第一种，统一存放到工作空间资源文件夹下。
* `file[]`：上传的文件列表
* 返回值
It is recommended to use the first one, which is stored in the workspace assets folder uniformly.
* `file[]`: Uploaded file list
* Return value
```json
{
@ -448,15 +448,15 @@
}
```
* `errFiles`：处理时遇到错误的文件名
* `succMap`：处理成功的文件，key 为上传时的文件名，value 为 assets/foo-id.png，用于将已有 Markdown 内容中的资源文件链接地址替换为上传后的地址
* `errFiles`: List of filenames with errors in upload processing
* `succMap`: For successfully processed files, the key is the file name when uploading, and the value is assets/foo-id.png, which is used to replace the asset link address in the existing Markdown content with the uploaded address
## 块操作
## Blocks
### 插入块
### Insert blocks
* `/api/block/insertBlock`
* 参数
* Parameters
```json
{
@ -466,10 +466,10 @@
}
```
* `dataType`：待插入数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待插入的数据
* `previousID`：前一个块的 ID，用于锚定插入位置
* 返回值
* `dataType`: The data type to be inserted, the value can be `markdown` or `dom`
* `data`: Data to be inserted
* `previousID`: The ID of the previous block, used to anchor the insertion position
* Return value
```json
{
@ -493,13 +493,13 @@
}
```
* `action.data`：新插入块生成的 DOM
* `action.id`：新插入块的 ID
* `action.data`: DOM generated by the newly inserted block
* `action.id`: ID of the newly inserted block
### 插入前置子块
### Prepend blocks
* `/api/block/prependBlock`
* 参数
* Parameters
```json
{
@ -509,10 +509,10 @@
}
```
* `dataType`：待插入数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待插入的数据
* `parentID`：父块的 ID，用于锚定插入位置
* 返回值
* `dataType`: The data type to be inserted, the value can be `markdown` or `dom`
* `data`: Data to be inserted
* `parentID`: The ID of the parent block, used to anchor the insertion position
* Return value
```json
{
@ -536,13 +536,13 @@
}
```
* `action.data`：新插入块生成的 DOM
* `action.id`：新插入块的 ID
* `action.data`: DOM generated by the newly inserted block
* `action.id`: ID of the newly inserted block
### 插入后置子块
### Append blocks
* `/api/block/appendBlock`
* 参数
* Parameters
```json
{
@ -552,10 +552,10 @@
}
```
* `dataType`：待插入数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待插入的数据
* `parentID`：父块的 ID，用于锚定插入位置
* 返回值
* `dataType`: The data type to be inserted, the value can be `markdown` or `dom`
* `data`: Data to be inserted
* `parentID`: The ID of the parent block, used to anchor the insertion position
* Return value
```json
{
@ -579,13 +579,13 @@
}
```
* `action.data`：新插入块生成的 DOM
* `action.id`：新插入块的 ID
* `action.data`: DOM generated by the newly inserted block
* `action.id`: ID of the newly inserted block
### 更新块
### Update a block
* `/api/block/updateBlock`
* 参数
* Parameters
```json
{
@ -595,10 +595,10 @@
}
```
* `dataType`：待更新数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待更新的数据
* `id`：待更新块 ID
* 返回值
* `dataType`: The data type to be updated, the value can be `markdown` or `dom`
* `data`: Data to be updated
* `id`: ID of the block to be updated
* Return value
```json
{
@ -622,12 +622,12 @@
}
```
* `action.data`：更新块生成的 DOM
* `action.data`: DOM generated by the updated block
### 删除块
### Delete a block
* `/api/block/deleteBlock`
* 参数
* Parameters
```json
{
@ -635,8 +635,8 @@
}
```
* `id`：待删除块 ID
* 返回值
* `id`: ID of the block to be deleted
* Return value
```json
{
@ -660,12 +660,12 @@
}
```
## 属性
## Attributes
### 设置块属性
### Set block properties
* `/api/attr/setBlockAttrs`
* 参数
* Parameters
```json
{
@ -676,9 +676,9 @@
}
```
* `id`：块 ID
* `attrs`：块属性，自定义属性必须以 `custom-` 作为前缀
* 返回值
* `id`: Block ID
* `attrs`: Block attributes, custom attributes must be prefixed with `custom-`
* Return value
```json
{
@ -688,10 +688,10 @@
}
```
### 获取块属性
### Get block attributes
* `/api/attr/getBlockAttrs`
* 参数
* Parameters
```json
{
@ -699,8 +699,8 @@
}
```
* `id`：块 ID
* 返回值
* `id`: Block ID
* Return value
```json
{
@ -709,7 +709,7 @@
"data": {
"custom-attr1": "line1\nline2",
"id": "20210912214605-uhi5gco",
"title": "PDF 标注双链演示",
"title": "PDF Annotation Demo",
"type": "doc",
"updated": "20210916120715"
}
@ -718,10 +718,10 @@
## SQL
### SQL 查询
### Execute SQL query
* `/api/query/sql`
* 参数
* Parameters
```json
{
@ -729,31 +729,31 @@
}
```
* `stmt`：SQL 脚本
* 返回值
* `stmt`: SQL statement
* Return value
```json
{
"code": 0,
"msg": "",
"data": [
{ "列": "值" }
{ "col": "val" }
]
}
```
## 模板
## Templates
### 渲染模板
### Render a template
/template/render
## 导出
## Export
### 导出 Markdown 文本
### Export Markdown
* `/api/export/exportMdContent`
* 参数
* Parameters
```json
{
@ -761,30 +761,30 @@
}
```
* `id`：要导出的文档块 ID
* 返回值
* `id`: ID of the doc block to export
* Return value
```json
{
"code": 0,
"msg": "",
"data": {
"hPath": "/0 请从这里开始",
"content": "## 🍫 内容块\n\n在思源中，唯一重要的核心概念是..."
"hPath": "/Please Start Here",
"content": "## 🍫 Content Block\n\nIn SiYuan, the only important core concept is..."
}
}
```
* `hPath`：人类可读的路径
* `content`：Markdown 内容
* `hPath`: human-readable path
* `content`: Markdown content
## 系统
## System
### 获取启动进度
### Get boot progress
* `/api/system/bootProgress`
* 不带参
* 返回值
* No parameters
* Return value
```json
{
@ -797,11 +797,11 @@
}
```
### 获取系统版本
### Get system version
* `/api/system/version`
* 不带参
* 返回值
* No parameters
* Return value
```json
{
@ -811,11 +811,11 @@
}
```
### 获取系统当前时间
### Get the current time of the system
* `/api/system/currentTime`
* 不带参
* 返回值
* No parameters
* Return value
```json
{
@ -825,7 +825,7 @@
}
```
* `data`: 精度为毫秒
* `data`: Precision in milliseconds
## Webhook

834
API_zh_CN.md Normal file
View file

@ -0,0 +1,834 @@
* [规范](#规范)
* [参数和返回值](#参数和返回值)
* [鉴权](#鉴权)
* [笔记本](#笔记本)
* [列出笔记本](#列出笔记本)
* [打开笔记本](#打开笔记本)
* [关闭笔记本](#关闭笔记本)
* [重命名笔记本](#重命名笔记本)
* [创建笔记本](#创建笔记本)
* [删除笔记本](#删除笔记本)
* [获取笔记本配置](#获取笔记本配置)
* [保存笔记本配置](#保存笔记本配置)
* [文档](#文档)
* [通过 Markdown 创建文档](#通过-markdown-创建文档)
* [重命名文档](#重命名文档)
* [删除文档](#删除文档)
* [移动文档](#移动文档)
* [根据路径获取人类可读路径](#根据路径获取人类可读路径)
* [资源文件](#资源文件)
* [上传资源文件](#上传资源文件)
* [块操作](#块操作)
* [插入块](#插入块)
* [插入前置子块](#插入前置子块)
* [插入后置子块](#插入后置子块)
* [更新块](#更新块)
* [删除块](#删除块)
* [属性](#属性)
* [设置块属性](#设置块属性)
* [获取块属性](#获取块属性)
* [SQL](#SQL)
* [SQL 查询](#SQL-查询)
* [模板](#模板)
* [渲染模板](#渲染模板)
* [导出](#导出)
* [导出 Markdown 文本](#导出-markdown-文本)
* [系统](#系统)
* [获取启动进度](#获取启动进度)
* [获取系统版本](#获取系统版本)
* [获取系统当前时间](#获取系统当前时间)
* [Webhook](#Webhook)
---
## 规范
### 参数和返回值
* 端点：`http://127.0.0.1:6806`
* 均是 POST 方法
* 需要带参的接口，参数为 JSON 字符串，放置到 body 里，标头 Content-Type 为 `application/json`
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {}
}
```
* `code`：非 0 为异常情况
* `msg`：正常情况下是空字符串，异常情况下会返回错误文案
* `data`：可能为 `{}`、`[]` 或者 `NULL`，根据不同接口而不同
### 鉴权
在 <kbd>设置 - 关于</kbd> 里查看 API token，请求标头：`Authorization: Token xxx`
## 笔记本
### 列出笔记本
* `/api/notebook/lsNotebooks`
* 不带参
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"notebooks": [
{
"id": "20210817205410-2kvfpfn",
"name": "测试笔记本",
"icon": "1f41b",
"sort": 0,
"closed": false
},
{
"id": "20210808180117-czj9bvb",
"name": "思源笔记用户指南",
"icon": "1f4d4",
"sort": 1,
"closed": false
}
]
}
}
```
### 打开笔记本
* `/api/notebook/openNotebook`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0"
}
```
* `notebook`：笔记本 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 关闭笔记本
* `/api/notebook/closeNotebook`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0"
}
```
* `notebook`：笔记本 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 重命名笔记本
* `/api/notebook/renameNotebook`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0",
"name": "笔记本的新名称"
}
```
* `notebook`：笔记本 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 创建笔记本
* `/api/notebook/createNotebook`
* 参数
```json
{
"name": "笔记本的名称"
}
```
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"notebook": {
"id": "20220126215949-r1wvoch",
"name": "笔记本的名称",
"icon": "",
"sort": 0,
"closed": false
}
}
}
```
### 删除笔记本
* `/api/notebook/removeNotebook`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0"
}
```
* `notebook`：笔记本 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 获取笔记本配置
* `/api/notebook/getNotebookConf`
* 参数
```json
{
"notebook": "20210817205410-2kvfpfn"
}
```
* `notebook`：笔记本 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"box": "20210817205410-2kvfpfn",
"conf": {
"name": "测试笔记本",
"closed": false,
"refCreateSavePath": "",
"createDocNameTemplate": "",
"dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
"dailyNoteTemplatePath": ""
},
"name": "测试笔记本"
}
}
```
### 保存笔记本配置
* `/api/notebook/setNotebookConf`
* 参数
```json
{
"notebook": "20210817205410-2kvfpfn",
"conf": {
"name": "测试笔记本",
"closed": false,
"refCreateSavePath": "",
"createDocNameTemplate": "",
"dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
"dailyNoteTemplatePath": ""
}
}
```
* `notebook`：笔记本 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"name": "测试笔记本",
"closed": false,
"refCreateSavePath": "",
"createDocNameTemplate": "",
"dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
"dailyNoteTemplatePath": ""
}
}
```
## 文档
### 通过 Markdown 创建文档
* `/api/filetree/createDocWithMd`
* 参数
```json
{
"notebook": "20210817205410-2kvfpfn",
"path": "/foo/bar",
"markdown": ""
}
```
* `notebook`：笔记本 ID
* `path`：文档路径，需要以 / 开头，中间使用 / 分隔层级（这里的 path 对应数据库 hpath 字段）
* `markdown`：GFM Markdown 内容
* 返回值
```json
{
"code": 0,
"msg": "",
"data": "20210914223645-oj2vnx2"
}
```
* `data`：创建好的文档 ID
* 如果使用同一个 `path` 重复调用该接口，不会覆盖已有文档，而是新建随机数结尾的文档
### 重命名文档
* `/api/filetree/renameDoc`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210902210113-0avi12f.sy",
"title": "文档新标题"
}
```
* `notebook`：笔记本 ID
* `path`：文档路径
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 删除文档
* `/api/filetree/removeDoc`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210902210113-0avi12f.sy"
}
```
* `notebook`：笔记本 ID
* `path`：文档路径
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 移动文档
* `/api/filetree/moveDoc`
* 参数
```json
{
"fromNotebook": "20210831090520-7dvbdv0",
"fromPath": "/20210917220056-yxtyl7i.sy",
"toNotebook": "20210817205410-2kvfpfn",
"toPath": "/"
}
```
* `fromNotebook`：源笔记本 ID
* `fromPath`：源路径
* `toNotebook`：目标笔记本 ID
* `toPath`：目标路径
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 根据路径获取人类可读路径
* `/api/filetree/getHPathByPath`
* 参数
```json
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210917220500-sz588nq/20210917220056-yxtyl7i.sy"
}
```
* `notebook`：笔记本 ID
* `path`：路径
* 返回值
```json
{
"code": 0,
"msg": "",
"data": "/foo/bar"
}
```
## 资源文件
### 上传资源文件
* `/api/asset/upload`
* 参数为 HTTP Multipart 表单
* `assetsDirPath`：资源文件存放的文件夹路径，实参有以下三种情况
1. `"/assets/"`：工作空间/data/assets 文件夹
2. `"/测试笔记本/assets/"`：`测试笔记本`下的 assets 文件夹
3. `"/测试笔记本/foo/assets/"`：`测试笔记本`下 foo 文件夹下的 assets 文件夹
建议用第一种，统一存放到工作空间资源文件夹下。
* `file[]`：上传的文件列表
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"errFiles": [""],
"succMap": {
"foo.png": "assets/foo-20210719092549-9j5y79r.png"
}
}
}
```
* `errFiles`：处理时遇到错误的文件名
* `succMap`：处理成功的文件，key 为上传时的文件名，value 为 assets/foo-id.png，用于将已有 Markdown 内容中的资源文件链接地址替换为上传后的地址
## 块
### 插入块
* `/api/block/insertBlock`
* 参数
```json
{
"dataType": "markdown",
"data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz",
"previousID": "20211229114650-vrek5x6"
}
```
* `dataType`：待插入数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待插入的数据
* `previousID`：前一个块的 ID，用于锚定插入位置
* 返回值
```json
{
"code": 0,
"msg": "",
"data": [
{
"doOperations": [
{
"action": "insert",
"data": "<div data-node-id=\"20211230115020-g02dfx0\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong style=\"color: var(--b3-font-color8);\">bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
"id": "20211230115020-g02dfx0",
"parentID": "",
"previousID": "20211229114650-vrek5x6",
"retData": null
}
],
"undoOperations": null
}
]
}
```
* `action.data`：新插入块生成的 DOM
* `action.id`：新插入块的 ID
### 插入前置子块
* `/api/block/prependBlock`
* 参数
```json
{
"data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz",
"dataType": "markdown",
"parentID": "20220107173950-7f9m1nb"
}
```
* `dataType`：待插入数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待插入的数据
* `parentID`：父块的 ID，用于锚定插入位置
* 返回值
```json
{
"code": 0,
"msg": "",
"data": [
{
"doOperations": [
{
"action": "insert",
"data": "<div data-node-id=\"20220108003710-hm0x9sc\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong style=\"color: var(--b3-font-color8);\">bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
"id": "20220108003710-hm0x9sc",
"parentID": "20220107173950-7f9m1nb",
"previousID": "",
"retData": null
}
],
"undoOperations": null
}
]
}
```
* `action.data`：新插入块生成的 DOM
* `action.id`：新插入块的 ID
### 插入后置子块
* `/api/block/appendBlock`
* 参数
```json
{
"data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz",
"dataType": "markdown",
"parentID": "20220107173950-7f9m1nb"
}
```
* `dataType`：待插入数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待插入的数据
* `parentID`：父块的 ID，用于锚定插入位置
* 返回值
```json
{
"code": 0,
"msg": "",
"data": [
{
"doOperations": [
{
"action": "insert",
"data": "<div data-node-id=\"20220108003642-y2wmpcv\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong style=\"color: var(--b3-font-color8);\">bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
"id": "20220108003642-y2wmpcv",
"parentID": "20220107173950-7f9m1nb",
"previousID": "20220108003615-7rk41t1",
"retData": null
}
],
"undoOperations": null
}
]
}
```
* `action.data`：新插入块生成的 DOM
* `action.id`：新插入块的 ID
### 更新块
* `/api/block/updateBlock`
* 参数
```json
{
"dataType": "markdown",
"data": "foobarbaz",
"id": "20211230161520-querkps"
}
```
* `dataType`：待更新数据类型，值可选择 `markdown` 或者 `dom`
* `data`：待更新的数据
* `id`：待更新块的 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": [
{
"doOperations": [
{
"action": "update",
"data": "<div data-node-id=\"20211230161520-querkps\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong>bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
"id": "20211230161520-querkps",
"parentID": "",
"previousID": "",
"retData": null
}
],
"undoOperations": null
}
]
}
```
* `action.data`：更新块生成的 DOM
### 删除块
* `/api/block/deleteBlock`
* 参数
```json
{
"id": "20211230161520-querkps"
}
```
* `id`：待删除块的 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": [
{
"doOperations": [
{
"action": "delete",
"data": null,
"id": "20211230162439-vtm09qo",
"parentID": "",
"previousID": "",
"retData": null
}
],
"undoOperations": null
}
]
}
```
## 属性
### 设置块属性
* `/api/attr/setBlockAttrs`
* 参数
```json
{
"id": "20210912214605-uhi5gco",
"attrs": {
"custom-attr1": "line1\nline2"
}
}
```
* `id`：块 ID
* `attrs`：块属性，自定义属性必须以 `custom-` 作为前缀
* 返回值
```json
{
"code": 0,
"msg": "",
"data": null
}
```
### 获取块属性
* `/api/attr/getBlockAttrs`
* 参数
```json
{
"id": "20210912214605-uhi5gco"
}
```
* `id`：块 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"custom-attr1": "line1\nline2",
"id": "20210912214605-uhi5gco",
"title": "PDF 标注双链演示",
"type": "doc",
"updated": "20210916120715"
}
}
```
## SQL
### 执行 SQL 查询
* `/api/query/sql`
* 参数
```json
{
"stmt": "SELECT * FROM blocks WHERE content LIKE'%content%' LIMIT 7"
}
```
* `stmt`：SQL 脚本
* 返回值
```json
{
"code": 0,
"msg": "",
"data": [
{ "列": "值" }
]
}
```
## 模板
### 渲染模板
/template/render
## 导出
### 导出 Markdown 文本
* `/api/export/exportMdContent`
* 参数
```json
{
"id": ""
}
```
* `id`：要导出的文档块 ID
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"hPath": "/0 请从这里开始",
"content": "## 🍫 内容块\n\n在思源中，唯一重要的核心概念是..."
}
}
```
* `hPath`：人类可读的路径
* `content`：Markdown 内容
## 系统
### 获取启动进度
* `/api/system/bootProgress`
* 不带参
* 返回值
```json
{
"code": 0,
"msg": "",
"data": {
"details": "Finishing boot...",
"progress": 100
}
}
```
### 获取系统版本
* `/api/system/version`
* 不带参
* 返回值
```json
{
"code": 0,
"msg": "",
"data": "1.3.5"
}
```
### 获取系统当前时间
* `/api/system/currentTime`
* 不带参
* 返回值
```json
{
"code": 0,
"msg": "",
"data": 1631850968131
}
```
* `data`: 精度为毫秒
## Webhook
TBD
https://ld246.com/article/1627956688432