Użyj indeksatora obiektów blob lub źródła wiedzy do pozyskiwania metadanych zakresów RBAC (wersja zapoznawcza)

Uwaga

Wyszukiwanie AI platformy Azure jest dostępna za pośrednictwem portalu Azure, interfejsów API REST i Azure SDKs. Jest także podstawą Foundry IQ — zarządzanej warstwy wiedzy, która przekształca treści przedsiębiorstwa w bazy wiedzy wielokrotnego użytku z uwzględnieniem uprawnień dla agentów w portalu Microsoft Foundry.

Ważna

Funkcje, możliwości lub właściwości oznaczone (wersja zapoznawcza) nie są objęte umową dotyczącą poziomu usług, nie są zalecane w przypadku obciążeń produkcyjnych i mogą ulec zmianie lub ograniczeniu, zanim staną się one ogólnie dostępne. Warunki Wyszukiwanie AI platformy Azure wersji zapoznawczej mają zastosowanie do wszystkich funkcji w wersji zapoznawczej, niezależnie od tego, czy jest ona autonomiczna, czy częścią ogólnie dostępnej funkcji.

Azure Storage umożliwia dostęp oparty na rolach w kontenerach w magazynie obiektów blob, w których role takie jak Storage Blob Data Reader lub Storage Blob Data Contributor określają, czy ktoś ma dostęp do zawartości. Wyszukiwanie AI platformy Azure obsługuje pozyskiwanie uprawnień użytkownika (wersja zapoznawcza) wraz z pozyskiwaniem dokumentów, dzięki czemu można użyć tych uprawnień do kontrolowania dostępu do wyników wyszukiwania. Jeśli użytkownik nie ma uprawnień do określonego katalogu lub pliku w Azure Storage, nie ma dostępu do odpowiednich dokumentów w wynikach Wyszukiwanie AI platformy Azure, nawet jeśli ty osobiście masz przypisane Search Index Data Readerdo indeksu.

  • Od wersji 2025-05-01-preview i nowszych, metadane zakresów RBAC można pobierać za pomocą indeksatora blobów.
  • 2025-11-01-preview i nowsze wersje zapewniają równoważną obsługę źródeł wiedzy Blob w usłudze Azure Storage.

Zakres RBAC jest ustawiany na poziomie kontenera i rozciąga się na wszystkie bloby (dokumenty) dzięki dziedziczeniu uprawnień. Zakres RBAC jest przechwytywany podczas indeksowania w formie metadanych uprawnień. Możesz używać push API do ręcznego przekazywania i indeksowania zawartości oraz metadanych uprawnień (zobacz Uprawnienia indeksowania przy użyciu push REST API), lub wykorzystać indeksator lub zasób wiedzy w celu zautomatyzowania pozyskiwania danych. Ten artykuł koncentruje się na automatyzacji indeksowania.

W czasie zapytania tożsamość obiektu wywołującego jest zawarta w nagłówku żądania za pośrednictwem parametru x-ms-query-source-authorization . Tożsamość musi być zgodna z metadanymi uprawnień w dokumentach, jeśli użytkownik ma wyświetlać wyniki wyszukiwania.

Ten artykuł koncentruje się na podejściach automatyzacji indeksowania opartych na tej podstawie:

Wymagania wstępne

  • Microsoft Entra ID uwierzytelnianie i autoryzacja. Usługi i aplikacje muszą znajdować się w tej samej dzierżawie. Użytkownicy mogą należeć do różnych dzierżawców, pod warunkiem że wszyscy są z "Microsoft Entra ID." Przypisania ról są używane dla każdego uwierzytelnionego połączenia.

  • Wyszukiwanie AI platformy Azure w jakimkolwiek regionie, ale musisz mieć plan płatny (podstawowy lub wyższy) do obsługiwania tożsamości zarządzanych. Usługa wyszukiwania musi być skonfigurowana pod kątem dostępu opartego na rolach i musi mieć tożsamość zarządzaną (system lub użytkownik).

  • Azure Storage, Standardowa wydajność (ogólnego przeznaczenia w wersji 2), w warstwach dostępu Gorąca, Chłodna i Zimna, z kontenerami lub obiektami blob zabezpieczonymi za pomocą kontroli dostępu opartej na rolach.

  • Należy zrozumieć, jak działają indeksatory i źródła wiedzy oraz jak utworzyć indeks. W tym artykule wyjaśniono ustawienia konfiguracji źródła danych i indeksatora, ale nie udostępnia kroków tworzenia indeksu. Aby uzyskać więcej informacji na temat indeksów przeznaczonych dla filtrów uprawnień, zobacz Tworzenie indeksu z polami filtru uprawnień.

Ograniczenia

Konfigurowanie Blob Storage

Proszę sprawdzić, czy kontener obiektów blob korzysta z dostępu opartego na rolach.

  1. Zaloguj się do portalu Azure i znajdź swoje konto magazynowe.

  2. Rozwiń kontenery i wybierz kontener, który ma obiekty blob, które chcesz indeksować.

  3. Wybierz pozycję Access Control (IAM) aby sprawdzić przypisania ról. Użytkownicy i grupy z czytnikiem danych obiektu blob usługi Storage lub współautorem danych obiektu blob usługi Storage mają dostęp do przeszukiwania dokumentów w indeksie po indeksie kontenera.

Autoryzacja

Aby wykonać indeksator, identyfikator usługi wyszukiwania musi mieć uprawnienie 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.

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

Autoryzacja

W przypadku wykonywania indeksatora klient wystawiający wywołanie interfejsu API musi mieć uprawnienia Search Service Contributor do tworzenia obiektów, Search Index Data Contributor do przeprowadzania importowania danych oraz Search Index Data Reader do wykonywania zapytań dotyczących indeksu. Zobacz Łączenie z Wyszukiwanie AI platformy Azure za pomocą 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). Zakres kontroli dostępu opartej na rolach jest wykrywany i automatycznie uwzględniany 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 jest ustawiona na wartość false, co oznacza, że źródło danych jest Azure Blob Storage.
  • ingestionPermissionOptions określa rbacScope.
# 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": false,
        "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": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Dokumentacja:tworzenie lub aktualizowanie źródła wiedzy (interfejs API REST)

Konfigurowanie indeksowania opartego na indeksatorze

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

Tworzenie źródła danych

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

  • Tryb analizowania źródła danych musi być domyślny.

  • Źródło danych musi mieć indexerPermissionOptions z rbacScope.

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

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

Przykład schematu JSON z tożsamością zarządzaną przez użytkownika w parametry połączenia:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "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 zakresu RBAC:

  • 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 ustawić ją z powrotem na false przed wdrożeniem do środowiska produkcyjnego, aby tożsamości podmiotów zabezpieczeń nie były widoczne w wynikach.

Przykład schematu JSON:

{
  ...
  "fields": [
    ...
    { 
        "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. Następujące pola metadanych w Azure Blob Storage mogą wymagać mapowania pól, jeśli nazwa pola jest różna:

  • 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_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Uruchamianie indeksatora

Po skonfigurowaniu indeksatora, źródła danych i indeksu uruchom indeksator, aby rozpocząć proces. Jeśli wystąpi problem z konfiguracją lub uprawnieniami, te problemy pojawią się w tym kroku.

Domyślnie indeksator jest uruchamiany natychmiast po opublikowaniu go w usłudze wyszukiwania, ale jeśli konfiguracja indeksatora ma disabled wartość true, indeksator jest publikowany w stanie wyłączonym, aby można było uruchomić indeksator ręcznie.

Zalecamy uruchomić indeksator z portalu Azure, aby móc monitorować stan i komunikaty.

Przy założeniu, że indeks nie zawiera żadnych błędów, jest teraz wypełniany i można przejść do przodu za pomocą zapytań i testów.

Śledzenie usuwania

Aby skutecznie zarządzać usuwaniem obiektów blob, upewnij się, że włączono śledzenie usuwania przed uruchomieniem indeksatora po raz pierwszy. Ta funkcja umożliwia systemowi wykrywanie usuniętych obiektów blob ze źródła i usuwanie odpowiedniej zawartości z indeksu.

Zobacz też

  • Ostatnia aktualizacja o