Samouczek: indeksowanie metadanych uprawnień z ADLS Gen2 i wykonywanie zapytań z wynikami filtrowanymi według uprawnień (wersja zapoznawcza)

W tym samouczku przedstawiono pozyskiwanie metadanych dotyczących uprawnień w usłudze Azure Data Lake Storage (ADLS) Gen2 (wersja zapoznawcza), w ramach którego indeksator Wyszukiwanie AI platformy Azure dodaje do indeksu wyszukiwania zakresy list kontroli dostępu (ACL) i kontroli dostępu opartej na rolach (RBAC).

Pokazano również, jak utworzyć strukturę zapytania, które szanuje uprawnienia dostępu użytkowników. Wynik pomyślnego zapytania potwierdza transfer uprawnień, który nastąpił podczas indeksowania.

Aby uzyskać więcej informacji na temat indeksowania list ACL, zobacz Używanie indeksatora usługi ADLS Gen2 do pozyskiwania metadanych uprawnień.

Z tego samouczka dowiesz się, jak wykonywać następujące działania:

Aby ukończyć ten samouczek i najnowszą wersję zapoznawczą REST API, użyj klienta REST. Obecnie w portalu Azure nie ma obsługi indeksowania ACL.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Microsoft Entra ID - uwierzytelnianie i autoryzacja. Usługi i aplikacje muszą znajdować się w tej samej dzierżawie. Przypisania ról są używane dla każdego uwierzytelnionego połączenia. Użytkownicy i grupy muszą znajdować się w tej samej dzierżawie. Należy mieć użytkowników i grupy do pracy. Tworzenie dzierżaw i podmiotów zabezpieczających nie jest objęte zakresem tego samouczka.

• ADLS Gen2 z hierarchiczną przestrzenią nazw.

• Pliki w strukturze folderów hierarchicznych. W tym samouczku przyjmuje się demonstrację struktury folderów ADLS Gen2 dla pliku /Oregon/Portland/Data.txt. Ten samouczek przeprowadzi Cię przez przydzielanie listy kontroli dostępu (ACL) w folderach i plikach, aby móc pomyślnie ukończyć ćwiczenie.

• Wyszukiwanie AI platformy Azure dowolny region. Do obsługi tożsamości zarządzanej wymagana jest warstwa Podstawowa lub nowsza.

• Visual Studio Code z rozszerzeniem klienta REST.

Przygotowywanie przykładowych danych

Przekaż przykładowe dane parków stanowych do kontenera w usłudze ADLS Gen2. Nazwa kontenera powinna być "parki" i powinna zawierać dwa foldery: "Oregon" i "Washington".

Sprawdzanie konfiguracji usługi wyszukiwania

Należy skonfigurować usługę wyszukiwania na potrzeby uwierzytelniania i autoryzacji Microsoft Entra ID. Przejrzyj tę listę kontrolną, aby upewnić się, że jesteś przygotowany.

• Włączanie dostępu opartego na rolach

• Skonfiguruj tożsamość zarządzaną przypisaną przez system.

Uzyskiwanie osobistego tokenu tożsamości na potrzeby testowania lokalnego

W tym samouczku założono, że klient REST w systemie lokalnym łączy się z Azure za pośrednictwem publicznego połączenia internetowego.

Użyj te kroki aby uzyskać osobisty token tożsamości i skonfigurować Visual Studio Code dla połączeń lokalnych z zasobami Azure.

Ustawianie uprawnień w usłudze ADLS Gen2

Najlepszym rozwiązaniem jest użycie Group zestawów zamiast bezpośredniego przypisywania User zestawów.

1. Przyznaj tożsamości usługi wyszukiwania dostęp do odczytu w kontenerze. Indeksator łączy się z Azure Storage w ramach tożsamości usługi wyszukiwania. Aby pobrać dane, usługa wyszukiwania musi mieć uprawnienia Odczyt danych Storage Blob.

2. Przyznaj uprawnienia dla poszczególnych grup lub użytkowników w hierarchii plików. W hierarchii plików zidentyfikuj wszystkie zestawy Group i User przypisane do kontenerów, katalogów i plików.

3. Aby zarządzać listami ACL, możesz użyć portalu Azure. W przeglądarce magazynu wybierz katalog Oregon, a następnie wybierz opcję Zarządzaj ACL z menu kontekstowego.

4. Dodaj nowe zasady zabezpieczeń dla użytkowników i grup.

5. Usuń istniejące zasady dla grup posiadających, użytkowników posiadających oraz innych. Te podmioty nie są obsługiwane w przypadku indeksowania listy ACL w wersji próbnej.

Tworzenie indeksu wyszukiwania dla metadanych uprawnień

Utwórz indeks zawierający pola zawartości i metadanych uprawnień.

Pamiętaj, aby użyć latest preview REST API lub pakietu Azure SDK w wersji zapoznawczej, który zapewnia równoważne funkcje. Właściwości filtru uprawnień są dostępne tylko w interfejsach API w wersji zapoznawczej.

W celach demonstracyjnych pole uprawnień zostało retrievable włączone, aby można było sprawdzić wartości z indeksu. W środowisku produkcyjnym należy wyłączyć, retrievable aby uniknąć wycieku poufnych informacji.

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

Tworzenie źródła danych

Zmodyfikuj konfigurację źródła danych , aby określić pozyskiwanie uprawnień indeksatora oraz typy metadanych uprawnień, które chcesz indeksować.

Źródło danych wymaga indexerPermissionOptions.

W tym samouczku użyj przypisanej przez system tożsamości zarządzanej do uwierzytelnienia połączenia.

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "parks",
    "query": null
    }
}

Tworzenie i uruchamianie indeksatora

Konfiguracja indeksatora dotycząca pobierania uprawnień polega głównie na definiowaniu fieldMappingsna podstawie metadanych uprawnień.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

Po utworzeniu indeksatora i natychmiastowym uruchomieniu zawartość pliku wraz z informacjami o metadanych uprawnień jest indeksowana do indeksu.

Uruchamianie zapytania w celu sprawdzenia wyników

Teraz, gdy dokumenty są załadowane, możesz wysyłać do nich zapytania, korzystając z Dokumenty - wyszukiwanie zapytań (REST).

Identyfikator URI jest rozszerzony w celu uwzględnienia danych wejściowych zapytania, które jest określane przy użyciu /docs/search operatora . Token zapytania jest przekazywany w nagłówku żądania. Aby uzyskać więcej informacji, zobacz Egzekwowanie ACL czasu zapytań i RBAC.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Powiązana zawartość

• https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl