Udostępnij przez


OneLake Data Access Security - Create Or Update Data Access Roles

Tworzy lub aktualizuje role dostępu do danych w usłudze OneLake.

Note

Ten interfejs API jest częścią wersji zapoznawczej i jest dostarczany tylko do celów ewaluacyjnych i programistycznych. Może ona ulec zmianie na podstawie opinii i nie jest zalecana do użytku produkcyjnego.

Wymagane zakresy delegowane

OneLake.ReadWrite.All

Tożsamości obsługiwane przez Microsoft Entra

To API obsługuje tożsamości Microsoft wymienione w tej sekcji.

Identity Support
User Yes
Główne usługi i Tożsamości zarządzane 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}

Parametry identyfikatora URI

Nazwa W Wymagane Typ Opis
itemId
path True

string (uuid)

Identyfikator elementu sieć szkieletowa do umieszczenia ról.

workspaceId
path True

string (uuid)

Identyfikator przestrzeni roboczej.

dryRun
query

boolean

Służy do wyzwalania suchego przebiegu wywołania interfejsu API. Prawda — wywołanie interfejsu API spowoduje wyzwolenie przebiegu suchego i żadne role nie zostaną zmienione. Fałsz — nie spowoduje wyzwolenia suchego przebiegu i zostaną zaktualizowane role.

Nagłówek żądania

Nazwa Wymagane Typ Opis
If-Match

string

Wartość ETag. Element ETag musi być określony w cudzysłowie. Jeśli zostanie podana wartość , wywołanie powiedzie się tylko wtedy, gdy element ETag zasobu jest zgodny z podanym elementem ETag.

If-None-Match

string

Wartość ETag. Element ETag musi być określony w cudzysłowie. Jeśli zostanie podana wartość , wywołanie powiedzie się tylko wtedy, gdy element ETag zasobu nie jest zgodny z podanym elementem ETag.

Treść żądania

Nazwa Typ Opis
value

DataAccessRole[]

Lista ról używanych do zarządzania zabezpieczeniami dostępu do danych i zapewniania, że tylko autoryzowani użytkownicy mogą wyświetlać określone dane. Rola reprezentuje zestaw uprawnień i zakresów uprawnień, które definiują, jakie akcje mogą wykonywać jego członkowie dla danych w zakresie. Członkowie to użytkownicy lub grupy, którym przyznano rolę, i mogą odczytywać dane na podstawie uprawnień przypisanych do roli. Na przykład element członkowski może być grupą identyfikatorów Entra firmy Microsoft i zakresem uprawnień może być akcja odczytu zastosowana w danej ścieżce do plików, folderów lub tabel w usłudze OneLake.

Odpowiedzi

Nazwa Typ Opis
200 OK

Żądanie zostało ukończone pomyślnie.

Nagłówki

Etag: string

Other Status Codes

ErrorResponse

Typowe kody błędów:

  • ItemNotFound — wskazuje, że serwer nie może odnaleźć żądanego elementu.

  • Warunek wstępny -Indicates, że bieżący zasób ETag nie jest zgodny z wartością określoną w nagłówku If-Match.

Przykłady

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

Przykładowe żądanie

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

Przykładowa odpowiedź

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with constraints example

Przykładowe żądanie

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

Przykładowa odpowiedź

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4

Create or update data access roles with tables path example

Przykładowe żądanie

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

Przykładowa odpowiedź

ETag: 33a64df551425fcc55e4d42a148795d9f25f89d5

Definicje

Nazwa Opis
AttributeName

Określa nazwę atrybutu ocenianego pod kątem uprawnień dostępu. AtrybutName może być Path lub Action. Dodatkowe typy attributeName można dodawać w czasie.

ColumnAction

Tablica akcji zastosowanych do kolumny columnNames. Określa, które akcje użytkownik będzie mógł wykonywać w kolumnach. Dozwolone wartości to: Odczyt. Dodatkowe typy columnAction mogą być dodawane w czasie.

ColumnConstraint

KolumnaConstraint wskazuje ograniczenie określające uprawnienia i widoczność, które użytkownik ma w kolumnach w tabeli.

ColumnEffect

Efekt nadany kolumnom columnNames. Jedyną dozwoloną wartością jest Zezwalanie. Dodatkowe typy columnEffect mogą być dodawane w czasie.

Constraints

Wszelkie ograniczenia, takie jak zabezpieczenia na poziomie wiersza lub kolumny, które są stosowane do tabel w ramach tej roli. Jeśli nie zostaną uwzględnione, żadne ograniczenia nie mają zastosowania do żadnych tabel w roli.

CreateOrUpdateDataAccessRolesRequest

Zawiera definicję ról używanych do zarządzania zabezpieczeniami dostępu do danych i zapewnia, że tylko autoryzowani użytkownicy mogą wyświetlać, edytować lub usuwać określone dane. Wywołanie tego interfejsu API aktualizuje definicje ról i tworzy, aktualizuje lub usuwa role, aby pasować do podanego ładunku.

DataAccessRole

Rola dostępu do danych reprezentuje zestaw uprawnień i zakresów uprawnień, które definiują, jakie akcje mogą wykonywać jego członkowie dla danych w zakresie. Role dostępu do danych służą do zarządzania zabezpieczeniami dostępu do danych i zapewniają, że tylko autoryzowani użytkownicy mogą wyświetlać, edytować lub usuwać określone dane. Członkowie to użytkownicy lub grupy, którym przyznano rolę, i mogą odczytywać dane na podstawie uprawnień przypisanych do roli. Na przykład element członkowski może być grupą identyfikatorów Entra firmy Microsoft i zakresem uprawnień może być akcja odczytu zastosowana w danej ścieżce do plików, folderów lub tabel w usłudze OneLake.

DecisionRule

Określa regułę dopasowania żądanej akcji. Zawiera efekt (Zezwól) i Uprawnienie, które określają, czy użytkownik lub jednostka jest autoryzowana do wykonania konkretnej akcji (np. odczytu) na zasobie. Uprawnienie to zestaw zakresów zdefiniowanych przez atrybuty, które muszą być zgodne z żądaną akcją, aby reguła została zastosowana.

Effect

Wpływ, jaki rola ma na dostęp do zasobu danych. Obecnie jedynym obsługiwanym typem efektu jest Permit, który udziela dostępu do zasobu. Dodatkowe typy efektów mogą być dodawane w czasie.

ErrorRelatedResource

Obiekt szczegółów zasobu powiązanego z błędem.

ErrorResponse

Odpowiedź na błąd.

ErrorResponseDetails

Szczegóły odpowiedzi na błąd.

FabricItemMember

Składowa elementu sieci szkieletowej.

ItemAccess

Lista określająca uprawnienia dostępu dla użytkownika sieci szkieletowej, które mają być automatycznie uwzględniane w członkach roli. Dodatkowe typy itemAccess można dodawać w czasie.

Members

Obiekt członkowski zawierający elementy członkowskie roli jako tablice różnych typów składowych.

MicrosoftEntraMember

Członek microsoft Entra ID przypisany do roli.

ObjectType

Typ obiektu Microsoft Entra ID. Dodatkowe typy objectType można dodawać w czasie.

PermissionScope

Definiuje zestaw atrybutów (właściwości), które określają zakres i poziom dostępu do zasobu. Gdy właściwość attributeName jest ustawiona na Path, właściwość attributeValueIncludedIn musi określać lokalizację zasobu, na przykład "Tables/Table1". Gdy właściwość attributeName jest ustawiona na Action, właściwość attributeValueIncludedIn musi określać typ udzielanego dostępu, na przykład Read.

RowConstraint

WierszConstraint wskazuje ograniczenie określające wiersze w tabeli, które użytkownicy mogą zobaczyć. Role zdefiniowane za pomocą ograniczeń wierszy używają języka T-SQL do zdefiniowania predykatu, który filtruje dane w tabeli. Wiersze, które nie spełniają warunków predykatu, są filtrowane, pozostawiając podzbiór oryginalnych wierszy. Ograniczenia wierszy mogą również służyć do określania dynamicznych i wieloplaterowych smaków zabezpieczeń na poziomie wiersza przy użyciu języka T-SQL.

AttributeName

Określa nazwę atrybutu ocenianego pod kątem uprawnień dostępu. AtrybutName może być Path lub Action. Dodatkowe typy attributeName można dodawać w czasie.

Wartość Opis
Path

Ścieżka nazwy atrybutu

Action

Akcja nazwy atrybutu

ColumnAction

Tablica akcji zastosowanych do kolumny columnNames. Określa, które akcje użytkownik będzie mógł wykonywać w kolumnach. Dozwolone wartości to: Odczyt. Dodatkowe typy columnAction mogą być dodawane w czasie.

Wartość Opis
Read

Odczyt wartości ColumnAction

ColumnConstraint

KolumnaConstraint wskazuje ograniczenie określające uprawnienia i widoczność, które użytkownik ma w kolumnach w tabeli.

Nazwa Typ Opis
columnAction

ColumnAction[]

Tablica akcji zastosowanych do kolumny columnNames. Określa, które akcje użytkownik będzie mógł wykonywać w kolumnach. Dozwolone wartości to: Odczyt. Dodatkowe typy columnAction mogą być dodawane w czasie.

columnEffect

ColumnEffect

Efekt nadany kolumnom columnNames. Jedyną dozwoloną wartością jest Zezwalanie. Dodatkowe typy columnEffect mogą być dodawane w czasie.

columnNames

string[]

Tablica nazw kolumn z uwzględnieniem wielkości liter. Każda wartość to nazwa kolumny z tabeli określonej w pliku tablePath. Użyj tych kolumn z wartościami columnEffect i columnAction. Kolumny, które nie są wymienione, otrzymują wartość domyślną o wartości null. Użyj * polecenia , aby wskazać wszystkie kolumny w tabeli.

tablePath

string

Względna ścieżka pliku określająca, do której tabeli ma zastosowanie ograniczenie kolumny. Powinno to mieć postać /Tables/{optionalSchema}/{tableName}. W tym miejscu można podać tylko jedną wartość, a tabela TableName musi być tabelą zawartą w kolumnie PermissionScope.

ColumnEffect

Efekt nadany kolumnom columnNames. Jedyną dozwoloną wartością jest Zezwalanie. Dodatkowe typy columnEffect mogą być dodawane w czasie.

Wartość Opis
Permit

Typ ColumnEffect Zezwalaj

Constraints

Wszelkie ograniczenia, takie jak zabezpieczenia na poziomie wiersza lub kolumny, które są stosowane do tabel w ramach tej roli. Jeśli nie zostaną uwzględnione, żadne ograniczenia nie mają zastosowania do żadnych tabel w roli.

Nazwa Typ Opis
columns

ColumnConstraint[]

Tablica ograniczeń kolumn zastosowanych do co najmniej jednej tabeli w roli dostępu do danych.

rows

RowConstraint[]

Tablica ograniczeń wierszy zastosowanych do co najmniej jednej tabeli w roli dostępu do danych.

CreateOrUpdateDataAccessRolesRequest

Zawiera definicję ról używanych do zarządzania zabezpieczeniami dostępu do danych i zapewnia, że tylko autoryzowani użytkownicy mogą wyświetlać, edytować lub usuwać określone dane. Wywołanie tego interfejsu API aktualizuje definicje ról i tworzy, aktualizuje lub usuwa role, aby pasować do podanego ładunku.

Nazwa Typ Opis
value

DataAccessRole[]

Lista ról używanych do zarządzania zabezpieczeniami dostępu do danych i zapewniania, że tylko autoryzowani użytkownicy mogą wyświetlać określone dane. Rola reprezentuje zestaw uprawnień i zakresów uprawnień, które definiują, jakie akcje mogą wykonywać jego członkowie dla danych w zakresie. Członkowie to użytkownicy lub grupy, którym przyznano rolę, i mogą odczytywać dane na podstawie uprawnień przypisanych do roli. Na przykład element członkowski może być grupą identyfikatorów Entra firmy Microsoft i zakresem uprawnień może być akcja odczytu zastosowana w danej ścieżce do plików, folderów lub tabel w usłudze OneLake.

DataAccessRole

Rola dostępu do danych reprezentuje zestaw uprawnień i zakresów uprawnień, które definiują, jakie akcje mogą wykonywać jego członkowie dla danych w zakresie. Role dostępu do danych służą do zarządzania zabezpieczeniami dostępu do danych i zapewniają, że tylko autoryzowani użytkownicy mogą wyświetlać, edytować lub usuwać określone dane. Członkowie to użytkownicy lub grupy, którym przyznano rolę, i mogą odczytywać dane na podstawie uprawnień przypisanych do roli. Na przykład element członkowski może być grupą identyfikatorów Entra firmy Microsoft i zakresem uprawnień może być akcja odczytu zastosowana w danej ścieżce do plików, folderów lub tabel w usłudze OneLake.

Nazwa Typ Opis
decisionRules

DecisionRule[]

Tablica uprawnień tworzących rolę dostępu do danych.

id

string (uuid)

Unikatowy identyfikator roli dostępu do danych.

members

Members

Obiekt członkowski zawierający elementy członkowskie roli jako tablice różnych typów składowych.

name

string

Nazwa roli dostępu do danych.

DecisionRule

Określa regułę dopasowania żądanej akcji. Zawiera efekt (Zezwól) i Uprawnienie, które określają, czy użytkownik lub jednostka jest autoryzowana do wykonania konkretnej akcji (np. odczytu) na zasobie. Uprawnienie to zestaw zakresów zdefiniowanych przez atrybuty, które muszą być zgodne z żądaną akcją, aby reguła została zastosowana.

Nazwa Typ Opis
constraints

Constraints

Wszelkie ograniczenia, takie jak zabezpieczenia na poziomie wiersza lub kolumny, które są stosowane do tabel w ramach tej roli. Jeśli nie zostaną uwzględnione, żadne ograniczenia nie mają zastosowania do żadnych tabel w roli.

effect

Effect

Wpływ, jaki rola ma na dostęp do zasobu danych. Obecnie jedynym obsługiwanym typem efektu jest Permit, który udziela dostępu do zasobu. Dodatkowe typy efektów mogą być dodawane w czasie.

permission

PermissionScope[]

Właściwość permission to tablica określająca zakres i poziom dostępu dla żądanej akcji. Tablica musi zawierać dokładnie dwa obiekty PermissionScope: Path i Action. scope jest definiowana przy użyciu obiektu PermissionScope z attributeValueIncludedIn określania lokalizacji zasobu, do których uzyskuje się dostęp, lub typu udzielanej akcji. access odnosi się do poziomu przyznanego dostępu, takiego jak Read.

Effect

Wpływ, jaki rola ma na dostęp do zasobu danych. Obecnie jedynym obsługiwanym typem efektu jest Permit, który udziela dostępu do zasobu. Dodatkowe typy efektów mogą być dodawane w czasie.

Wartość Opis
Permit

typ efektu Zezwalaj

ErrorRelatedResource

Obiekt szczegółów zasobu powiązanego z błędem.

Nazwa Typ Opis
resourceId

string

Identyfikator zasobu, który jest zaangażowany w błąd.

resourceType

string

Typ zasobu, który jest zaangażowany w błąd.

ErrorResponse

Odpowiedź na błąd.

Nazwa Typ Opis
errorCode

string

Określony identyfikator, który zawiera informacje o stanie błędu, co pozwala na ustandaryzowaną komunikację między naszą usługą a jej użytkownikami.

message

string

Czytelna reprezentacja błędu przez człowieka.

moreDetails

ErrorResponseDetails[]

Lista dodatkowych szczegółów błędu.

relatedResource

ErrorRelatedResource

Szczegóły zasobu powiązanego z błędem.

requestId

string

Identyfikator żądania skojarzonego z błędem.

ErrorResponseDetails

Szczegóły odpowiedzi na błąd.

Nazwa Typ Opis
errorCode

string

Określony identyfikator, który zawiera informacje o stanie błędu, co pozwala na ustandaryzowaną komunikację między naszą usługą a jej użytkownikami.

message

string

Czytelna reprezentacja błędu przez człowieka.

relatedResource

ErrorRelatedResource

Szczegóły zasobu powiązanego z błędem.

FabricItemMember

Składowa elementu sieci szkieletowej.

Nazwa Typ Opis
itemAccess

ItemAccess[]

Lista określająca uprawnienia dostępu dla użytkownika sieci szkieletowej, które mają być automatycznie uwzględniane w członkach roli. Dodatkowe typy itemAccess można dodawać w czasie.

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}[}]?$

Ścieżka do elementu sieci szkieletowej z określonym dostępem do elementu.

ItemAccess

Lista określająca uprawnienia dostępu dla użytkownika sieci szkieletowej, które mają być automatycznie uwzględniane w członkach roli. Dodatkowe typy itemAccess można dodawać w czasie.

Wartość Opis
Read

Odczyt dostępu do elementów.

Write

Zapis dostępu do elementu.

Reshare

Udostępnianie dalej dostępu do elementów.

Explore

Eksplorowanie dostępu do elementów.

Execute

Wykonywanie dostępu do elementów.

ReadAll

Dostęp do elementu ReadAll.

Members

Obiekt członkowski zawierający elementy członkowskie roli jako tablice różnych typów składowych.

Nazwa Typ Opis
fabricItemMembers

FabricItemMember[]

Lista członków, którzy mają określone uprawnienia ustawione w usłudze Microsoft Fabric. Wszyscy członkowie z tym zestawem uprawnień są dodawani jako członkowie tej roli dostępu do danych.

microsoftEntraMembers

MicrosoftEntraMember[]

Lista członków identyfikatora Entra firmy Microsoft.

MicrosoftEntraMember

Członek microsoft Entra ID przypisany do roli.

Nazwa Typ Opis
objectId

string (uuid)

Identyfikator obiektu.

objectType

ObjectType

Typ obiektu Microsoft Entra ID. Dodatkowe typy objectType można dodawać w czasie.

tenantId

string (uuid)

Identyfikator dzierżawy.

ObjectType

Typ obiektu Microsoft Entra ID. Dodatkowe typy objectType można dodawać w czasie.

Wartość Opis
Group

Grupa nazw atrybutów

User

Nazwa atrybutu Użytkownik

ServicePrincipal

Nazwa atrybutu ServicePrincipal

ManagedIdentity

Nazwa atrybutu ManagedIdentity

PermissionScope

Definiuje zestaw atrybutów (właściwości), które określają zakres i poziom dostępu do zasobu. Gdy właściwość attributeName jest ustawiona na Path, właściwość attributeValueIncludedIn musi określać lokalizację zasobu, na przykład "Tables/Table1". Gdy właściwość attributeName jest ustawiona na Action, właściwość attributeValueIncludedIn musi określać typ udzielanego dostępu, na przykład Read.

Nazwa Typ Opis
attributeName

AttributeName

Określa nazwę atrybutu ocenianego pod kątem uprawnień dostępu. AtrybutName może być Path lub Action. Dodatkowe typy attributeName można dodawać w czasie.

attributeValueIncludedIn

string[]

Określa listę wartości dla attributeName, aby zdefiniować zakres i poziom dostępu do zasobu. Gdy attributeName jest Path, attributeValueIncludedIn musi określić lokalizację zasobu, do których jest uzyskiwany dostęp, na przykład "Tabele/Tabela1". Gdy attributeName jest Action, attributeValueIncludedIn musi określić typ przyznanego dostępu, na przykład Read.

RowConstraint

WierszConstraint wskazuje ograniczenie określające wiersze w tabeli, które użytkownicy mogą zobaczyć. Role zdefiniowane za pomocą ograniczeń wierszy używają języka T-SQL do zdefiniowania predykatu, który filtruje dane w tabeli. Wiersze, które nie spełniają warunków predykatu, są filtrowane, pozostawiając podzbiór oryginalnych wierszy. Ograniczenia wierszy mogą również służyć do określania dynamicznych i wieloplaterowych smaków zabezpieczeń na poziomie wiersza przy użyciu języka T-SQL.

Nazwa Typ Opis
tablePath

string

Względna ścieżka pliku określająca, do której tabeli ma zastosowanie ograniczenie wiersza. Powinno to mieć postać /Tables/{optionalSchema}/{tableName}. W tym miejscu można podać tylko jedną wartość, a tabela TableName musi być tabelą zawartą w kolumnie PermissionScope.

value

string

Wyrażenie języka T-SQL używane do oceny wierszy, które mogą zobaczyć członkowie roli. Jako predykat można używać tylko podzestawu języka T-SQL.