OneLake Data Access Security - Create Or Update Single Data Access Role

Servizio:: Core

Versione API:: v1

Crea o aggiorna (upserts) un singolo ruolo di accesso ai dati.

Annotazioni

Questa API fa parte di una versione di anteprima e viene fornita solo a scopo di valutazione e sviluppo. Può cambiare in base al feedback e non è consigliato per l'uso in produzione.

Quando si chiama questa API, i chiamanti devono specificare true come valore per il parametro previewdi query .

Permissions

Il chiamante deve avere un ruolo membro o superiore nell'area di lavoro.

Ambiti delegati obbligatori

OneLake.ReadWrite.All

Identità supportate da Microsoft Entra

Questa API supporta le identità di Microsoft elencate in questa sezione.

Identità	Support
User	Yes
Principale del servizio e Identità gestite	Yes

Interfaccia

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

Con parametri facoltativi:

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
itemId	path	True	string (uuid)	ID dell'elemento Fabric in cui creare o aggiornare il ruolo.
workspaceId	path	True	string (uuid)	L’ID dell’area di lavoro.
dataAccessRoleConflictPolicy	query		DataAccessRoleConflictPolicy	Determina il comportamento quando sono presenti assegnazioni di ruolo di accesso ai dati in conflitto. Sovrascrivere significa che le nuove assegnazioni sostituiscono quelle esistenti. Interruzione indica che l'operazione ha esito negativo in caso di conflitti. È possibile aggiungere altri tipi dataAccessRoleConflictPolicy nel tempo.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
If-Match		string	Un valore ETag. L'ETag deve essere specificato tra virgolette. Se specificato, la chiamata avrà esito positivo solo se l'ETag della risorsa corrisponde all'ETag specificato.
If-None-Match		string	Un valore ETag. L'ETag deve essere specificato tra virgolette. Se specificato, la chiamata avrà esito positivo solo se l'ETag della risorsa non corrisponde all'ETag specificato.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
decisionRules	True	DecisionRule[]	Matrice di autorizzazioni che costituiscono il ruolo accesso ai dati.
name	True	string	Nome del ruolo accesso ai dati.
kind		DataAccessRoleKind	Tipo di ruolo accesso ai dati. Attualmente, l'unico tipo supportato è `Policy`. È possibile aggiungere tipi di tipi aggiuntivi nel tempo.
members		Members	Oggetto membri che contiene i membri del ruolo come matrici di tipi di membri diversi.

Risposte

Nome	Tipo	Descrizione
200 OK		Richiesta completata correttamente. Intestazioni ETag: string Location: string
201 Created		Ruolo creato correttamente. Intestazioni ETag: string Location: string
429 Too Many Requests	ErrorResponse	È stato superato il limite di velocità del servizio. Il server restituisce un'intestazione `Retry-After` che indica, in secondi, per quanto tempo il client deve attendere prima di inviare richieste aggiuntive. Intestazioni Retry-After: integer
Other Status Codes	ErrorResponse	Codici di errore comuni: ItemNotFound: indica che il server non riesce a trovare l'elemento richiesto. PrecondizioneFailed: indica che l'ETag della risorsa corrente non corrisponde al valore specificato nell'intestazione If-Match. Conflitto: sono presenti assegnazioni di ruolo in conflitto e i criteri di conflitto sono impostati su Interrompi.

Esempio

Create or update single data access role example

Esempio di richiesta

HTTP

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

{
  "name": "DefaultReader",
  "kind": "Policy",
  "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"
      }
    ]
  }
}

Risposta di esempio

Codice di stato:: 200

ETag: ccaa9212-0f33-4a42-ae8c-9de28f112222
Location: https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff222/items/25bac802-080d-4f73-8a42-1b406eb1fceb/dataAccessRoles/DefaultReader

Definizioni

Nome	Descrizione
AttributeName	Specifica il nome dell'attributo che viene valutato per le autorizzazioni di accesso. AttributeName può essere `Path` o `Action`. È possibile aggiungere altri tipi attributeName nel tempo.
ColumnAction	Matrice di azioni applicate ai columnNames. Determina le azioni che un utente potrà eseguire sulle colonne. I valori consentiti sono: Lettura. È possibile aggiungere altri tipi columnAction nel tempo.
ColumnConstraint	ColumnConstraint indica un vincolo che determina le autorizzazioni e la visibilità di un utente sulle colonne all'interno di una tabella.
ColumnEffect	Effetto assegnato a columnNames. L'unico valore consentito è Permit. È possibile aggiungere altri tipi columnEffect nel tempo.
Constraints	Qualsiasi vincolo, ad esempio la sicurezza a livello di riga o colonna applicata alle tabelle come parte di questo ruolo. Se non è incluso, nessun vincolo si applica ad alcuna tabella nel ruolo.
DataAccessRoleBase	Oggetto ruolo di accesso ai dati di base usato per le operazioni a ruolo singolo (non include ID). Rappresenta un set di autorizzazioni e ambiti di autorizzazione che definiscono le azioni consentite per i dati con ambito.
DataAccessRoleConflictPolicy	Determina il comportamento quando sono presenti assegnazioni di ruolo di accesso ai dati in conflitto. Sovrascrivere significa che le nuove assegnazioni sostituiscono quelle esistenti. Interruzione indica che l'operazione ha esito negativo in caso di conflitti. È possibile aggiungere altri tipi dataAccessRoleConflictPolicy nel tempo.
DataAccessRoleKind	Tipo di ruolo accesso ai dati. Attualmente, l'unico tipo supportato è `Policy`. È possibile aggiungere tipi di tipi aggiuntivi nel tempo.
DecisionRule	Specifica una regola per la corrispondenza dell'azione richiesta. Contiene l'effetto (permesso) e l'autorizzazione che determinano se un utente o un'entità è autorizzata a eseguire un'azione specifica (ad esempio, leggere) su una risorsa. L'autorizzazione è un set di ambiti, definiti dagli attributi, che devono corrispondere all'azione richiesta per l'applicazione della regola.
Effect	Effetto che un ruolo ha sull'accesso alla risorsa dati. Attualmente, l'unico tipo di effetto supportato è `Permit`, che concede l'accesso alla risorsa. È possibile aggiungere altri tipi di effetto nel tempo.
ErrorRelatedResource	Oggetto dettagli risorsa correlato all'errore.
ErrorResponse	Risposta di errore.
ErrorResponseDetails	Dettagli della risposta di errore.
FabricItemMember	Membro dell'elemento dell'infrastruttura.
ItemAccess	Elenco che specifica le autorizzazioni di accesso per l'utente di Fabric da includere automaticamente nei membri del ruolo. È possibile aggiungere altri tipi itemAccess nel corso del tempo.
Members	Oggetto membri che contiene i membri del ruolo come matrici di tipi di membri diversi.
MicrosoftEntraMember	Membro MICROSOFT Entra ID assegnato al ruolo.
ObjectType	Tipo di oggetto MICROSOFT Entra ID. È possibile aggiungere altri tipi objectType nel tempo.
PermissionScope	Definisce un set di attributi (proprietà) che determinano l'ambito e il livello di accesso a una risorsa. Quando `attributeName` proprietà è impostata su `Path`, la proprietà `attributeValueIncludedIn` deve specificare il percorso della risorsa a cui si accede, ad esempio "Tables/Table1". Quando la proprietà `attributeName` è impostata su `Action`, la proprietà `attributeValueIncludedIn` deve specificare il tipo di accesso concesso, ad esempio `Read`.
RowConstraint	RowConstraint indica un vincolo che determina le righe di una tabella che gli utenti possono visualizzare. I ruoli definiti con RowConstraints usano T-SQL per definire un predicato che filtra i dati in una tabella. Le righe che non soddisfano le condizioni del predicato vengono filtrate, lasciando un subset delle righe originali. RowConstraints può essere usato anche per specificare versioni dinamiche e multi-tabella di sicurezza a livello di riga tramite T-SQL.

AttributeName

Enumerazione

Specifica il nome dell'attributo che viene valutato per le autorizzazioni di accesso. AttributeName può essere Path o Action. È possibile aggiungere altri tipi attributeName nel tempo.

Valore	Descrizione
Path	Percorso nome attributo
Action	Azione nome attributo

ColumnAction

Enumerazione

Matrice di azioni applicate ai columnNames. Determina le azioni che un utente potrà eseguire sulle colonne. I valori consentiti sono: Lettura. È possibile aggiungere altri tipi columnAction nel tempo.

Valore	Descrizione
Read	Valore ColumnAction Letto

ColumnConstraint

Oggetto

ColumnConstraint indica un vincolo che determina le autorizzazioni e la visibilità di un utente sulle colonne all'interno di una tabella.

Nome	Tipo	Descrizione
columnAction	ColumnAction[]	Matrice di azioni applicate ai columnNames. Determina le azioni che un utente potrà eseguire sulle colonne. I valori consentiti sono: Lettura. È possibile aggiungere altri tipi columnAction nel tempo.
columnEffect	ColumnEffect	Effetto assegnato a columnNames. L'unico valore consentito è Permit. È possibile aggiungere altri tipi columnEffect nel tempo.
columnNames	string[]	Matrice di nomi di colonna con distinzione tra maiuscole e minuscole. Ogni valore è un nome di colonna della tabella specificata in `tablePath`. Usare queste colonne con `columnEffect` e `columnAction`. Le colonne non elencate ottengono il valore predefinito Null. Utilizzare `*` per indicare tutte le colonne della tabella.
tablePath	string	Percorso di file relativo che specifica la tabella a cui si applica il vincolo di colonna. Deve essere nel formato .`/Tables/{optionalSchema}/{tableName}` In questo caso è possibile specificare un solo valore e tableName deve essere una tabella inclusa in PermissionScope.

ColumnEffect

Enumerazione

Effetto assegnato a columnNames. L'unico valore consentito è Permit. È possibile aggiungere altri tipi columnEffect nel tempo.

Valore	Descrizione
Permit	Tipo ColumnEffect Permit

Constraints

Oggetto

Qualsiasi vincolo, ad esempio la sicurezza a livello di riga o colonna applicata alle tabelle come parte di questo ruolo. Se non è incluso, nessun vincolo si applica ad alcuna tabella nel ruolo.

Nome	Tipo	Descrizione
columns	ColumnConstraint[]	Matrice di vincoli di colonna applicati a una o più tabelle nel ruolo di accesso ai dati.
rows	RowConstraint[]	Matrice di vincoli di riga applicati a una o più tabelle nel ruolo di accesso ai dati.

DataAccessRoleBase

Oggetto

Oggetto ruolo di accesso ai dati di base usato per le operazioni a ruolo singolo (non include ID). Rappresenta un set di autorizzazioni e ambiti di autorizzazione che definiscono le azioni consentite per i dati con ambito.

Nome	Tipo	Descrizione
decisionRules	DecisionRule[]	Matrice di autorizzazioni che costituiscono il ruolo accesso ai dati.
kind	DataAccessRoleKind	Tipo di ruolo accesso ai dati. Attualmente, l'unico tipo supportato è `Policy`. È possibile aggiungere tipi di tipi aggiuntivi nel tempo.
members	Members	Oggetto membri che contiene i membri del ruolo come matrici di tipi di membri diversi.
name	string	Nome del ruolo accesso ai dati.

DataAccessRoleConflictPolicy

Enumerazione

Determina il comportamento quando sono presenti assegnazioni di ruolo di accesso ai dati in conflitto. Sovrascrivere significa che le nuove assegnazioni sostituiscono quelle esistenti. Interruzione indica che l'operazione ha esito negativo in caso di conflitti. È possibile aggiungere altri tipi dataAccessRoleConflictPolicy nel tempo.

Valore	Descrizione
Overwrite	Creare un nuovo ruolo o sovrascrivere un ruolo esistente con la definizione specificata.
Abort	Interrompere l'operazione quando si verifica un conflitto con un ruolo esistente.

DataAccessRoleKind

Enumerazione

Tipo di ruolo accesso ai dati. Attualmente, l'unico tipo supportato è Policy. È possibile aggiungere tipi di tipi aggiuntivi nel tempo.

Valore	Descrizione
Policy	Ruolo di accesso ai dati basato su criteri.

DecisionRule

Oggetto

Specifica una regola per la corrispondenza dell'azione richiesta. Contiene l'effetto (permesso) e l'autorizzazione che determinano se un utente o un'entità è autorizzata a eseguire un'azione specifica (ad esempio, leggere) su una risorsa. L'autorizzazione è un set di ambiti, definiti dagli attributi, che devono corrispondere all'azione richiesta per l'applicazione della regola.

Nome	Tipo	Descrizione
constraints	Constraints	Qualsiasi vincolo, ad esempio la sicurezza a livello di riga o colonna applicata alle tabelle come parte di questo ruolo. Se non è incluso, nessun vincolo si applica ad alcuna tabella nel ruolo.
effect	Effect	Effetto che un ruolo ha sull'accesso alla risorsa dati. Attualmente, l'unico tipo di effetto supportato è `Permit`, che concede l'accesso alla risorsa. È possibile aggiungere altri tipi di effetto nel tempo.
permission	PermissionScope[]	La proprietà `permission` è una matrice che specifica l'ambito e il livello di accesso per un'azione richiesta. La matrice deve contenere esattamente due oggetti PermissionScope: `Path` e `Action`. Il `scope` viene definito usando l'oggetto `PermissionScope`, con `attributeValueIncludedIn` specificando la posizione della risorsa a cui si accede o il tipo di azione concessa. Il `access` fa riferimento al livello di accesso concesso, ad esempio `Read`.

Effect

Enumerazione

Effetto che un ruolo ha sull'accesso alla risorsa dati. Attualmente, l'unico tipo di effetto supportato è Permit, che concede l'accesso alla risorsa. È possibile aggiungere altri tipi di effetto nel tempo.

Valore	Descrizione
Permit	tipo di effetto Permit

ErrorRelatedResource

Oggetto

Oggetto dettagli risorsa correlato all'errore.

Nome	Tipo	Descrizione
resourceId	string	ID risorsa coinvolto nell'errore.
resourceType	string	Tipo della risorsa coinvolta nell'errore.

ErrorResponse

Oggetto

Risposta di errore.

Nome	Tipo	Descrizione
errorCode	string	Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
message	string	Rappresentazione leggibile dell'errore.
moreDetails	ErrorResponseDetails[]	Elenco di dettagli aggiuntivi sull'errore.
relatedResource	ErrorRelatedResource	Dettagli della risorsa correlati all'errore.
requestId	string (uuid)	ID della richiesta associata all'errore.

ErrorResponseDetails

Oggetto

Dettagli della risposta di errore.

Nome	Tipo	Descrizione
errorCode	string	Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
message	string	Rappresentazione leggibile dell'errore.
relatedResource	ErrorRelatedResource	Dettagli della risorsa correlati all'errore.

FabricItemMember

Oggetto

Membro dell'elemento dell'infrastruttura.

Nome	Tipo	Descrizione
itemAccess	ItemAccess[]	Elenco che specifica le autorizzazioni di accesso per l'utente di Fabric da includere automaticamente nei membri del ruolo. È possibile aggiungere altri tipi itemAccess nel corso del 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}[}]?$	Percorso dell'elemento Fabric con accesso all'elemento specificato.

ItemAccess

Enumerazione

Elenco che specifica le autorizzazioni di accesso per l'utente di Fabric da includere automaticamente nei membri del ruolo. È possibile aggiungere altri tipi itemAccess nel corso del tempo.

Valore	Descrizione
Read	Accesso elemento in lettura.
Write	Scrittura accesso elementi.
Reshare	Ricondividi accesso all'elemento.
Explore	Esplora accesso elementi.
Execute	Esecuzione dell'accesso all'elemento.
ReadAll	Accesso all'elemento ReadAll.

Members

Oggetto

Oggetto membri che contiene i membri del ruolo come matrici di tipi di membri diversi.

Nome	Tipo	Descrizione
fabricItemMembers	FabricItemMember[]	Elenco di membri che dispongono di un determinato set di autorizzazioni in Microsoft Fabric. Tutti i membri con tale set di autorizzazioni vengono aggiunti come membri di questo ruolo di accesso ai dati.
microsoftEntraMembers	MicrosoftEntraMember[]	Elenco dei membri di Microsoft Entra ID.

MicrosoftEntraMember

Oggetto

Membro MICROSOFT Entra ID assegnato al ruolo.

Nome	Tipo	Descrizione
objectId	string (uuid)	ID oggetto.
objectType	ObjectType	Tipo di oggetto MICROSOFT Entra ID. È possibile aggiungere altri tipi objectType nel tempo.
tenantId	string (uuid)	ID tenant.

ObjectType

Enumerazione

Tipo di oggetto MICROSOFT Entra ID. È possibile aggiungere altri tipi objectType nel tempo.

Valore	Descrizione
Group	Gruppo nome attributo
User	Nome attributo Utente
ServicePrincipal	Nome attributo ServicePrincipal
ManagedIdentity	Nome attributo ManagedIdentity

PermissionScope

Oggetto

Definisce un set di attributi (proprietà) che determinano l'ambito e il livello di accesso a una risorsa. Quando attributeName proprietà è impostata su Path, la proprietà attributeValueIncludedIn deve specificare il percorso della risorsa a cui si accede, ad esempio "Tables/Table1". Quando la proprietà attributeName è impostata su Action, la proprietà attributeValueIncludedIn deve specificare il tipo di accesso concesso, ad esempio Read.

Nome	Tipo	Descrizione
attributeName	AttributeName	Specifica il nome dell'attributo che viene valutato per le autorizzazioni di accesso. AttributeName può essere `Path` o `Action`. È possibile aggiungere altri tipi attributeName nel tempo.
attributeValueIncludedIn	string[]	Specifica un elenco di valori per il `attributeName` per definire l'ambito e il livello di accesso a una risorsa. Quando `attributeName` è `Path`, `attributeValueIncludedIn` deve specificare il percorso della risorsa a cui si accede, ad esempio "Tabelle/Table1". Quando `attributeName` è `Action`, il `attributeValueIncludedIn` deve specificare il tipo di accesso concesso, ad esempio `Read`.

RowConstraint

Oggetto

RowConstraint indica un vincolo che determina le righe di una tabella che gli utenti possono visualizzare. I ruoli definiti con RowConstraints usano T-SQL per definire un predicato che filtra i dati in una tabella. Le righe che non soddisfano le condizioni del predicato vengono filtrate, lasciando un subset delle righe originali. RowConstraints può essere usato anche per specificare versioni dinamiche e multi-tabella di sicurezza a livello di riga tramite T-SQL.

Nome	Tipo	Descrizione
tablePath	string	Percorso di file relativo che specifica la tabella a cui si applica il vincolo di riga. Deve essere nel formato .`/Tables/{optionalSchema}/{tableName}` In questo caso è possibile specificare un solo valore e tableName deve essere una tabella inclusa in PermissionScope.
value	string	Espressione T-SQL usata per valutare le righe che i membri del ruolo possono visualizzare. È possibile usare solo un subset di T-SQL come predicato.

Condividi tramite

OneLake Data Access Security - Create Or Update Single Data Access Role

Permissions

Ambiti delegati obbligatori

Identità supportate da Microsoft Entra

Interfaccia

Parametri dell'URI

Intestazione della richiesta

Corpo della richiesta

Risposte

Esempio

Create or update single data access role example

Esempio di richiesta

Risposta di esempio

Definizioni

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

DataAccessRoleBase

DataAccessRoleConflictPolicy

DataAccessRoleKind

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint