Samouczek: indeksowanie uprawnień usługi ADLS Gen2 i weryfikowanie filtrowanych wyników

Note

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

W tym samouczku przedstawiono pozyskiwanie metadanych uprawnień w usłudze Azure Data Lake Storage (ADLS) Gen2, w którym indeksator Foundry IQ (Wyszukiwanie AI platformy Azure) dodaje do indeksu wyszukiwania listy kontroli dostępu (ACL) i zakres kontroli dostępu opartej na rolach (RBAC). Ta funkcja jest ogólnie dostępna w interfejsie API 2026-10-01REST.

Przedstawiono również sposób wykonywania zapytań jako użytkownicy z dozwolonym i zabronionym dostępem oraz weryfikowania zmian uprawnień po indeksowaniu.

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:

  • Konfigurowanie zakresu RBAC (kontroli dostępu opartej na rolach) oraz list ACL w źródle danych adlsgen2
  • Utwórz indeks IQ usługi Foundry zawierający pola informacji o uprawnieniach
  • Tworzenie i uruchamianie indeksatora w celu pozyskiwania informacji o uprawnieniach do indeksu ze źródła danych
  • Przeszukaj właśnie utworzony indeks

Użyj klienta REST i interfejsu API REST 2026-10-01. 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.

  • Usługa 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.

  • Foundry IQ, 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

Utwórz kontener o nazwie parks w usłudze ADLS Gen2. Prześlij dwa pliki zwykłego tekstu z inną zawartością:

  • Oregon/Portland/Data.txt
  • Washington/Seattle/Data.txt

W tym samouczku jest używany domyślny tryb analizowania w celu utworzenia jednego dokumentu wyszukiwania dla każdego pliku. Indeks przechowuje nazwę pliku i wyodrębniony tekst. Pliki .txt nie wymagają wyspecjalizowanego text trybu analizowania, który nie jest obsługiwany z uprawnieniami na poziomie dokumentu. Zobacz Obsługiwane analizowanie i wyodrębnianie zawartości na potrzeby importu uprawnień.

Sprawdź konfigurację usługi IQ usługi Foundry

Skonfiguruj usługę IQ usługi Foundry na potrzeby uwierzytelniania i autoryzacji Microsoft Entra ID. Przejrzyj tę listę kontrolną, aby upewnić się, że jesteś przygotowany.

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.

Wykonaj następujące 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. Udziel tożsamości usługi Foundry IQ dostępu do odczytu do kontenera. Indeksator łączy się z Azure Storage w ramach tożsamości usługi IQ usługi Foundry. Aby pobrać dane, usługa Foundry IQ musi mieć uprawnienia Czytelnik danych obiektu blob usługi Storage.

  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. Użyj nazwanych użytkowników i nazwanych grup dla uprawnień testowych. Wpisy właściciela-użytkownika, właściciela-grupy i Inne nie są obsługiwane w przypadku indeksowania list ACL; nie polegaj na nich w przypadku tożsamości testowych.

Przed indeksowaniem sprawdź źródłowe listy ACL pod kątem nieobsługiwanych niejawnych wpisów blocklists i koryguj je za pomocą obsługiwanych allowlists.

Tworzenie indeksu wyszukiwania dla metadanych uprawnień

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

Użyj interfejsu API REST 2026-10-01 dla żądań indeksu, źródła danych i indeksatora.

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": "metadata_storage_path", "type": "Edm.String",
      "searchable": false, "filterable": true, "retrievable": true
    },
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "content", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": false
    },
    {
      "name": "id", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": false, "filterable": true, "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

Zdefiniuj pole najwyższego poziomu fieldMappings dla nieprzetworzonej ścieżki źródłowej i metadanych uprawnień. metadata_storage_path jest wymagany, nawet jeśli pozyskasz tylko zakresy RBAC. Nie koduj tego pola.

{
  "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": "default",
      "refreshAllAcls": true
    }
  },
  "fieldMappings": [
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "id", "mappingFunction": { "name": "base64Encode" } },
    { "sourceFieldName": "metadata_storage_name", "targetFieldName": "name" },
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "metadata_storage_path" },
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Utworzenie indeksatora rozpoczyna pierwszy przebieg. Przed wykonaniem zapytania użyj polecenia Pobierz stan indeksatora , aby potwierdzić, że przebieg zakończył się pomyślnie. Sprawdź błędy i ostrzeżenia oraz sprawdź, czy oba pliki zostały indeksowane.

Jeśli planujesz użyć automatycznego odświeżania listy ACL w celu zweryfikowania zmian uprawnień, skonfiguruj harmonogram indeksatora.

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/my-adlsgen2-acl-index/docs/search?api-version=2026-10-01
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{query-user-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,content,metadata_storage_path,GroupIds"
}

Nagłówek Authorization autoryzuje aplikację do wykonywania zapytań dotyczących wyszukiwania. query-user-token jest tokenem delegowanego użytkownika do oceny uprawnień; może reprezentować inną tożsamość.

Zweryfikuj zmiany uprawnień

  1. Wykonaj zapytanie jako nazwany użytkownik z dostępem do odczytu pliku i uprawnieniem do wykonywania/przechodzenia przez katalogi nadrzędne. Upewnij się, że zostanie wyświetlony oczekiwany dokument.
  2. Wykonaj zapytanie jako użytkownik bez pasującej listy ACL użytkownika lub grupy oraz bez obsługiwanego przyznania RBAC kontenera. Upewnij się, że tego samego dokumentu nie ma.
  3. Usuń pierwsze uprawnienie ACL użytkownika bez zmieniania zawartości pliku. Upewnij się, że żadne inne uprawnienie ACL ani obsługiwane przypisanie RBAC nie autoryzuje tego użytkownika. Zażądaj ponownej synchronizacji uprawnień i uruchom indeksator lub poczekaj na automatyczne odświeżanie listy ACL.
  4. Po zakończeniu powtórz oba zapytania. Odwołany użytkownik nie może już pobrać dokumentu, podczas gdy inny jawnie autoryzowany użytkownik nadal może.
  5. Powtarzaj z nadaniem lub usunięciem uprawnienia dla nazwanej grupy oraz zmianą przechodzenia z katalogu przodków. Testuj przyznania lub usunięcia RBAC oddzielnie, uwzględniając propagację Storage i pamięć podręczną autoryzacji zapytań.

W przypadku fragmentowanego potoku sprawdź również reprezentatywne fragmenty z każdego nadrzędnego elementu objętego zmianą. Po częściowych awariach sprawdź błędy i ostrzeżenia i ponów próbę przed traktowaniem wszystkich wyników za uzgodnione. Użyj mapowań projekcji kanonicznych; chroniony element nadrzędny nie chroni fragmentu pozbawionego metadanych uprawnień.