diff --git a/content/guides/pro/api.mdx b/content/guides/pro/api.mdx index 83b0fe9..9687e89 100644 --- a/content/guides/pro/api.mdx +++ b/content/guides/pro/api.mdx @@ -31,11 +31,21 @@ This page lists common Univer Server APIs. The default base URL is `http://local type: 'string', required: true, description: 'Creator id', + }, { + name: 'idempotencyKey', + type: 'string', + required: false, + description: 'Introduced since v0.20.0. Optional idempotency key; The total byte size must be ≤ 64.', + }, { + name: 'metaData', + type: 'string', + required: false, + description: 'Introduced since v0.20.0. User-defined information, bound to the created unit, will be transparently passed through in subsequent synchronization events and USIP calls. The total byte size must be ≤ 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"}'`, + --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`, }} response={{ type: 'application/json', @@ -292,10 +302,20 @@ This page lists common Univer Server APIs. The default base URL is `http://local type: 'int', required: true, description: 'Minimum columns; import validates column count', + }, { + name: 'idempotencyKey', + type: 'string', + required: false, + description: 'Introduced since v0.20.0. Optional idempotency key; The total byte size must be ≤ 64.', + }, { + name: 'metaData', + type: 'string', + required: false, + description: 'Introduced since v0.20.0. User-defined information, bound to the imported unit, will be transparently passed through in subsequent synchronization events and USIP calls. The total byte size must be ≤ 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}'`, + --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20,"idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`, }} response={{ type: 'application/json', diff --git a/content/guides/pro/api.zh-CN.mdx b/content/guides/pro/api.zh-CN.mdx index 787f76d..03214a9 100644 --- a/content/guides/pro/api.zh-CN.mdx +++ b/content/guides/pro/api.zh-CN.mdx @@ -31,11 +31,21 @@ title: API 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"}'`, + --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`, }} response={{ type: 'application/json', @@ -292,10 +302,20 @@ title: API 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}'`, + --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20,"idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`, }} response={{ type: 'application/json', diff --git a/content/guides/pro/event-sync.ja-JP.mdx b/content/guides/pro/event-sync.ja-JP.mdx index 56ff1a7..d60302f 100644 --- a/content/guides/pro/event-sync.ja-JP.mdx +++ b/content/guides/pro/event-sync.ja-JP.mdx @@ -53,6 +53,7 @@ message EventSyncData { univer.ChangesetAck csAckEvent = 4; // more event types in the future. } + optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request) } message ChangesetAck { diff --git a/content/guides/pro/event-sync.mdx b/content/guides/pro/event-sync.mdx index c6cbfe9..d2837e4 100644 --- a/content/guides/pro/event-sync.mdx +++ b/content/guides/pro/event-sync.mdx @@ -53,6 +53,7 @@ message EventSyncData { univer.ChangesetAck csAckEvent = 4; // more event types in the future. } + optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request) } message ChangesetAck { diff --git a/content/guides/pro/event-sync.zh-CN.mdx b/content/guides/pro/event-sync.zh-CN.mdx index d8c0c7a..2367294 100644 --- a/content/guides/pro/event-sync.zh-CN.mdx +++ b/content/guides/pro/event-sync.zh-CN.mdx @@ -53,6 +53,7 @@ message EventSyncData { univer.ChangesetAck csAckEvent = 4; // more event types in the future. } + optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request) } message ChangesetAck { diff --git a/content/guides/pro/event-sync.zh-TW.mdx b/content/guides/pro/event-sync.zh-TW.mdx index 69c6844..c278454 100644 --- a/content/guides/pro/event-sync.zh-TW.mdx +++ b/content/guides/pro/event-sync.zh-TW.mdx @@ -53,6 +53,7 @@ message EventSyncData { univer.ChangesetAck csAckEvent = 4; // more event types in the future. } + optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request) } message ChangesetAck { diff --git a/content/guides/pro/usip.mdx b/content/guides/pro/usip.mdx index bcef070..373353c 100644 --- a/content/guides/pro/usip.mdx +++ b/content/guides/pro/usip.mdx @@ -149,6 +149,11 @@ To determine permissions for reading/editing a document. type: 'string', example: 'acff-adebc125e45b', description: 'Document ID', + }, { + name: 'metaData', + type: 'string', + example: '{"tenantId":"company1"}', + description: 'metadata associated with the unit. Introduced since v0.20.0', }], example: 'curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"', }} @@ -194,9 +199,15 @@ Required when selecting users for protected ranges or sheets. type: 'array[string]', example: '["unit_id1", "unit_id2"]', description: 'Document IDs', + }, { + name: 'unitsMetaDatas', + type: 'object', + example: '{"unit_id1":"metadata of unit_id1","unit_id2":"metadata of unit_id2"}', + description: 'metadata of each unit in the unitIDs param, introduced since v0.20.0', }], example: JSON.stringify({ - unitIDs: ['unit_id1', 'unit_id2', 'unit_id3'], + unitIDs: ['unit_id1', 'unit_id2'], + unitsMetaDatas: { unit_id1: 'metadata of unit_id1', unit_id2: 'metadata of unit_id2' }, }, null, 2), }} response={{ @@ -300,10 +311,16 @@ For your system to display last edit time. type: 'int', example: '1762591632345', description: 'Unix timestamp in milliseconds', + }, { + name: 'metaData', + type: 'string', + example: '{"tenantId":"company1"}', + description: 'metadata associated with the unit. Introduced since v0.20.0', }], example: JSON.stringify({ unitID: 'unit_id1', editTimeUnixMs: 1762591632345, + metaData: { tenantId: 'company1' }, }, null, 2), }} response={{ @@ -360,7 +377,7 @@ If your USIP service is exposed on the public network, to ensure API request sec Univer uses RBAC with fixed roles: `owner`, `editor`, `reader`. You can override minimum role requirements for permission points. -Default permission points: +Default permission points and minimum role requirements are as follows: | Permission | Enum | Description | Minimum Role | Role Enum | |:-------|:---------|:-------|:-------|:-------| @@ -415,7 +432,7 @@ universer: ### Object Permission Inheritance -By default, document owners do not automatically own all protected ranges/sheets. To enable inheritance: +By default, the owner of a document does not automatically have owner permissions for all "protected areas / sub-tables" within that document. If you want the document owner to unconditionally have full permissions over all sub-objects within the document, you can enable permission inheritance by configuring the following settings: ```properties title=".env.custom" AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true diff --git a/content/guides/pro/usip.zh-CN.mdx b/content/guides/pro/usip.zh-CN.mdx index 58035a1..8552cee 100644 --- a/content/guides/pro/usip.zh-CN.mdx +++ b/content/guides/pro/usip.zh-CN.mdx @@ -149,6 +149,11 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或 type: 'string', example: 'acff-adebc125e45b', description: '文档 ID', + }, { + name: 'metaData', + type: 'string', + example: '{"tenantId":"company1"}', + description: '文档关联的由客户系统设置的自定义metadata,从v0.20.0开始引入', }], example: 'curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"', }} @@ -194,9 +199,15 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或 type: 'array[string]', example: '["unit_id1", "unit_id2"]', description: '文档 ID 数组', + }, { + name: 'unitsMetaDatas', + type: 'object', + example: '{"unit_id1":"metadata of unit_id1","unit_id2":"metadata of unit_id2"}', + description: '参数unitIDs数组中每个unit的metadata,从v0.20.0开始引入', }], example: JSON.stringify({ - unitIDs: ['unit_id1', 'unit_id2', 'unit_id3'], + unitIDs: ['unit_id1', 'unit_id2'], + unitsMetaDatas: { unit_id1: 'metadata of unit_id1', unit_id2: 'metadata of unit_id2' }, }, null, 2), }} response={{ @@ -300,10 +311,16 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或 type: 'int', example: '1762591632345', description: 'unix 时间戳(毫秒)', + }, { + name: 'metaData', + type: 'string', + example: '{"tenantId":"company1"}', + description: '文档关联的由客户系统设置的自定义metadata,从v0.20.0开始引入', }], example: JSON.stringify({ unitID: 'unit_id1', editTimeUnixMs: 1762591632345, + metaData: { tenantId: 'company1' }, }, null, 2), }} response={{ @@ -360,9 +377,9 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或 ## Univer 权限模型 -Univer 使用 RBAC 模型,固定角色为 `owner`、`editor`、`reader`。可以通过配置为某些权限点位设置最低角色。 +Univer 使用 RBAC 模型,固定角色为 `owner`、`editor`、`reader`。可以通过配置为某些权限点位设置最低角色要求。 -默认权限点位与最低角色如下: +默认权限点位与最低角色要求如下: | 权限点位 | 权限点位枚举值 | 点位含义 | 最低角色要求 | 角色枚举值 | |:-------|:---------|:-------|:-------|:-------| @@ -417,7 +434,7 @@ universer: ### 对象权限继承 -默认情况下,文档的 owner 并不自动拥有该文档内所有“保护区/子表”的 owner 权限。若需要开启继承: +默认情况下,文档的 owner 并不自动拥有该文档内所有“保护区/子表”的 owner 权限。如果你希望文档的owner无条件地拥有文档内所有子对象的所有权限,可以如下配置来开启权限的继承: ```properties title=".env.custom" AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true