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

Essa API faz parte de uma versão prévia e é fornecida apenas para fins de avaliação e desenvolvimento. Ele pode mudar com base nos comentários e não é recomendado para uso em produção.

Escopos delegados necessários

OneLake.ReadWrite.All

Identidades com suporte do Microsoft Entra

Esta API dá suporte às identidades do Microsoft listadas nesta seção.

Identity	Support
User	Yes
Entidade de serviço e identidades gerenciadas	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 de URI

Nome	Em	Obrigatório	Tipo	Description
itemId	path	True	string (uuid)	A ID do item fabric para colocar as funções.
workspaceId	path	True	string (uuid)	O identificador do espaço de trabalho.
dryRun	query		boolean	Usado para disparar uma execução seca da chamada à API. True – a chamada à API disparará uma execução seca e nenhuma função será alterada. False - Não disparará uma execução seca e as funções serão atualizadas.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
If-Match		string	Um valor ETag. A ETag deve ser especificada entre aspas. Se fornecida, a chamada será bem-sucedida somente se a ETag do recurso corresponder à ETag fornecida.
If-None-Match		string	Um valor ETag. A ETag deve ser especificada entre aspas. Se fornecida, a chamada será bem-sucedida somente se a ETag do recurso não corresponder à ETag fornecida.

Corpo da solicitação

Nome	Tipo	Description
value	DataAccessRole[]	Uma lista de funções usadas para gerenciar a segurança de acesso a dados e garantir que somente 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 que receberam 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 do Microsoft Entra ID e o escopo de permissão pode ser uma Ação de Leitura aplicada no caminho para arquivo, pastas ou tabelas fornecidos no OneLake.

Respostas

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

Nome

Tipo

Description

200 OK

Solicitação concluída com êxito.

Cabeçalhos

Etag: string

Other Status Codes

ErrorResponse

Códigos de erro comuns:

ItemNotFound – Indica que o servidor não pode encontrar o item solicitado.
PreconditionFailed -Indicates que a ETag do recurso atual 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

Solicitação de exemplo

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 de exemplo

Código de status:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with constraints example

Solicitação de exemplo

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 de exemplo

Código de status:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with tables path example

Solicitação de exemplo

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 de exemplo

Código de status:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d5

Definições

Nome	Description
AttributeName	Especifica o nome do atributo que está sendo avaliado para permissões de acesso. AttributeName pode ser `Path` ou `Action`. Tipos de attributeName adicionais podem ser adicionados ao longo do tempo.
ColumnAction	A matriz de ações aplicadas aos columnNames. Isso determina quais ações um usuário poderá executar em colunas. Os valores permitidos são: Leitura. Tipos de columnAction 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 em colunas dentro de uma tabela.
ColumnEffect	O efeito dado aos columnNames. O único valor permitido é Permissão. Tipos de 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 nenhuma tabela na função.
CreateOrUpdateDataAccessRolesRequest	Contém a definição de funções usadas para gerenciar a segurança de acesso a dados e garantir que somente usuários autorizados possam exibir, editar ou excluir determinados dados. Chamar essa API atualiza definições de função e cria, atualiza ou exclui funções para corresponder ao conteúdo fornecido.
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 somente usuários autorizados possam exibir, editar ou excluir determinados dados. Os membros são usuários ou grupos que receberam 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 do Microsoft Entra ID e o escopo de permissão pode ser uma Ação de Leitura aplicada no caminho para arquivo, pastas ou tabelas fornecidos no OneLake.
DecisionRule	Especifica uma regra para corresponder à ação solicitada. Contém efeito (Permissão) e Permissão que determinam se um usuário ou entidade está autorizado a executar uma ação específica (por exemplo, leitura) em um recurso. A 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 sobre o acesso ao recurso de dados. Atualmente, o único tipo de efeito com suporte é `Permit`, que concede acesso ao recurso. Tipos de efeito adicionais podem ser adicionados 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 fabric.
ItemAccess	Uma lista que especifica as permissões de acesso para que o usuário do Fabric precise ser incluído automaticamente nos membros da função. Tipos de itemAccess adicionais 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 membro.
MicrosoftEntraMember	Membro da ID do Microsoft Entra atribuído à função.
ObjectType	O tipo de objeto da 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 tipos 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 de attributeName adicionais podem ser adicionados ao longo do tempo.

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

ColumnAction

Enumeração

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

Valor	Description
Read	O valor ColumnAction Read

ColumnConstraint

Objeto

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

Nome	Tipo	Description
columnAction	ColumnAction[]	A matriz de ações aplicadas aos columnNames. Isso determina quais ações um usuário poderá executar em colunas. Os valores permitidos são: Leitura. Tipos de columnAction adicionais podem ser adicionados ao longo do tempo.
columnEffect	ColumnEffect	O efeito dado aos columnNames. O único valor permitido é Permissão. Tipos de 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 essas 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 que especifica a qual tabela a restrição de coluna se aplica. Isso deve estar na forma de `/Tables/{optionalSchema}/{tableName}`. Somente um valor pode ser fornecido aqui e o tableName deve ser uma tabela incluída no PermissionScope.

ColumnEffect

Enumeração

O efeito dado aos columnNames. O único valor permitido é Permissão. Tipos de columnEffect adicionais podem ser adicionados ao longo do tempo.

Valor	Description
Permit	O tipo ColumnEffect Permit

Constraints

Objeto

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 nenhuma tabela na função.

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

CreateOrUpdateDataAccessRolesRequest

Objeto

Contém a definição de funções usadas para gerenciar a segurança de acesso a dados e garantir que somente usuários autorizados possam exibir, editar ou excluir determinados dados. Chamar essa API atualiza definições de função e cria, atualiza ou exclui funções para corresponder ao conteúdo fornecido.

Nome	Tipo	Description
value	DataAccessRole[]	Uma lista de funções usadas para gerenciar a segurança de acesso a dados e garantir que somente 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 que receberam 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 do Microsoft Entra ID e o escopo de permissão pode ser uma Ação de Leitura aplicada no caminho para arquivo, pastas ou tabelas fornecidos no OneLake.

DataAccessRole

Objeto

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 somente usuários autorizados possam exibir, editar ou excluir determinados dados. Os membros são usuários ou grupos que receberam 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 do Microsoft Entra ID e o escopo de permissão pode ser uma Ação de Leitura aplicada no caminho para arquivo, pastas ou tabelas fornecidos no OneLake.

Nome	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 membro.
name	string	O nome da função de acesso a dados.

DecisionRule

Objeto

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

Nome	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 nenhuma tabela na função.
effect	Effect	O efeito que uma função tem sobre o acesso ao recurso de dados. Atualmente, o único tipo de efeito com suporte é `Permit`, que concede acesso ao recurso. Tipos de efeito adicionais podem ser adicionados ao longo do tempo.
permission	PermissionScope[]	A propriedade `permission` é uma matriz que especifica o escopo e o nível de acesso de 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 sobre o acesso ao recurso de dados. Atualmente, o único tipo de efeito com suporte é Permit, que concede acesso ao recurso. Tipos de efeito adicionais podem ser adicionados ao longo do tempo.

Valor	Description
Permit	o tipo de efeito Permissão

ErrorRelatedResource

Objeto

O objeto de detalhes do recurso relacionado ao erro.

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

ErrorResponse

Objeto

A resposta de erro.

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

ErrorResponseDetails

Objeto

Os detalhes da resposta de erro.

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

FabricItemMember

Objeto

Membro do item fabric.

Nome	Tipo	Description
itemAccess	ItemAccess[]	Uma lista que especifica as permissões de acesso para que o usuário do Fabric precise ser incluído automaticamente nos membros da função. Tipos de itemAccess adicionais 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 fabric que tem o acesso de item especificado.

ItemAccess

Enumeração

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

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

Members

Objeto

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

Nome	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 dessa Função de Acesso a Dados.
microsoftEntraMembers	MicrosoftEntraMember[]	A lista de membros da ID do Microsoft Entra.

MicrosoftEntraMember

Objeto

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

Nome	Tipo	Description
objectId	string (uuid)	A ID do objeto.
objectType	ObjectType	O tipo de objeto da ID do Microsoft Entra. Tipos de objectType adicionais podem ser adicionados ao longo do tempo.
tenantId	string (uuid)	A ID do locatário.

ObjectType

Enumeração

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

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

PermissionScope

Objeto

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.

Nome	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 de attributeName adicionais podem ser adicionados ao longo do tempo.
attributeValueIncludedIn	string[]	Especifica uma lista de valores para o `attributeName` para 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

Objeto

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 tipos dinâmicos e de várias tabelas de RLS usando T-SQL.

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

Compartilhar via

OneLake Data Access Security - Create Or Update Data Access Roles

Escopos delegados necessários

Identidades com suporte do Microsoft Entra

Interface

Parâmetros de URI

Cabeçalho da solicitação

Corpo da solicitação

Respostas

Exemplos

Create or update data access roles example

Solicitação de exemplo

Resposta de exemplo

Create or update data access roles with constraints example

Solicitação de exemplo

Resposta de exemplo

Create or update data access roles with tables path example

Solicitação de exemplo

Resposta de exemplo

Definições

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

CreateOrUpdateDataAccessRolesRequest

DataAccessRole

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint