OneLake Data Access Security - Create Or Update Data Access Roles

Serviço:: Core

Versão da API:: v1

Cria ou atualiza funções de acesso a dados no OneLake.

Note

Esta API faz parte de uma versão de pré-visualização e é fornecida apenas para fins de avaliação e desenvolvimento. Ele pode mudar com base no feedback e não é recomendado para uso em produção.

Escopos delegados necessários

OneLake.ReadWrite.All

Identidades suportadas pelo Microsoft Entra

Esta API suporta as identidades do Microsoft listadas nesta secção.

Identity	Support
User	Yes
Entidade de serviço e identidades geridas	Yes

Interface

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

Com parâmetros opcionais:

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

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
itemId	path	True	string (uuid)	A ID do item Malha para colocar as funções.
workspaceId	path	True	string (uuid)	O ID do espaço de trabalho.
dryRun	query		boolean	Usado para disparar uma execução seca da chamada de API. True - A chamada de API acionará uma execução seca e nenhuma função será alterada. Falso - Não acionará uma execução seca e as funções serão atualizadas.

Cabeçalho do Pedido

Name	Necessário	Tipo	Description
If-Match		string	Um valor ETag. O ETag deve ser especificado entre aspas. Se fornecida, a chamada só terá êxito se a ETag do recurso corresponder à ETag fornecida.
If-None-Match		string	Um valor ETag. O ETag deve ser especificado entre aspas. Se fornecida, a chamada só terá êxito se a ETag do recurso não corresponder à ETag fornecida.

Corpo do Pedido

Name	Tipo	Description
value	DataAccessRole[]	Uma lista de funções que são usadas para gerenciar a segurança de acesso a dados e garantir que apenas usuários autorizados possam exibir determinados dados. Uma função representa um conjunto de permissões e escopos de permissão que definem quais ações seus membros têm permissão para executar para os dados no escopo. Os membros são usuários ou grupos aos quais foi concedida a função e podem ler os dados com base nas permissões atribuídas à função. Por exemplo, um membro pode ser um grupo de ID do Microsoft Entra e o escopo de permissão pode ser uma Ação de Leitura aplicada no Caminho para Arquivo, Pasta(s) ou Tabela(s) no OneLake.

Respostas

Name	Tipo	Description
200 OK		Pedido concluído com sucesso. Cabeçalhos Etag: string
Other Status Codes	ErrorResponse	Códigos de erro comuns: ItemNotFound - Indica que o servidor não consegue encontrar o item solicitado. PreconditionFailed -Indicates que o recurso atual ETag não corresponde ao valor especificado no cabeçalho If-Match.

Name

Tipo

Description

200 OK

Pedido concluído com sucesso.

Cabeçalhos

Etag: string

Other Status Codes

ErrorResponse

Códigos de erro comuns:

ItemNotFound - Indica que o servidor não consegue encontrar o item solicitado.
PreconditionFailed -Indicates que o recurso atual ETag não corresponde ao valor especificado no cabeçalho If-Match.

Exemplos

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

Pedido de amostra

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"
          }
        ]
      }
    }
  ]
}

Resposta da amostra

Código de estado:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with constraints example

Pedido de amostra

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"
          }
        ]
      }
    }
  ]
}

Resposta da amostra

Código de estado:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with tables path example

Pedido de amostra

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"
          }
        ]
      }
    }
  ]
}

Resposta da amostra

Código de estado:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d5

Definições

Name	Description
AttributeName	Especifica o nome do atributo que está sendo avaliado para permissões de acesso. AttributeName pode ser `Path` ou `Action`. Tipos adicionais de attributeName podem ser adicionados ao longo do tempo.
ColumnAction	A matriz de ações aplicadas a columnNames. Isso determina quais ações um usuário poderá executar em colunas. Os valores permitidos são: Ler. Tipos de colunaAção adicionais podem ser adicionados ao longo do tempo.
ColumnConstraint	ColumnConstraint indica uma restrição que determina as permissões e a visibilidade que um usuário tem nas colunas de uma tabela.
ColumnEffect	O efeito dado à columnNames. O único valor permitido é Permit. Tipos columnEffect adicionais podem ser adicionados ao longo do tempo.
Constraints	Quaisquer restrições, como segurança em nível de linha ou coluna, que são aplicadas a tabelas como parte dessa função. Se não estiver incluído, nenhuma restrição se aplicará a quaisquer tabelas na função.
CreateOrUpdateDataAccessRolesRequest	Contém a definição de Funções que são usadas para gerenciar a segurança de acesso a dados e garantir que apenas usuários autorizados possam exibir, editar ou excluir determinados dados. Chamar essa API atualiza as definições de função e cria, atualiza ou exclui funções para corresponder à carga útil fornecida.
DataAccessRole	Uma função de acesso a dados representa um conjunto de permissões e escopos de permissão que definem quais ações seus membros têm permissão para executar para os dados no escopo. As funções de acesso a dados são usadas para gerenciar a segurança de acesso a dados e garantir que apenas usuários autorizados possam visualizar, editar ou excluir determinados dados. Os membros são usuários ou grupos aos quais foi concedida a função e podem ler os dados com base nas permissões atribuídas à função. Por exemplo, um membro pode ser um grupo de ID do Microsoft Entra e o escopo de permissão pode ser uma Ação de Leitura aplicada no Caminho para Arquivo, Pasta(s) ou Tabela(s) no OneLake.
DecisionRule	Especifica uma regra para corresponder à ação solicitada. Contém efeito (Permit) e Permission que determinam se um usuário ou entidade está autorizado a executar uma ação específica (por exemplo, ler) em um recurso. Permissão é um conjunto de escopos, definidos por atributos, que devem corresponder à ação solicitada para que a regra seja aplicada.
Effect	O efeito que uma função tem no acesso ao recurso de dados. Atualmente, o único tipo de efeito suportado é o `Permit`, que concede acesso ao recurso. Podem ser adicionados tipos de efeitos adicionais ao longo do tempo.
ErrorRelatedResource	O objeto de detalhes do recurso relacionado ao erro.
ErrorResponse	A resposta de erro.
ErrorResponseDetails	Os detalhes da resposta de erro.
FabricItemMember	Membro do item de malha.
ItemAccess	Uma lista especificando as permissões de acesso para o usuário do Fabric que devem ser incluídas automaticamente nos membros da função. Tipos adicionais de itemAccess podem ser adicionados ao longo do tempo.
Members	O objeto members, que contém os membros da função como matrizes de diferentes tipos de membros.
MicrosoftEntraMember	Membro do ID do Microsoft Entra atribuído à função.
ObjectType	O tipo de objeto ID do Microsoft Entra. Tipos de objectType adicionais podem ser adicionados ao longo do tempo.
PermissionScope	Define um conjunto de atributos (propriedades) que determinam o escopo e o nível de acesso a um recurso. Quando `attributeName` propriedade é definida como `Path`, a propriedade `attributeValueIncludedIn` deve especificar o local do recurso que está sendo acessado, como "Tabelas/Tabela1". Quando a propriedade `attributeName` é definida como `Action`, a propriedade `attributeValueIncludedIn` deve especificar o tipo de acesso que está sendo concedido, como `Read`.
RowConstraint	RowConstraint indica uma restrição que determina as linhas em uma tabela que os usuários podem ver. As funções definidas com RowConstraints usam T-SQL para definir um predicado que filtra dados em uma tabela. As linhas que não atendem às condições do predicado são filtradas, deixando um subconjunto das linhas originais. RowConstraints também pode ser usado para especificar sabores dinâmicos e de várias tabelas de RLS usando T-SQL.

AttributeName

Enumeração

Especifica o nome do atributo que está sendo avaliado para permissões de acesso. AttributeName pode ser Path ou Action. Tipos adicionais de attributeName podem ser adicionados ao longo do tempo.

Valor	Description
Path	Nome do atributo Caminho
Action	Nome do atributo Ação

ColumnAction

Enumeração

A matriz de ações aplicadas a columnNames. Isso determina quais ações um usuário poderá executar em colunas. Os valores permitidos são: Ler. Tipos de colunaAção adicionais podem ser adicionados ao longo do tempo.

Valor	Description
Read	O valor ColumnAction Read

ColumnConstraint

Object

ColumnConstraint indica uma restrição que determina as permissões e a visibilidade que um usuário tem nas colunas de uma tabela.

Name	Tipo	Description
columnAction	ColumnAction[]	A matriz de ações aplicadas a columnNames. Isso determina quais ações um usuário poderá executar em colunas. Os valores permitidos são: Ler. Tipos de colunaAção adicionais podem ser adicionados ao longo do tempo.
columnEffect	ColumnEffect	O efeito dado à columnNames. O único valor permitido é Permit. Tipos columnEffect adicionais podem ser adicionados ao longo do tempo.
columnNames	string[]	Uma matriz de nomes de colunas que diferenciam maiúsculas de minúsculas. Cada valor é um nome de coluna da tabela especificada em `tablePath`. Use estas colunas com `columnEffect` e `columnAction`. As colunas que não estão listadas obtêm o valor padrão nulo. Use `*` para indicar todas as colunas na tabela.
tablePath	string	Um caminho de arquivo relativo especificando a qual tabela a restrição de coluna se aplica. Tal deve assumir a forma de `/Tables/{optionalSchema}/{tableName}`. Apenas um valor pode ser dado aqui e o tableName deve ser uma tabela incluída no PermissionScope.

ColumnEffect

Enumeração

O efeito dado à columnNames. O único valor permitido é Permit. Tipos columnEffect adicionais podem ser adicionados ao longo do tempo.

Valor	Description
Permit	A permissão do tipo ColumnEffect

Constraints

Object

Quaisquer restrições, como segurança em nível de linha ou coluna, que são aplicadas a tabelas como parte dessa função. Se não estiver incluído, nenhuma restrição se aplicará a quaisquer tabelas na função.

Name	Tipo	Description
columns	ColumnConstraint[]	A matriz de restrições de coluna aplicadas a uma ou mais tabelas na função de acesso a dados.
rows	RowConstraint[]	A matriz de restrições de linha aplicadas a uma ou mais tabelas na função de acesso a dados.

CreateOrUpdateDataAccessRolesRequest

Object

Contém a definição de Funções que são usadas para gerenciar a segurança de acesso a dados e garantir que apenas usuários autorizados possam exibir, editar ou excluir determinados dados. Chamar essa API atualiza as definições de função e cria, atualiza ou exclui funções para corresponder à carga útil fornecida.

Name	Tipo	Description
value	DataAccessRole[]	Uma lista de funções que são usadas para gerenciar a segurança de acesso a dados e garantir que apenas usuários autorizados possam exibir determinados dados. Uma função representa um conjunto de permissões e escopos de permissão que definem quais ações seus membros têm permissão para executar para os dados no escopo. Os membros são usuários ou grupos aos quais foi concedida a função e podem ler os dados com base nas permissões atribuídas à função. Por exemplo, um membro pode ser um grupo de ID do Microsoft Entra e o escopo de permissão pode ser uma Ação de Leitura aplicada no Caminho para Arquivo, Pasta(s) ou Tabela(s) no OneLake.

DataAccessRole

Object

Uma função de acesso a dados representa um conjunto de permissões e escopos de permissão que definem quais ações seus membros têm permissão para executar para os dados no escopo. As funções de acesso a dados são usadas para gerenciar a segurança de acesso a dados e garantir que apenas usuários autorizados possam visualizar, editar ou excluir determinados dados. Os membros são usuários ou grupos aos quais foi concedida a função e podem ler os dados com base nas permissões atribuídas à função. Por exemplo, um membro pode ser um grupo de ID do Microsoft Entra e o escopo de permissão pode ser uma Ação de Leitura aplicada no Caminho para Arquivo, Pasta(s) ou Tabela(s) no OneLake.

Name	Tipo	Description
decisionRules	DecisionRule[]	A matriz de permissões que compõem a função de acesso a dados.
id	string (uuid)	A ID exclusiva para a função de acesso a dados.
members	Members	O objeto members, que contém os membros da função como matrizes de diferentes tipos de membros.
name	string	O nome da função de acesso a dados.

DecisionRule

Object

Especifica uma regra para corresponder à ação solicitada. Contém efeito (Permit) e Permission que determinam se um usuário ou entidade está autorizado a executar uma ação específica (por exemplo, ler) em um recurso. Permissão é um conjunto de escopos, definidos por atributos, que devem corresponder à ação solicitada para que a regra seja aplicada.

Name	Tipo	Description
constraints	Constraints	Quaisquer restrições, como segurança em nível de linha ou coluna, que são aplicadas a tabelas como parte dessa função. Se não estiver incluído, nenhuma restrição se aplicará a quaisquer tabelas na função.
effect	Effect	O efeito que uma função tem no acesso ao recurso de dados. Atualmente, o único tipo de efeito suportado é o `Permit`, que concede acesso ao recurso. Podem ser adicionados tipos de efeitos adicionais ao longo do tempo.
permission	PermissionScope[]	A propriedade `permission` é uma matriz que especifica o escopo e o nível de acesso para uma ação solicitada. A matriz deve conter exatamente dois objetos PermissionScope: `Path` e `Action`. O `scope` é definido usando o objeto `PermissionScope`, com `attributeValueIncludedIn` especificando o local do recurso que está sendo acessado ou o tipo de ação que está sendo concedida. O `access` refere-se ao nível de acesso que está sendo concedido, como `Read`.

Effect

Enumeração

O efeito que uma função tem no acesso ao recurso de dados. Atualmente, o único tipo de efeito suportado é o Permit, que concede acesso ao recurso. Podem ser adicionados tipos de efeitos adicionais ao longo do tempo.

Valor	Description
Permit	o tipo de efeito Licença

ErrorRelatedResource

Object

O objeto de detalhes do recurso relacionado ao erro.

Name	Tipo	Description
resourceId	string	A ID do recurso envolvida no erro.
resourceType	string	O tipo de recurso envolvido no erro.

ErrorResponse

Object

A resposta de erro.

Name	Tipo	Description
errorCode	string	Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
message	string	Uma representação legível por humanos do erro.
moreDetails	ErrorResponseDetails[]	Lista de detalhes de erro adicionais.
relatedResource	ErrorRelatedResource	Os detalhes do recurso relacionados ao erro.
requestId	string	ID da solicitação associada ao erro.

ErrorResponseDetails

Object

Os detalhes da resposta de erro.

Name	Tipo	Description
errorCode	string	Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
message	string	Uma representação legível por humanos do erro.
relatedResource	ErrorRelatedResource	Os detalhes do recurso relacionados ao erro.

FabricItemMember

Object

Membro do item de malha.

Name	Tipo	Description
itemAccess	ItemAccess[]	Uma lista especificando as permissões de acesso para o usuário do Fabric que devem ser incluídas automaticamente nos membros da função. Tipos adicionais de itemAccess podem ser adicionados ao longo do tempo.
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}[}]?$	O caminho para o item de malha com acesso ao item especificado.

ItemAccess

Enumeração

Uma lista especificando as permissões de acesso para o usuário do Fabric que devem ser incluídas automaticamente nos membros da função. Tipos adicionais de itemAccess podem ser adicionados ao longo do tempo.

Valor	Description
Read	Acesso ao item Leitura.
Write	Gravação de acesso ao item.
Reshare	Recompartilhamento de acesso ao item.
Explore	Acesso ao Item Explorar.
Execute	Acesso ao item Executar.
ReadAll	Acesso ao item ReadAll.

Members

Object

O objeto members, que contém os membros da função como matrizes de diferentes tipos de membros.

Name	Tipo	Description
fabricItemMembers	FabricItemMember[]	Uma lista de membros que têm um determinado conjunto de permissões no Microsoft Fabric. Todos os membros com esse conjunto de permissões são adicionados como membros desta Função de Acesso a Dados.
microsoftEntraMembers	MicrosoftEntraMember[]	A lista de membros do Microsoft Entra ID.

MicrosoftEntraMember

Object

Membro do ID do Microsoft Entra atribuído à função.

Name	Tipo	Description
objectId	string (uuid)	A id do objeto.
objectType	ObjectType	O tipo de objeto ID do Microsoft Entra. Tipos de objectType adicionais podem ser adicionados ao longo do tempo.
tenantId	string (uuid)	O ID do inquilino.

ObjectType

Enumeração

O tipo de objeto ID do Microsoft Entra. Tipos de objectType adicionais podem ser adicionados ao longo do tempo.

Valor	Description
Group	Grupo de nomes de atributos
User	Nome do atributo Usuário
ServicePrincipal	Nome do atributo ServicePrincipal
ManagedIdentity	Nome do atributo ManagedIdentity

PermissionScope

Object

Define um conjunto de atributos (propriedades) que determinam o escopo e o nível de acesso a um recurso. Quando attributeName propriedade é definida como Path, a propriedade attributeValueIncludedIn deve especificar o local do recurso que está sendo acessado, como "Tabelas/Tabela1". Quando a propriedade attributeName é definida como Action, a propriedade attributeValueIncludedIn deve especificar o tipo de acesso que está sendo concedido, como Read.

Name	Tipo	Description
attributeName	AttributeName	Especifica o nome do atributo que está sendo avaliado para permissões de acesso. AttributeName pode ser `Path` ou `Action`. Tipos adicionais de attributeName podem ser adicionados ao longo do tempo.
attributeValueIncludedIn	string[]	Especifica uma lista de valores para o `attributeName` definir o escopo e o nível de acesso a um recurso. Quando `attributeName` é `Path`, `attributeValueIncludedIn` deve especificar o local do recurso que está sendo acessado, como "Tabelas/Tabela1". Quando `attributeName` é `Action`, o `attributeValueIncludedIn` deve especificar o tipo de acesso que está sendo concedido, como `Read`.

RowConstraint

Object

RowConstraint indica uma restrição que determina as linhas em uma tabela que os usuários podem ver. As funções definidas com RowConstraints usam T-SQL para definir um predicado que filtra dados em uma tabela. As linhas que não atendem às condições do predicado são filtradas, deixando um subconjunto das linhas originais. RowConstraints também pode ser usado para especificar sabores dinâmicos e de várias tabelas de RLS usando T-SQL.

Name	Tipo	Description
tablePath	string	Um caminho de arquivo relativo especificando a qual tabela a restrição de linha se aplica. Tal deve assumir a forma de `/Tables/{optionalSchema}/{tableName}`. Apenas um valor pode ser dado aqui e o tableName deve ser uma tabela incluída no PermissionScope.
value	string	Uma expressão T-SQL que é usada para avaliar quais linhas os membros da função podem ver. Apenas um subconjunto de T-SQL pode ser usado como predicado.

Partilhar via

OneLake Data Access Security - Create Or Update Data Access Roles

Escopos delegados necessários

Identidades suportadas pelo Microsoft Entra

Interface

Parâmetros do URI

Cabeçalho do Pedido

Corpo do Pedido

Respostas

Exemplos

Create or update data access roles example

Pedido de amostra

Resposta da amostra

Create or update data access roles with constraints example

Pedido de amostra

Resposta da amostra

Create or update data access roles with tables path example

Pedido de amostra

Resposta da amostra

Definições

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

CreateOrUpdateDataAccessRolesRequest

DataAccessRole

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint