api.zh-CN.mdx

title	API

本文档列出 Univer Server 常用 API。Base URL 默认为 http://localhost:8000。

说明：type 参数含义：1 表示 Docs，2 表示 Sheets。

文档管理

创建文档

<APITable request={{ method: 'POST', url: '/universer-api/snapshot/{type}/unit/-/create', headers: content-type: application/json, parametersType: 'Body', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1（docs），2（sheets）路径和请求体参数', }, { name: 'name', type: 'string', required: true, description: '文档名称', }, { name: 'creator', type: 'string', required: true, description: '创建者 id', }, { name: 'idempotencyKey', type: 'string', required: false, description: 'v0.20.0开始引入，可选幂等键, 字符数需要<=64', }, { name: 'metaData', type: 'string', required: false, description: 'v0.20.0开始引入，用户自定义信息，会绑定到创建的unit，之后的同步事件和USIP调用会透传，总字节数需要<=1024', }], example: curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \\ -X POST \\ -H 'Content-Type: application/json' \\ --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'unitID', type: 'string', description: '文档 id', }], example: JSON.stringify({ error: { code: 1, message: 'success', }, unitID: 'ETVf-B4lQqOSE_p09mcp9Q', }, null, 2), }} />

获取文档列表

<APITable request={{ method: 'GET', url: '/universer-api/snapshot/{type}/units', parametersType: 'Query', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1（doc），2（sheet）路径和请求体参数', }, { name: 'nextCursor', type: 'string', required: false, description: '分页的下一页游标', }], example: curl -X GET 'http://localhost:8000/universer-api/snapshot/1/units?nextCursor=100', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'units', type: 'array[object]', description: '文档列表', properties: [{ name: 'unitID', type: 'string', description: '文档 id', }, { name: 'name', type: 'string', description: '文档名称', }, { name: 'type', type: 'enum(int)', description: '1（doc），2（sheet）', }], }, { name: 'nextCursor', type: 'string', description: '分页的下一页游标，当为空时表示为最后一页', }], example: JSON.stringify({ error: { code: 1, message: '', }, units: [{ unitID: '1', name: 'a', type: 1, }], nextCursor: '200', }, null, 2), }} />

删除文档

<APITable request={{ method: 'DELETE', url: '/universer-api/snapshot/-/units', headers: content-type: application/json, parametersType: 'Query', parameters: [{ name: 'unitIds', type: 'array[string]', required: true, description: '文档 id 数组', }, { name: 'hardDelete', type: 'boolean', required: false, description: '是否永久删除，true 为永久删除，false 或不传为仅标记删除', }], example: curl -X DELETE 'http://localhost:8000/universer-api/snapshot/-/units?unitIds=1&unitIds=2&hardDelete=true', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }], example: JSON.stringify({ error: { code: 1, message: '', }, }, null, 2), }} />

复制文档（实验性 API）

说明：这是实验性 API，后续可能发生兼容性变更。

<APITable request={{ method: 'POST', url: '/universer-api/snapshot/{type}/unit/{unitId}/fork', headers: content-type: application/json, parametersType: 'Path', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1（docs），2（sheets）路径参数', }, { name: 'unitId', type: 'string', required: true, description: '待复制的文档 id', }], example: curl -X POST 'http://localhost:8000/universer-api/snapshot/2/unit/ETVf-B4lQqOSE_p09mcp9Q/fork', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'unitId', type: 'string', description: '复制后生成的新文档 id', }], example: JSON.stringify({ error: { code: 1, message: '', }, unitId: 'FORKED_ETVf-B4lQqOSE_p09mcp9Q', }, null, 2), }} />

生成快照

<APITable request={{ method: 'GET', url: '/universer-api/snapshot/{type}/unit/{unitID}/rev/0/ensure', parametersType: 'Query', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1（doc），2（sheet）路径参数', }, { name: 'unitID', type: 'string', required: true, description: '文档 id', }], example: curl -X GET 'http://localhost:8000/universer-api/snapshot/2/unit/ETVf-B4lQqOSE_p09mcp9Q/rev/0/ensure', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }], example: JSON.stringify({ error: { code: 1, message: '', }, }, null, 2), }} />

文件与导入导出

上传文件 [#upload-file]

<APITable request={{ method: 'POST', url: '/universer-api/stream/file/upload', headers: content-type: multipart/form-data, parametersType: 'Body', parameters: [{ name: 'size', type: 'int', required: true, description: '文件大小（byte），query 参数；参数必须等于真实文件大小，否则返回 error', }, { name: 'file', type: 'Form.file', required: true, description: 'HTML form 上传文件', }], example: curl 'http://localhost:8000/universer-api/stream/file/upload?size=125466' \\ --header 'cookie: _univer=XXXXXX' \\ --form 'file=@"demo.xlsx"', }} response={{ type: 'application/json', parameters: [{ name: 'FileId', type: 'string', description: '文件 id，用于后续导入导出', }], example: JSON.stringify({ FileId: 'xxxx', }, null, 2), }} />

导入 [#import-file]

<APITable request={{ method: 'POST', url: '/universer-api/exchange/{type}/import', headers: content-type: application/json, parametersType: 'Body', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1（doc），2（sheet）', }, { name: 'outputType', type: 'enum(int)', required: true, description: '1（unit），2（json）', }, { name: 'fileID', type: 'string', required: true, description: '上传的文件 id', }, { name: 'minSheetRowCount', type: 'int', required: true, description: '最小行数，导入时会检查表格行数是否满足要求', }, { name: 'minSheetColumnCount', type: 'int', required: true, description: '最小列数，导入时会检查表格列数是否满足要求', }, { name: 'idempotencyKey', type: 'string', required: false, description: 'v0.20.0开始引入，可选幂等键, 字符数需要<=64', }, { name: 'metaData', type: 'string', required: false, description: 'v0.20.0开始引入，用户自定义信息，会绑定到导入的unit，之后的同步事件和USIP调用会透传，总字节数需要<=1024', }], example: curl -X POST 'http://localhost:8000/universer-api/exchange/2/import' \\ -H 'Content-Type: application/json' \\ --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20,"idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'taskID', type: 'string', description: '转换任务 id，使用该 id 轮询接口获取结果', }], example: JSON.stringify({ error: { code: 1, message: '', }, taskID: '456', }, null, 2), }} />

导出 [#export-file]

<APITable request={{ method: 'POST', url: '/universer-api/exchange/{type}/export', headers: content-type: application/json, parametersType: 'Body', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1（doc），2（sheet）', }, { name: 'unitID', type: 'string', required: true, description: '协同文档 id。若以 jsonID 方式导出，则无需 unitID，传空字符串即可', }, { name: 'jsonID', type: 'string', required: true, description: '非协同文档导出的方式，jsonID 是前端 snapshot json 生成的文件上传后返回的 FileId。若以 unitID 方式导出，则无需 jsonID，传空字符串即可', }, { name: 'sscSwitch', type: 'boolean', required: false, description: '是否开启 SSC（Server Side Calculation），true 则触发服务端公式计算，默认为 false', }, { name: 'useImageUrl', type: 'boolean', required: false, description: '是否禁止单元格图片转换为链接，true 则单元格图片不会转换为链接，默认为 false', }, { name: 'ignoreTableExport', type: 'boolean', required: false, description: '是否忽略表格（Table）导出，默认为 false', }], example: curl -X POST 'http://localhost:8000/universer-api/exchange/2/export' \\ -H 'Content-Type: application/json' \\ --data-raw '{"unitID":"xxxx","type":2}', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'taskID', type: 'string', description: '转换任务 id，使用该 id 轮询接口获取结果', }], example: JSON.stringify({ error: { code: 1, message: '', }, taskID: '456', }, null, 2), }} />

获取转换结果 [#get-task-result]

<APITable request={{ method: 'GET', url: '/universer-api/exchange/task/{taskID}', parametersType: 'Path', parameters: [{ name: 'taskID', type: 'string', required: true, description: '转换任务 id', }], example: curl -X GET 'http://localhost:8000/universer-api/exchange/task/123', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'status', type: 'enum(string)', description: '"pending", "done", "failed"', }, { name: 'export', type: 'object', properties: [{ name: 'fileID', type: 'string', description: '导出结果文件 id', }], }, { name: 'import', type: 'object', properties: [{ name: 'unitID', type: 'string', description: '导入转换后的 unitID', }, { name: 'jsonID', type: 'string', description: '导入 JSON 结果的文件 id', }], }], example: JSON.stringify({ error: { code: 1, message: '', }, status: 'done', export: { fileID: '456', }, import: { unitID: '789', jsonID: '012', }, }, null, 2), }} />

获取文件 [#get-file]

<APITable request={{ method: 'GET', url: '/universer-api/file/{fileID}/sign-url', parametersType: 'Path', parameters: [{ name: 'fileID', type: 'string', required: true, description: '转换任务的结果文件 id (export.fileID 或 import.jsonID)', }], example: curl -X GET 'http://localhost:8000/universer-api/file/1234/sign-url', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1（成功）', }, { name: 'message', type: 'string', description: '失败信息', }], }, { name: 'url', type: 'string', description: '文件下载链接', }], example: JSON.stringify({ error: { code: 1, message: '', }, url: 'https://example.com/path/to/file.xlsx', }, null, 2), }} />