OneLake Data Access Security - Get Data Access Role

Dienst:: Core

API-Version:: v1

Gibt Datenzugriffsrollendetails für den angegebenen Rollennamen zurück.

Hinweis

Diese API ist Teil einer Preview-Version und wird nur für Evaluierungs- und Entwicklungszwecke bereitgestellt. Sie kann sich basierend auf Feedback ändern und wird nicht für den Produktionseinsatz empfohlen.

Beim Aufrufen dieser API müssen Aufrufer als Wert für den Abfrageparameter trueangebenpreview.

Erlaubnisse

Der Anrufer muss mitglied oder höher im Arbeitsbereich sein.

Erforderliche delegierte Bereiche

OneLake.Read.All oder OneLake.ReadWrite.All

Von Microsoft Entra unterstützte Identitäten

Diese API unterstützt die in diesem Abschnitt aufgeführten Microsoft Identitäten.

Identität	Support
Benutzer	Yes
Service Principal und Verwaltete Identitäten	Yes

Schnittstelle

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
itemId	path	True	string (uuid)	Die ID des Fabric-Elements, aus dem die Rolle abgerufen werden soll.
roleName	path	True	string	Der Name der abzurufenden Rolle.
workspaceId	path	True	string (uuid)	Die Arbeitsbereichs-ID.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
If-Match		string	Ein ETag-Wert. Das ETag muss in Anführungszeichen angegeben werden. Wenn angegeben, wird der Aufruf nur erfolgreich ausgeführt, wenn das ETag der Ressource mit dem bereitgestellten ETag übereinstimmt.
If-None-Match		string	Ein ETag-Wert. Das ETag muss in Anführungszeichen angegeben werden. Wenn angegeben, wird der Aufruf nur erfolgreich ausgeführt, wenn das ETag der Ressource nicht mit dem bereitgestellten ETag übereinstimmt.

Antworten

Name Typ Beschreibung

200 OK

Name	Typ	Beschreibung
200 OK	DataAccessRoleBase	Die Anforderung wurde erfolgreich abgeschlossen. Header ETag: string
429 Too Many Requests	ErrorResponse	Der Dienstratengrenzwert wurde überschritten. Der Server gibt einen `Retry-After` Header zurück, der in Sekunden angibt, wie lange der Client warten muss, bevor zusätzliche Anforderungen gesendet werden. Header Retry-After: integer
Other Status Codes	ErrorResponse	Häufige Fehlercodes: ItemNotFound – Gibt an, dass der Server das angeforderte Element nicht finden kann. RoleNotFound – Gibt an, dass die angegebene Rolle nicht gefunden wurde. PreconditionFailed - Gibt an, dass das aktuelle Ressourcen-ETag nicht mit dem wert übereinstimmt, der im If-Match-Header angegeben ist.

DataAccessRoleBase

Die Anforderung wurde erfolgreich abgeschlossen.

Header

ETag: string

429 Too Many Requests

ErrorResponse

Der Dienstratengrenzwert wurde überschritten. Der Server gibt einen Retry-After Header zurück, der in Sekunden angibt, wie lange der Client warten muss, bevor zusätzliche Anforderungen gesendet werden.

Header

Retry-After: integer

Other Status Codes

ErrorResponse

Häufige Fehlercodes:

ItemNotFound – Gibt an, dass der Server das angeforderte Element nicht finden kann.
RoleNotFound – Gibt an, dass die angegebene Rolle nicht gefunden wurde.
PreconditionFailed - Gibt an, dass das aktuelle Ressourcen-ETag nicht mit dem wert übereinstimmt, der im If-Match-Header angegeben ist.

Beispiele

Get data access role example

Beispielanforderung

HTTP

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

Beispiel für eine Antwort

Statuscode:: 200

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

{
  "name": "DefaultReader",
  "decisionRules": [
    {
      "effect": "Permit",
      "permission": [
        {
          "attributeName": "Path",
          "attributeValueIncludedIn": [
            "Tables/schema1",
            "Tables/schema2/TableB"
          ]
        },
        {
          "attributeName": "Action",
          "attributeValueIncludedIn": [
            "Read",
            "ReadWrite"
          ]
        }
      ],
      "constraints": {
        "columns": [
          {
            "tablePath": "Tables/schema1/TableB",
            "columnNames": [
              "*"
            ],
            "columnEffect": "Permit",
            "columnAction": [
              "Read"
            ]
          }
        ],
        "rows": [
          {
            "tablePath": "Tables/schema1/TableC",
            "value": "select * from [schema1].[TableC] where name = 'Aaron' AND country = 'USA'"
          }
        ]
      }
    }
  ],
  "members": {
    "fabricItemMembers": [
      {
        "sourcePath": "cfafbeb1-8037-4d0c-896e-a46fb27ff222/25bac802-080d-4f73-8a42-1b406eb1fceb",
        "itemAccess": [
          "ReadAll"
        ]
      }
    ],
    "microsoftEntraMembers": [
      {
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
        "objectId": "EAF3B3B8-524A-4EC6-A96F-3340748DF869"
      }
    ]
  }
}

Definitionen

Name	Beschreibung
AttributeName	Gibt den Namen des Attributs an, das für Zugriffsberechtigungen ausgewertet wird. Attributname kann `Path` oder `Action`werden. Zusätzliche Attributname-Typen können im Laufe der Zeit hinzugefügt werden.
ColumnAction	Das Array von Aktionen, die auf die ColumnNames angewendet werden. Dadurch wird bestimmt, welche Aktionen ein Benutzer für Spalten ausführen kann. Die zulässigen Werte sind: Lesezugriff. Zusätzliche columnAction-Typen können im Laufe der Zeit hinzugefügt werden.
ColumnConstraint	ColumnConstraint gibt eine Einschränkung an, die die Berechtigungen und Sichtbarkeit bestimmt, die ein Benutzer für Spalten innerhalb einer Tabelle hat.
ColumnEffect	Der Effekt, der den ColumnNames zugewiesen wurde. Der einzige zulässige Wert ist Permit. Zusätzliche ColumnEffect-Typen können im Laufe der Zeit hinzugefügt werden.
Constraints	Einschränkungen wie Sicherheit auf Zeilen- oder Spaltenebene, die als Teil dieser Rolle auf Tabellen angewendet werden. Wenn sie nicht enthalten ist, gelten keine Einschränkungen für Tabellen in der Rolle.
DataAccessRoleBase	Rollenobjekt für den Basisdatenzugriff, das für Einzelrollenvorgänge verwendet wird (enthält keine ID). Stellt einen Satz von Berechtigungen und Berechtigungsbereichen dar, die zulässige Aktionen für bereichsbezogene Daten definieren.
DataAccessRoleKind	Die Art der Datenzugriffsrolle. Derzeit ist `Policy`die einzige unterstützte Art. Zusätzliche Typen können im Laufe der Zeit hinzugefügt werden.
DecisionRule	Gibt eine Regel für den Abgleich der angeforderten Aktion an. Enthält Effekt (Permit) und Permission, die bestimmen, ob ein Benutzer oder eine Entität berechtigt ist, eine bestimmte Aktion (z. B. lesen) für eine Ressource auszuführen. Berechtigung ist eine Reihe von Bereichen, die durch Attribute definiert werden, die mit der angeforderten Aktion übereinstimmen müssen, damit die Regel angewendet werden kann.
Effect	Der Effekt, den eine Rolle auf den Zugriff auf die Datenressource hat. Derzeit ist der einzige unterstützte Effekttyp `Permit`, der Zugriff auf die Ressource gewährt. Zusätzliche Effekttypen können im Laufe der Zeit hinzugefügt werden.
ErrorRelatedResource	Das Fehlerbezogene Ressourcendetails-Objekt.
ErrorResponse	Die Fehlerantwort.
ErrorResponseDetails	Die Fehlerantwortdetails.
FabricItemMember	Fabric-Elementelement.
ItemAccess	Eine Liste, die die Zugriffsberechtigungen für Fabric-Benutzer angibt, die automatisch in die Rollenmitglieder aufgenommen werden müssen. Zusätzliche ItemAccess-Typen können im Laufe der Zeit hinzugefügt werden.
Members	Das Memberobjekt, das die Elemente der Rolle als Arrays verschiedener Membertypen enthält.
MicrosoftEntraMember	Microsoft Entra ID-Mitglied, das der Rolle zugewiesen ist.
ObjectType	Der Typ des Microsoft Entra ID-Objekts. Zusätzliche objectType-Typen können im Laufe der Zeit hinzugefügt werden.
PermissionScope	Definiert einen Satz von Attributen (Eigenschaften), die den Umfang und die Zugriffsebene für eine Ressource bestimmen. Wenn `attributeName` Eigenschaft auf `Path`festgelegt ist, muss die `attributeValueIncludedIn` Eigenschaft den Speicherort der Ressource angeben, auf die zugegriffen wird, z. B. "Tables/Table1". Wenn die `attributeName`-Eigenschaft auf `Action`festgelegt ist, muss die `attributeValueIncludedIn`-Eigenschaft den Typ des gewährten Zugriffs angeben, z. B. `Read`.
RowConstraint	RowConstraint gibt eine Einschränkung an, die die Zeilen in einer Tabelle bestimmt, die Benutzer sehen können. Rollen, die mit RowConstraints definiert sind, verwenden T-SQL, um ein Prädikat zu definieren, das Daten in einer Tabelle filtert. Zeilen, die die Bedingungen des Prädikats nicht erfüllen, werden herausgefiltert, sodass eine Teilmenge der ursprünglichen Zeilen übrig bleibt. RowConstraints können auch verwendet werden, um dynamische und tabellenübergreifende Varianten von RLS mithilfe von T-SQL anzugeben.

AttributeName

Enumeration

Gibt den Namen des Attributs an, das für Zugriffsberechtigungen ausgewertet wird. Attributname kann Path oder Actionwerden. Zusätzliche Attributname-Typen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Path	Attributname Pfad
Action	Attributname-Aktion

ColumnAction

Enumeration

Das Array von Aktionen, die auf die ColumnNames angewendet werden. Dadurch wird bestimmt, welche Aktionen ein Benutzer für Spalten ausführen kann. Die zulässigen Werte sind: Lesezugriff. Zusätzliche columnAction-Typen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Read	Der ColumnAction-Wert "Read"

ColumnConstraint

Objekt

ColumnConstraint gibt eine Einschränkung an, die die Berechtigungen und Sichtbarkeit bestimmt, die ein Benutzer für Spalten innerhalb einer Tabelle hat.

Name	Typ	Beschreibung
columnAction	ColumnAction[]	Das Array von Aktionen, die auf die ColumnNames angewendet werden. Dadurch wird bestimmt, welche Aktionen ein Benutzer für Spalten ausführen kann. Die zulässigen Werte sind: Lesezugriff. Zusätzliche columnAction-Typen können im Laufe der Zeit hinzugefügt werden.
columnEffect	ColumnEffect	Der Effekt, der den ColumnNames zugewiesen wurde. Der einzige zulässige Wert ist Permit. Zusätzliche ColumnEffect-Typen können im Laufe der Zeit hinzugefügt werden.
columnNames	string[]	Ein Array von Spaltennamen mit Groß-/Kleinschreibung. Jeder Wert ist ein Spaltenname aus der in `tablePath`der Tabelle angegebenen. Verwenden Sie diese Spalten mit `columnEffect` und `columnAction`. Spalten, die nicht aufgelistet sind, erhalten den Standardwert NULL. Wird verwendet `*` , um alle Spalten in der Tabelle anzugeben.
tablePath	string	Ein relativer Dateipfad, der angibt, für welche Tabelle die Spalteneinschränkung gilt. Dies sollte in Form von `/Tables/{optionalSchema}/{tableName}`. Hier kann nur ein Wert angegeben werden, und der TableName muss eine Tabelle sein, die im PermissionScope enthalten ist.

ColumnEffect

Enumeration

Der Effekt, der den ColumnNames zugewiesen wurde. Der einzige zulässige Wert ist Permit. Zusätzliche ColumnEffect-Typen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Permit	Der ColumnEffect-Typ "Permit"

Constraints

Objekt

Einschränkungen wie Sicherheit auf Zeilen- oder Spaltenebene, die als Teil dieser Rolle auf Tabellen angewendet werden. Wenn sie nicht enthalten ist, gelten keine Einschränkungen für Tabellen in der Rolle.

Name	Typ	Beschreibung
columns	ColumnConstraint[]	Das Array von Spalteneinschränkungen, die auf eine oder mehrere Tabellen in der Datenzugriffsrolle angewendet werden.
rows	RowConstraint[]	Das Array von Zeileneinschränkungen, die auf eine oder mehrere Tabellen in der Datenzugriffsrolle angewendet werden.

DataAccessRoleBase

Objekt

Rollenobjekt für den Basisdatenzugriff, das für Einzelrollenvorgänge verwendet wird (enthält keine ID). Stellt einen Satz von Berechtigungen und Berechtigungsbereichen dar, die zulässige Aktionen für bereichsbezogene Daten definieren.

Name	Typ	Beschreibung
decisionRules	DecisionRule[]	Das Array der Berechtigungen, aus denen die Datenzugriffsrolle besteht.
kind	DataAccessRoleKind	Die Art der Datenzugriffsrolle. Derzeit ist `Policy`die einzige unterstützte Art. Zusätzliche Typen können im Laufe der Zeit hinzugefügt werden.
members	Members	Das Memberobjekt, das die Elemente der Rolle als Arrays verschiedener Membertypen enthält.
name	string	Der Name der Datenzugriffsrolle.

DataAccessRoleKind

Enumeration

Die Art der Datenzugriffsrolle. Derzeit ist Policydie einzige unterstützte Art. Zusätzliche Typen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Policy	Richtlinienbasierte Datenzugriffsrolle.

DecisionRule

Objekt

Gibt eine Regel für den Abgleich der angeforderten Aktion an. Enthält Effekt (Permit) und Permission, die bestimmen, ob ein Benutzer oder eine Entität berechtigt ist, eine bestimmte Aktion (z. B. lesen) für eine Ressource auszuführen. Berechtigung ist eine Reihe von Bereichen, die durch Attribute definiert werden, die mit der angeforderten Aktion übereinstimmen müssen, damit die Regel angewendet werden kann.

Name	Typ	Beschreibung
constraints	Constraints	Einschränkungen wie Sicherheit auf Zeilen- oder Spaltenebene, die als Teil dieser Rolle auf Tabellen angewendet werden. Wenn sie nicht enthalten ist, gelten keine Einschränkungen für Tabellen in der Rolle.
effect	Effect	Der Effekt, den eine Rolle auf den Zugriff auf die Datenressource hat. Derzeit ist der einzige unterstützte Effekttyp `Permit`, der Zugriff auf die Ressource gewährt. Zusätzliche Effekttypen können im Laufe der Zeit hinzugefügt werden.
permission	PermissionScope[]	Die `permission`-Eigenschaft ist ein Array, das den Bereich und die Zugriffsebene für eine angeforderte Aktion angibt. Das Array muss genau zwei PermissionScope-Objekte enthalten: `Path` und `Action`. Die `scope` wird mithilfe des `PermissionScope`-Objekts definiert, wobei `attributeValueIncludedIn` entweder den Speicherort der zugegriffenen Ressource oder den Typ der gewährten Aktion angeben. Die `access` bezieht sich auf die Zugriffsebene, die gewährt wird, z. B. `Read`.

Effect

Enumeration

Der Effekt, den eine Rolle auf den Zugriff auf die Datenressource hat. Derzeit ist der einzige unterstützte Effekttyp Permit, der Zugriff auf die Ressource gewährt. Zusätzliche Effekttypen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Permit	der Effekttyp "Permit"

ErrorRelatedResource

Objekt

Das Fehlerbezogene Ressourcendetails-Objekt.

Name	Typ	Beschreibung
resourceId	string	Die Ressourcen-ID, die an dem Fehler beteiligt ist.
resourceType	string	Der Typ der Ressource, die an dem Fehler beteiligt ist.

ErrorResponse

Objekt

Die Fehlerantwort.

Name	Typ	Beschreibung
errorCode	string	Ein bestimmter Bezeichner, der Informationen über eine Fehlerbedingung bereitstellt und eine standardisierte Kommunikation zwischen unserem Dienst und seinen Benutzern ermöglicht.
message	string	Eine lesbare Darstellung des Fehlers.
moreDetails	ErrorResponseDetails[]	Liste der zusätzlichen Fehlerdetails.
relatedResource	ErrorRelatedResource	Die fehlerbezogenen Ressourcendetails.
requestId	string (uuid)	ID der Anforderung, die dem Fehler zugeordnet ist.

ErrorResponseDetails

Objekt

Die Fehlerantwortdetails.

Name	Typ	Beschreibung
errorCode	string	Ein bestimmter Bezeichner, der Informationen über eine Fehlerbedingung bereitstellt und eine standardisierte Kommunikation zwischen unserem Dienst und seinen Benutzern ermöglicht.
message	string	Eine lesbare Darstellung des Fehlers.
relatedResource	ErrorRelatedResource	Die fehlerbezogenen Ressourcendetails.

FabricItemMember

Objekt

Fabric-Elementelement.

Name	Typ	Beschreibung
itemAccess	ItemAccess[]	Eine Liste, die die Zugriffsberechtigungen für Fabric-Benutzer angibt, die automatisch in die Rollenmitglieder aufgenommen werden müssen. Zusätzliche ItemAccess-Typen können im Laufe der Zeit hinzugefügt werden.
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}[}]?$	Der Pfad zu Fabric-Element mit dem angegebenen Elementzugriff.

ItemAccess

Enumeration

Eine Liste, die die Zugriffsberechtigungen für Fabric-Benutzer angibt, die automatisch in die Rollenmitglieder aufgenommen werden müssen. Zusätzliche ItemAccess-Typen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Read	Elementzugriff lesen.
Write	Access-Elementschreibzugriff.
Reshare	Elementzugriff erneut freigeben.
Explore	Elementzugriff erkunden.
Execute	Elementzugriff wird ausgeführt.
ReadAll	Elementzugriff ReadAll.

Members

Objekt

Das Memberobjekt, das die Elemente der Rolle als Arrays verschiedener Membertypen enthält.

Name	Typ	Beschreibung
fabricItemMembers	FabricItemMember[]	Eine Liste der Mitglieder, die über einen bestimmten Berechtigungssatz in Microsoft Fabric verfügen. Alle Mitglieder mit diesem Berechtigungssatz werden als Mitglieder dieser Datenzugriffsrolle hinzugefügt.
microsoftEntraMembers	MicrosoftEntraMember[]	Die Liste der Microsoft Entra-ID-Mitglieder.

MicrosoftEntraMember

Objekt

Microsoft Entra ID-Mitglied, das der Rolle zugewiesen ist.

Name	Typ	Beschreibung
objectId	string (uuid)	Die Objekt-ID.
objectType	ObjectType	Der Typ des Microsoft Entra ID-Objekts. Zusätzliche objectType-Typen können im Laufe der Zeit hinzugefügt werden.
tenantId	string (uuid)	Die Mandanten-ID.

ObjectType

Enumeration

Der Typ des Microsoft Entra ID-Objekts. Zusätzliche objectType-Typen können im Laufe der Zeit hinzugefügt werden.

Wert	Beschreibung
Group	AttributnameGruppe
User	Attributname Benutzer
ServicePrincipal	Attributname ServicePrincipal
ManagedIdentity	Attributname ManagedIdentity

PermissionScope

Objekt

Definiert einen Satz von Attributen (Eigenschaften), die den Umfang und die Zugriffsebene für eine Ressource bestimmen. Wenn attributeName Eigenschaft auf Pathfestgelegt ist, muss die attributeValueIncludedIn Eigenschaft den Speicherort der Ressource angeben, auf die zugegriffen wird, z. B. "Tables/Table1". Wenn die attributeName-Eigenschaft auf Actionfestgelegt ist, muss die attributeValueIncludedIn-Eigenschaft den Typ des gewährten Zugriffs angeben, z. B. Read.

Name	Typ	Beschreibung
attributeName	AttributeName	Gibt den Namen des Attributs an, das für Zugriffsberechtigungen ausgewertet wird. Attributname kann `Path` oder `Action`werden. Zusätzliche Attributname-Typen können im Laufe der Zeit hinzugefügt werden.
attributeValueIncludedIn	string[]	Gibt eine Liste der Werte für die `attributeName` an, um den Bereich und die Ebene des Zugriffs auf eine Ressource zu definieren. Wenn `attributeNamePath`ist, muss `attributeValueIncludedIn` den Speicherort der Ressource angeben, auf die zugegriffen wird, z. B. "Tabellen/Tabelle1". Wenn `attributeNameAction`ist, muss die `attributeValueIncludedIn` den Typ des gewährten Zugriffs angeben, z. B. `Read`.

RowConstraint

Objekt

RowConstraint gibt eine Einschränkung an, die die Zeilen in einer Tabelle bestimmt, die Benutzer sehen können. Rollen, die mit RowConstraints definiert sind, verwenden T-SQL, um ein Prädikat zu definieren, das Daten in einer Tabelle filtert. Zeilen, die die Bedingungen des Prädikats nicht erfüllen, werden herausgefiltert, sodass eine Teilmenge der ursprünglichen Zeilen übrig bleibt. RowConstraints können auch verwendet werden, um dynamische und tabellenübergreifende Varianten von RLS mithilfe von T-SQL anzugeben.

Name	Typ	Beschreibung
tablePath	string	Ein relativer Dateipfad, der angibt, für welche Tabelle die Zeileneinschränkung gilt. Dies sollte in Form von `/Tables/{optionalSchema}/{tableName}`. Hier kann nur ein Wert angegeben werden, und der TableName muss eine Tabelle sein, die im PermissionScope enthalten ist.
value	string	Ein T-SQL-Ausdruck, der verwendet wird, um zu bewerten, welche Zeilen die Rollenmitglieder sehen können. Nur eine Teilmenge von T-SQL kann als Prädikat verwendet werden.

Freigeben über

OneLake Data Access Security - Get Data Access Role

Erlaubnisse

Erforderliche delegierte Bereiche

Von Microsoft Entra unterstützte Identitäten

Schnittstelle

URI-Parameter

Anforderungsheader

Antworten

Beispiele

Get data access role example

Beispielanforderung

Beispiel für eine Antwort

Definitionen

AttributeName

ColumnAction

ColumnConstraint

ColumnEffect

Constraints

DataAccessRoleBase

DataAccessRoleKind

DecisionRule

Effect

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

FabricItemMember

ItemAccess

Members

MicrosoftEntraMember

ObjectType

PermissionScope

RowConstraint