Używanie indeksatora usługi ADLS Gen2 do pozyskiwania metadanych uprawnień i filtrowania wyników wyszukiwania na podstawie praw dostępu użytkowników (wersja zapoznawcza)

usługa Azure Data Lake Storage Gen2 obsługuje dostęp poszczególnych użytkowników do katalogów i plików za pośrednictwem list kontroli dostępu (ACL) i kontroli dostępu opartej na rolach (RBAC Azure). kontrola dostępu oparta na Attribute (Azure ABAC) nie jest obsługiwana.

Usługa Wyszukiwanie AI platformy Azure może pozyskiwać te metadane dotyczące uprawnień (wersja zapoznawcza) wraz z zawartością dokumentu za pomocą interfejsu API REST w wersji zapoznawczej. Użytkownicy, którzy nie mają dostępu do katalogu lub pliku w magazynie, nie widzą odpowiednich dokumentów w wynikach wyszukiwania. Jest to jedna z kilku strategii kontroli dostępu na poziomie dokumentacji w Wyszukiwanie AI platformy Azure.

W tym artykule wyjaśniono, jak skonfigurować indeksator usługi ADLS Gen2 lub źródło wiedzy obiektu blob usługi ADLS Gen2 w celu automatycznego ściągnięcia metadanych uprawnień do indeksu wyszukiwania. Uzupełnia dane indeksu z usługi ADLS Gen2 i Utwórz źródło wiedzy obiektu blob dla usługi ADLS Gen2 z informacjami specyficznymi dla pozyskiwania uprawnień. Aby ręcznie wysyłać metadane uprawnień, zobacz Indeksowanie list ACL dokumentów przy użyciu interfejsu API wysyłania.

Wymagania wstępne

• Microsoft Entra ID uwierzytelnianie i autoryzacja. Usługi i aplikacje muszą znajdować się w tej samej dzierżawie. Użytkownicy mogą znajdować się w różnych dzierżawach, o ile wszystkie dzierżawy używają Microsoft Entra ID. Przypisania ról są używane dla każdego uwierzytelnionego połączenia.

• Wyszukiwanie AI platformy Azure w warstwie rozliczanej (Podstawowa lub nowsza) w dowolnym regionie. Usługa wyszukiwania musi mieć włączony dostęp oparty na rolach oraz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika.

• Obiekty blob usługi ADLS Gen2 w hierarchicznej przestrzeni nazw z uprawnieniami użytkownika przyznanymi za pośrednictwem list ACL lub ról.

• Interfejs API REST w wersji 2025-05-01-preview lub nowszej na potrzeby pozyskiwania uprawnień indeksatora. Interfejs API REST w wersji 2025-11-01-preview lub nowszej do obsługi źródeł wiedzy. Użyj najnowszej wersji zapoznawczej interfejsu REST API lub pakietu SDK w wersji zapoznawczej, który obsługuje filtry uprawnień.

Ograniczenia

• Portal Azure nie obsługuje tej funkcji.

• Mają zastosowanie limity usługi ADLS Gen2 dla przypisań ról i wpisów ACL.

• owning users, owning groups, i Other (all) Kategorie tożsamości ACL nie są obsługiwane w wersji zapoznawczej. Zamiast tego używaj przypisań named users i named groups.

• Następujące funkcje indeksatora nie obsługują dziedziczenia uprawnień w indeksowanych dokumentach pochodzących z usługi ADLS Gen2. Jeśli używasz żadnej z tych funkcji w zestawie umiejętności lub indeksatorze, uprawnienia na poziomie dokumentu nie są uwzględniane w indeksowanej zawartości.

  • Dostosowana umiejętność Web API

  • Baza wiedzy, w tym magazyn zasobów wymagany do udostępniania obrazów (wersja zapoznawcza) w wyszukiwaniu agentowym. W związku z tym udostępnianie obrazów nie jest obsługiwane w przypadku źródeł wiedzy, które importują mechanizmy ACL lub zakresy RBAC.

  • Wzbogacona pamięć podręczna indeksatora

  • Sesje debugowania

Obsługa modelu uprawnień

W tej sekcji porównaliśmy funkcje kontroli dostępu na poziomie dokumentu między usługami ADLS Gen2 i Wyszukiwanie AI platformy Azure. Wyjaśniono, które mechanizmy kontroli dostępu Azure Data Lake Storage (ADLS) Gen2 obsługuje lub mapuje AI Search. Pomaga to zrozumieć, jak uprawnienia są wymuszane na poziomie dokumentu.

W czasie wykonywania zapytania Wyszukiwanie AI platformy Azure najpierw ocenia uprawnienia RBAC na poziomie kontenera, a następnie sprawdza wpisy ACL na poziomie dokumentu. Dostęp jest udzielany, jeśli zezwala na to jakikolwiek mechanizm.

Informacje o hierarchicznych uprawnieniach ACL

Indeksatory i źródła wiedzy mogą pobierać przypisania ACL z określonego kontenera oraz ze wszystkich katalogów prowadzących do każdego pliku, stosując się do hierarchicznego schematu oceny dostępu ADLS Gen2. Ostateczne efektywne listy dostępu dla każdego pliku są obliczane, a różne kategorie dostępu są indeksowane w odpowiednich polach indeksu.

Na przykład w typowych scenariuszach usługi ADLS Gen2 związanych z uprawnieniami, takich jak ścieżka pliku /Oregon/Portland/Data.txt.

Indeksator lub źródło wiedzy zbiera listy ACL z każdego kontenera i katalogu. Następnie określa efektywny dostęp na niższych poziomach i kontynuuje, dopóki nie określi uprawnień dla każdego pliku.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

Konfigurowanie usługi ADLS Gen2

Indeksator lub źródło wiedzy może pobrać listy kontroli dostępu na koncie magazynowym, jeśli zostaną spełnione następujące kryteria. Aby uzyskać więcej informacji na temat przypisań ACL, zobacz ADLS Gen2 ACL przypisań.

Autoryzacja

W przypadku indeksowania tożsamość usługi wyszukiwania musi mieć uprawnienie Czytelnik danych obiektu blob usługi Storage .

Jeśli testujesz lokalnie, musisz również mieć przypisanie roli Czytelnik danych obiektu blob usługi Storage . Aby uzyskać więcej informacji, zobacz Połączenie z Azure Storage przy użyciu tożsamości zarządzanej.

Uprawnienia kontenera głównego:

1. Przypisz wszystkie zestawy Group i User (podmioty zabezpieczeń) na poziomie kontenera głównego / z uprawnieniami Read i Execute.

2. Upewnij się, że zarówno Read jak i Execute są dodawane jako "Uprawnienia domyślne", aby automatycznie propagowały się do nowo utworzonych plików i katalogów.

Propagacja uprawnień w dół hierarchii plików

Mimo że nowe katalogi i pliki dziedziczą uprawnienia, istniejące katalogi i pliki nie dziedziczą automatycznie tych przypisań.

Użyj narzędzia ADLS Gen2, aby rekursywnie stosować listy kontroli dostępu (ACL) do propagacji przypisań w istniejącej zawartości. To narzędzie propaguje przypisania ACL kontenera głównego do wszystkich podkatalogów i plików.

Usuwanie nadmiarowych uprawnień

Po ponownym zastosowaniu list ACL przejrzyj uprawnienia dla każdego katalogu i pliku.

Usuń wszystkie zestawy Group lub User, które nie powinny mieć dostępu do określonych katalogów lub plików. Na przykład usuń User2 z folderu Portland/, a z folderu Idaho usuń Group2 i User2 z przypisań, i tak dalej.

Przykładowa struktura przydziałów ACL

Oto diagram struktury przypisywania ACL dla fikcyjnej hierarchii katalogów w dokumentacji usługi ADLS Gen2.

Aktualizowanie przypisań listy ACL z upływem czasu

Z czasem, kiedy nowe przypisania ACL są dodawane lub modyfikowane, powtórz powyższe kroki, aby zapewnić odpowiednie propagowanie i dopasowanie uprawnień. Zaktualizowane uprawnienia w usłudze ADLS Gen2 są aktualizowane w indeksie wyszukiwania podczas ponownego pozyskiwania zawartości przy użyciu indeksatora lub źródła wiedzy.

Konfigurowanie Wyszukiwanie AI platformy Azure

Pamiętaj, że usługa wyszukiwania musi mieć:

• Włączony dostęp oparty na rolach
• Skonfigurowano tożsamość zarządzaną

Autoryzacja

W przypadku indeksowania, klient wystawiający wywołanie interfejsu API musi mieć uprawnienia Współtwórcy usługi wyszukiwania do tworzenia obiektów, Współtwórcy danych indeksu wyszukiwania do importowania danych, oraz Czytelnika danych indeksu wyszukiwania do wykonywania zapytań dotyczących indeksu.

Jeśli testujesz lokalnie, musisz mieć te same przypisania ról. Aby uzyskać więcej informacji, zobacz Połączenie z Wyszukiwanie AI platformy Azure przy użyciu ról.

Konfigurowanie źródła wiedzy

Jeśli używasz źródła wiedzy, definicje w źródle wiedzy są używane do generowania kompletnego procesu indeksacji (indeksator, źródło danych i indeks). Przypisania listy kontroli dostępu (ACL) są wykrywane i automatycznie uwzględniane w wygenerowanym indeksie. Nie ma potrzeby modyfikowania żadnego z wygenerowanych obiektów, jeśli chcesz dziedziczenie uprawnień w indeksowanej zawartości.

Kluczowe kwestie dotyczące konfiguracji, które sprawiają, że działają w tym scenariuszu:

• isADLSGen2 parametr ma wartość true, spełniając wymagania dotyczące źródła danych dla tego scenariusza.
• ingestionPermissionOptions określa identyfikatory użytkowników i grup.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Konfigurowanie indeksowania opartego na indeksatorze

Jeśli używasz indeksatora, skonfiguruj go, źródło danych i indeks, aby pobrać metadane uprawnień z blobów danych usługi ADLS Gen2.

Tworzenie źródła danych

Ta sekcja uzupełnia dane Index z usługi ADLS Gen2 o informacje specyficzne dla wczytywania uprawnień i zawartości dokumentu do indeksu Wyszukiwanie AI platformy Azure.

• Typ źródła danych musi mieć wartość adlsgen2.

• Źródło danych musi zawierać indexerPermissionOptions z userIds, groupIds i/lub rbacScope.

  • W przypadku rbacScope skonfiguruj łańcuch połączenia w formacie tożsamości zarządzanej.

  • W przypadku parametrów połączenia, używając tożsamości zarządzanej przypisanej przez użytkownika, należy również określić właściwość identity.

Przykład JSON z tożsamością zarządzaną przez system:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Przykład schematu JSON z tożsamością zarządzaną przez użytkownika w parametry 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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Tworzenie pól uprawnień w indeksie

W Wyszukiwanie AI platformy Azure upewnij się, że indeks zawiera definicje pól metadanych uprawnień. Metadane uprawnień można indeksować, gdy indexerPermissionOptions jest określony w definicji źródła danych.

Zalecane atrybuty schematu dla ACL (UserIds, GroupIds) i zakresu RBAC:

• pole identyfikator użytkownika (ID) z wartością userIds permissionFilter.
• Pole Identyfikatory grup z wartością groupIds permissionFilter.
• Pole zakresu RBAC z wartością rbacScope permissionFilter.
• Właściwość permissionFilterOption umożliwiająca filtrowanie w czasie wykonywania zapytań.
• Użyj pól tekstowych dla metadanych uprawnień
• Ustaw filterable wartość true we wszystkich polach.

Zwróć uwagę, że retrievable jest to fałsz. Można ustawić wartość true podczas programowania, aby sprawdzić, czy uprawnienia są obecne, ale pamiętaj, aby przed wdrożeniem w środowisku produkcyjnym przywrócić wartość false.

Przykład schematu JSON:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Konfigurowanie indeksatora

Mapowania pól w indeksatorze ustawiają ścieżkę danych na pola w indeksie. Pola docelowe i miejsca docelowe, które różnią się w zależności od nazwy lub typu danych, wymagają jawnego mapowania pól. W usłudze ADLS Gen2, następujące pola metadanych mogą wymagać mapowania, jeśli zmienisz nazwę pola.

• metadata_user_ids (Collection(Edm.String)) — lista identyfikatorów użytkowników ACL.
• metadata_group_ids (Collection(Edm.String)) — lista identyfikatorów grup ACL.
• metadata_rbac_scope (Edm.String) — zakres RBAC kontenera.

Określ fieldMappings w indeksatorze, aby skierować metadane uprawnień do pól docelowych podczas indeksowania.

Przykład schematu JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Zalecenia i najlepsze rozwiązania

• Przed utworzeniem folderów należy dokładnie zaplanować strukturę folderów usługi ADLS Gen2.

• Organizuj tożsamości w grupy i używaj grup, jeśli to możliwe, zamiast udzielać dostępu bezpośrednio poszczególnym użytkownikom. Ciągłe dodawanie poszczególnych użytkowników zamiast stosowania grup zwiększa liczbę wpisów kontroli dostępu, które muszą być śledzone i oceniane. Nieprzestrzeganie tej najlepszej praktyki może prowadzić do częstszej aktualizacji metadanych zabezpieczeń wymaganych w indeksie, ponieważ zmieniają się te metadane, co powoduje zwiększone opóźnienia i nieefektywność w procesie odświeżania.

Synchronizowanie uprawnień między indeksowaną i źródłową zawartością

Włączenie kontroli dostępu ACL lub wzbogacenie RBAC w indeksatorze działa automatycznie tylko w dwóch sytuacjach:

• Pierwsze pełne indeksowanie/przeszukiwanie danych: wszystkie metadane uprawnień, które są dostępne w danym momencie dla każdego dokumentu, są przechwytywane.

• Zupełnie nowe dokumenty dodane po włączeniu obsługi list kontroli dostępu ACL/RBAC: ich informacje ACL/RBAC są przetwarzane wraz z zawartością.

Jeśli zmienisz uprawnienia dokumentu, takie jak dodanie użytkownika do listy ACL lub zaktualizowanie przypisania roli, zmiana nie zostanie wyświetlona w indeksie wyszukiwania, chyba że indeksator ponownie poinformuje indeksatora o przeszukaniu metadanych uprawnień dokumentu.

Wybierz jeden z następujących mechanizmów, w zależności od liczby zmienionych elementów:

Przykład interfejsu API resetdocs (wersja zapoznawcza):

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Przykład interfejsu API ponownej synchronizacji (wersja zapoznawcza):

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Śledzenie usuwania

Aby efektywnie zarządzać usuwaniem obiektów blob, upewnij się, że śledzenie usuwania jest włączone przed pierwszym uruchomieniem indeksatora. Ta funkcja umożliwia systemowi wykrywanie usuniętych obiektów blob w Twoim źródle i usuwanie ich z indeksu.

Powiązana zawartość

• Łączenie się z Wyszukiwanie AI platformy Azure przy użyciu ról
• Egzekwowanie listy ACL i kontroli dostępu opartej na rolach w czasie wyszukiwania
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API