api.ja-JP.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）。実サイズと一致必須', }, { name: 'file', type: 'Form.file', required: true, description: 'HTML form の file', }], 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', }], 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 はフロントエンドの json 生成のファイルアップロード後に返される FileId です。unitID 方式でエクスポートする場合、jsonID は空文字列を渡してください', }, { name: 'sscSwitch', type: 'boolean', required: false, description: 'SSC（Server Side Calculation）を有効化', }, { 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', }], 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: 'ダウンロード URL', }], example: JSON.stringify({ error: { code: 1, message: '', }, url: 'https://example.com/path/to/file.xlsx', }, null, 2), }} />