OneLake Data Access Security - Create Or Update Data Access Roles

服务:: Core

API 版本:: v1

在 OneLake 中创建或更新数据访问角色。

Note

此 API 是预览版的一部分，仅用于评估和开发目的。它可能会根据反馈进行更改，不建议将其用于生产。

所需的委派范围

OneLake.ReadWrite.All

Microsoft Entra 支持的标识

此 API 支持本节中列出的Microsoft 标识。

Identity	Support
User	Yes
服务主体和托管标识	Yes

Interface

PUT https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/dataAccessRoles

具有可选参数:

PUT https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/dataAccessRoles?dryRun={dryRun}

URI 参数

名称	在	必需	类型	说明
itemId	path	True	string (uuid)	要放置角色的 Fabric 项的 ID。
workspaceId	path	True	string (uuid)	工作区 ID。
dryRun	query		boolean	用于触发 API 调用的干运行。 True - API 调用将触发干运行，不会更改任何角色。 False - 不会触发试运行，角色将更新。

请求头

名称	必需	类型	说明
If-Match		string	ETag 值。必须在引号中指定 ETag。如果提供，则仅当资源的 ETag 与提供的 ETag 匹配时，调用才会成功。
If-None-Match		string	ETag 值。必须在引号中指定 ETag。如果提供，则仅当资源的 ETag 与提供的 ETag 不匹配时，调用才会成功。

请求正文

名称	类型	说明
value	DataAccessRole[]	用于管理数据访问安全性的角色列表，并确保只有经过授权的用户才能查看特定数据。角色表示一组权限和权限范围，用于定义允许其成员对作用域中的数据执行的作。成员是已授予该角色的用户或组，他们可以根据分配给该角色的权限读取数据。例如，成员可以是Microsoft Entra ID 组，权限范围可以是 OneLake 中给定的文件路径、文件夹或表（s）上应用的读取作。

响应

名称	类型	说明
200 OK		请求成功完成。标头 Etag: string
Other Status Codes	ErrorResponse	常见错误代码： ItemNotFound - 指示服务器找不到请求的项目。 PreconditionFailed -Indicates 当前资源 ETag 与 If-Match 标头中指定的值不匹配。

名称

类型

说明

200 OK

请求成功完成。

标头

Etag: string

Other Status Codes

ErrorResponse

常见错误代码：

ItemNotFound - 指示服务器找不到请求的项目。
PreconditionFailed -Indicates 当前资源 ETag 与 If-Match 标头中指定的值不匹配。

示例

Create or update data access roles example

Create or update data access roles with constraints example

Create or update data access roles with tables path example

Create or update data access roles example

示例请求

HTTP

PUT https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles

{
  "value": [
    {
      "name": "default_role_1",
      "decisionRules": [
        {
          "effect": "Permit",
          "permission": [
            {
              "attributeName": "Path",
              "attributeValueIncludedIn": [
                "*"
              ]
            },
            {
              "attributeName": "Action",
              "attributeValueIncludedIn": [
                "Read"
              ]
            }
          ]
        }
      ],
      "members": {
        "fabricItemMembers": [
          {
            "itemAccess": [
              "ReadAll"
            ],
            "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb"
          }
        ]
      }
    }
  ]
}

示例响应

状态代码:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with constraints example

示例请求

HTTP

PUT https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles

{
  "value": [
    {
      "name": "default_role_1",
      "decisionRules": [
        {
          "effect": "Permit",
          "permission": [
            {
              "attributeName": "Path",
              "attributeValueIncludedIn": [
                "*"
              ]
            },
            {
              "attributeName": "Action",
              "attributeValueIncludedIn": [
                "Read"
              ]
            }
          ],
          "constraints": {
            "columns": [
              {
                "tablePath": "/Tables/industrytable",
                "columnNames": [
                  "Industry"
                ],
                "columnEffect": "Permit",
                "columnAction": [
                  "Read"
                ]
              }
            ],
            "rows": [
              {
                "tablePath": "/Tables/industrytable",
                "value": "select * from Industrytable where Industry=\"Green\""
              }
            ]
          }
        }
      ],
      "members": {
        "fabricItemMembers": [
          {
            "itemAccess": [
              "ReadAll"
            ],
            "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb"
          }
        ]
      }
    }
  ]
}

示例响应

状态代码:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with tables path example

示例请求

HTTP

PUT https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles

{
  "value": [
    {
      "name": "default_role_1",
      "decisionRules": [
        {
          "effect": "Permit",
          "permission": [
            {
              "attributeName": "Path",
              "attributeValueIncludedIn": [
                "/Tables/sales",
                "/Tables/users"
              ]
            },
            {
              "attributeName": "Action",
              "attributeValueIncludedIn": [
                "Read"
              ]
            }
          ]
        }
      ],
      "members": {
        "fabricItemMembers": [
          {
            "itemAccess": [
              "ReadAll"
            ],
            "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb"
          }
        ]
      }
    }
  ]
}

示例响应

状态代码:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d5

定义

名称	说明
AttributeName	指定正在评估访问权限的属性的名称。 AttributeName 可以 `Path` 或 `Action`。可能会随着时间的推移添加其他 attributeName 类型。
ColumnAction	应用于 columnNames 的作数组。这将确定用户能够在列上执行的作。允许的值为：读取。可能会随着时间的推移添加其他 columnAction 类型。
ColumnConstraint	ColumnConstraint 指示一个约束，该约束确定用户对表中的列的权限和可见性。
ColumnEffect	赋予 columnNames 的效果。唯一允许的值为 Permit。可能会随着时间的推移添加其他 columnEffect 类型。
Constraints	作为此角色的一部分应用于表的任何约束，例如行级或列级安全性。如果未包含，则任何约束都不适用于角色中的任何表。
CreateOrUpdateDataAccessRolesRequest	包含用于管理数据访问安全性的角色定义，并确保只有经过授权的用户才能查看、编辑或删除某些数据。调用此 API 可更新角色定义并创建、更新或删除角色以匹配提供的有效负载。
DataAccessRole	数据访问角色表示一组权限和权限范围，用于定义允许其成员对作用域中的数据执行的作。数据访问角色用于管理数据访问安全性，并确保只有经过授权的用户才能查看、编辑或删除某些数据。成员是已授予该角色的用户或组，他们可以根据分配给该角色的权限读取数据。例如，成员可以是Microsoft Entra ID 组，权限范围可以是 OneLake 中给定的文件路径、文件夹或表的读取作。
DecisionRule	指定与请求的作匹配的规则。包含效果（允许）和权限，用于确定用户或实体是否有权对资源执行特定作（例如读取）。权限是由属性定义的一组范围，必须与要应用的规则的请求作匹配。
Effect	角色对访问数据资源的影响。目前，唯一支持的效果类型是 `Permit`，该类型授予对资源的访问权限。可能会随着时间的推移添加其他效果类型。
ErrorRelatedResource	与错误相关的资源详细信息对象。
ErrorResponse	错误响应。
ErrorResponseDetails	错误响应详细信息。
FabricItemMember	构造项成员。
ItemAccess	一个列表，指定必须自动包含在角色成员中的 Fabric 用户的访问权限。可能会随着时间的推移添加其他 itemAccess 类型。
Members	成员对象，该对象包含角色的成员作为不同成员类型的数组。
MicrosoftEntraMember	Microsoft分配给角色的 Entra ID 成员。
ObjectType	Microsoft Entra ID 对象的类型。可能会随着时间的推移添加其他 objectType 类型。
PermissionScope	定义一组属性（属性），用于确定对资源的访问权限的范围和级别。当 `attributeName` 属性设置为 `Path`时，`attributeValueIncludedIn` 属性必须指定要访问的资源的位置，例如“Tables/Table1”。当 `attributeName` 属性设置为 `Action`时，`attributeValueIncludedIn` 属性必须指定要授予的访问权限类型，例如 `Read`。
RowConstraint	RowConstraint 指示一个约束，用于确定用户可以看到的表中的行。使用 RowConstraints 定义的角色使用 T-SQL 来定义筛选表中数据的谓词。不满足谓词条件的行将被筛选掉，留下原始行的子集。 RowConstraints 还可用于使用 T-SQL 指定 RLS 的动态和多表风格。

AttributeName

枚举

指定正在评估访问权限的属性的名称。 AttributeName 可以 Path 或 Action。可能会随着时间的推移添加其他 attributeName 类型。

值	说明
Path	属性名称路径
Action	属性名称作

ColumnAction

枚举

应用于 columnNames 的作数组。这将确定用户能够在列上执行的作。允许的值为：读取。可能会随着时间的推移添加其他 columnAction 类型。

值	说明
Read	ColumnAction 值读取

ColumnConstraint

Object

ColumnConstraint 指示一个约束，该约束确定用户对表中的列的权限和可见性。

名称	类型	说明
columnAction	ColumnAction[]	应用于 columnNames 的作数组。这将确定用户能够在列上执行的作。允许的值为：读取。可能会随着时间的推移添加其他 columnAction 类型。
columnEffect	ColumnEffect	赋予 columnNames 的效果。唯一允许的值为 Permit。可能会随着时间的推移添加其他 columnEffect 类型。
columnNames	string[]	区分大小写的列名的数组。每个值都是指定表中的 `tablePath`列名。使用这些列和 `columnEffectcolumnAction`。未列出的列将获取默认值 null。用于 `*` 指示表中的所有列。
tablePath	string	指定列约束适用的表的相对文件路径。这应采用以下 `/Tables/{optionalSchema}/{tableName}`形式。此处只能提供一个值，tableName 必须是 PermissionScope 中包含的表。

ColumnEffect

枚举

赋予 columnNames 的效果。唯一允许的值为 Permit。可能会随着时间的推移添加其他 columnEffect 类型。

值	说明
Permit	ColumnEffect 类型 Permit

Constraints

Object

作为此角色的一部分应用于表的任何约束，例如行级或列级安全性。如果未包含，则任何约束都不适用于角色中的任何表。

名称	类型	说明
columns	ColumnConstraint[]	应用于数据访问角色中的一个或多个表的列约束数组。
rows	RowConstraint[]	应用于数据访问角色中的一个或多个表的行约束数组。

CreateOrUpdateDataAccessRolesRequest

Object

包含用于管理数据访问安全性的角色定义，并确保只有经过授权的用户才能查看、编辑或删除某些数据。调用此 API 可更新角色定义并创建、更新或删除角色以匹配提供的有效负载。

名称	类型	说明
value	DataAccessRole[]	用于管理数据访问安全性的角色列表，并确保只有经过授权的用户才能查看特定数据。角色表示一组权限和权限范围，用于定义允许其成员对作用域中的数据执行的作。成员是已授予该角色的用户或组，他们可以根据分配给该角色的权限读取数据。例如，成员可以是Microsoft Entra ID 组，权限范围可以是 OneLake 中给定的文件路径、文件夹或表（s）上应用的读取作。

DataAccessRole

Object

数据访问角色表示一组权限和权限范围，用于定义允许其成员对作用域中的数据执行的作。数据访问角色用于管理数据访问安全性，并确保只有经过授权的用户才能查看、编辑或删除某些数据。成员是已授予该角色的用户或组，他们可以根据分配给该角色的权限读取数据。例如，成员可以是Microsoft Entra ID 组，权限范围可以是 OneLake 中给定的文件路径、文件夹或表的读取作。

名称	类型	说明
decisionRules	DecisionRule[]	构成数据访问角色的权限数组。
id	string (uuid)	数据访问角色的唯一 ID。
members	Members	成员对象，该对象包含角色的成员作为不同成员类型的数组。
name	string	数据访问角色的名称。

DecisionRule

Object

指定与请求的作匹配的规则。包含效果（允许）和权限，用于确定用户或实体是否有权对资源执行特定作（例如读取）。权限是由属性定义的一组范围，必须与要应用的规则的请求作匹配。

名称	类型	说明
constraints	Constraints	作为此角色的一部分应用于表的任何约束，例如行级或列级安全性。如果未包含，则任何约束都不适用于角色中的任何表。
effect	Effect	角色对访问数据资源的影响。目前，唯一支持的效果类型是 `Permit`，该类型授予对资源的访问权限。可能会随着时间的推移添加其他效果类型。
permission	PermissionScope[]	`permission` 属性是一个数组，指定所请求作的范围和访问级别。数组必须正好包含两个 PermissionScope 对象：`Path` 和 `Action`。 `scope` 是使用 `PermissionScope` 对象定义的，`attributeValueIncludedIn` 指定要访问的资源的位置或所授予的作类型。 `access` 是指授予的访问权限级别，例如 `Read`。

Effect

枚举

角色对访问数据资源的影响。目前，唯一支持的效果类型是 Permit，该类型授予对资源的访问权限。可能会随着时间的推移添加其他效果类型。

值	说明
Permit	效果类型 Permit

ErrorRelatedResource

Object

与错误相关的资源详细信息对象。

名称	类型	说明
resourceId	string	错误中涉及的资源 ID。
resourceType	string	错误中涉及的资源的类型。

ErrorResponse

Object

错误响应。

名称	类型	说明
errorCode	string	提供有关错误条件的信息的特定标识符，允许服务与其用户之间的标准化通信。
message	string	错误的人工可读表示形式。
moreDetails	ErrorResponseDetails[]	其他错误详细信息的列表。
relatedResource	ErrorRelatedResource	与错误相关的资源详细信息。
requestId	string	与错误关联的请求的 ID。

ErrorResponseDetails

Object

错误响应详细信息。

名称	类型	说明
errorCode	string	提供有关错误条件的信息的特定标识符，允许服务与其用户之间的标准化通信。
message	string	错误的人工可读表示形式。
relatedResource	ErrorRelatedResource	与错误相关的资源详细信息。

FabricItemMember

Object

构造项成员。

名称	类型	说明
itemAccess	ItemAccess[]	一个列表，指定必须自动包含在角色成员中的 Fabric 用户的访问权限。可能会随着时间的推移添加其他 itemAccess 类型。
sourcePath	string pattern: ^[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?/[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$	具有指定项访问权限的 Fabric 项的路径。

ItemAccess

枚举

一个列表，指定必须自动包含在角色成员中的 Fabric 用户的访问权限。可能会随着时间的推移添加其他 itemAccess 类型。

值	说明
Read	项访问读取。
Write	项访问写入。
Reshare	项目访问重新共享。
Explore	项访问浏览。
Execute	项访问执行。
ReadAll	Item Access ReadAll。

Members

Object

成员对象，该对象包含角色的成员作为不同成员类型的数组。

名称	类型	说明
fabricItemMembers	FabricItemMember[]	在 Microsoft Fabric 中具有特定权限集的成员列表。具有该权限集的所有成员都作为此数据访问角色的成员添加。
microsoftEntraMembers	MicrosoftEntraMember[]	Microsoft Entra ID 成员的列表。

MicrosoftEntraMember

Object

Microsoft分配给角色的 Entra ID 成员。

名称	类型	说明
objectId	string (uuid)	对象 ID。
objectType	ObjectType	Microsoft Entra ID 对象的类型。可能会随着时间的推移添加其他 objectType 类型。
tenantId	string (uuid)	租户 ID。

ObjectType

枚举

Microsoft Entra ID 对象的类型。可能会随着时间的推移添加其他 objectType 类型。

值	说明
Group	属性名称组
User	属性名称用户
ServicePrincipal	属性名称 ServicePrincipal
ManagedIdentity	属性名称 ManagedIdentity

PermissionScope

Object

定义一组属性（属性），用于确定对资源的访问权限的范围和级别。当 attributeName 属性设置为 Path时，attributeValueIncludedIn 属性必须指定要访问的资源的位置，例如“Tables/Table1”。当 attributeName 属性设置为 Action时，attributeValueIncludedIn 属性必须指定要授予的访问权限类型，例如 Read。

名称	类型	说明
attributeName	AttributeName	指定正在评估访问权限的属性的名称。 AttributeName 可以 `Path` 或 `Action`。可能会随着时间的推移添加其他 attributeName 类型。
attributeValueIncludedIn	string[]	指定 `attributeName` 的值列表，以定义对资源的作用域和访问级别。 `attributeName` `Path`时，`attributeValueIncludedIn` 必须指定要访问的资源的位置，例如“Tables/Table1”。当 `attributeNameAction`时，`attributeValueIncludedIn` 必须指定要授予的访问权限类型，例如 `Read`。

RowConstraint

Object

RowConstraint 指示一个约束，用于确定用户可以看到的表中的行。使用 RowConstraints 定义的角色使用 T-SQL 来定义筛选表中数据的谓词。不满足谓词条件的行将被筛选掉，留下原始行的子集。 RowConstraints 还可用于使用 T-SQL 指定 RLS 的动态和多表风格。

名称	类型	说明
tablePath	string	指定行约束适用的表的相对文件路径。这应采用以下 `/Tables/{optionalSchema}/{tableName}`形式。此处只能提供一个值，tableName 必须是 PermissionScope 中包含的表。
value	string	一个 T-SQL 表达式，用于计算角色成员可以看到哪些行。只能将 T-SQL 的子集用作谓词。

通过

OneLake Data Access Security - Create Or Update Data Access Roles

所需的委派范围

Microsoft Entra 支持的标识

Interface

URI 参数

请求头

请求正文

响应

示例

Create or update data access roles example

示例请求

示例响应

Create or update data access roles with constraints example

示例请求

示例响应

Create or update data access roles with tables path example

示例请求

示例响应

定义

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

CreateOrUpdateDataAccessRolesRequest

DataAccessRole

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint