Een blobindexeerfunctie of kennisbron gebruiken om metagegevens van RBAC-bereiken op te nemen (preview)

Opmerking

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Important

Functies, mogelijkheden of eigenschappen die zijn gemarkeerd (preview) vallen niet onder een service level agreement, worden niet aanbevolen voor productieworkloads en kunnen worden gewijzigd of beperkt voordat ze algemeen beschikbaar worden. De Azure AI Zoeken preview-voorwaarden zijn van toepassing op alle preview-functionaliteit, ongeacht of deze zelfstandig is of deel uitmaakt van een algemeen beschikbare functie.

Azure Storage maakt toegang op basis van rollen mogelijk voor containers in blobopslag, waarbij rollen zoals Storage Blob Data Reader of Storage Blob Data Contributor bepalen of iemand toegang heeft tot inhoud. Azure AI Zoeken ondersteunt het opnemen van gebruikersmachtigingen (preview) naast documentopname, zodat u deze machtigingen kunt gebruiken om de toegang tot zoekresultaten te beheren. Als een gebruiker geen machtigingen heeft voor een specifieke map of bestand in Azure Storage, heeft die gebruiker geen toegang tot de bijbehorende documenten in Azure AI Zoeken resultaten, zelfs als u persoonlijk een Search Index Data Reader toewijzing hebt on de index.

  • 2025-05-01-preview en hoger, metagegevens van RBAC-bereiken kunnen worden opgenomen met behulp van de Blob-indexeerfunctie.
  • 2025-11-01-preview en hoger biedt gelijkwaardige ondersteuning voor Blob-kennisbronnen in Azure Storage.

Het RBAC-bereik wordt ingesteld op containerniveau en wordt via overname van machtigingen naar alle blobs (documenten) gestroomd. Het RBAC-bereik wordt vastgelegd tijdens het indexeren als metagegevens van machtigingen. U kunt de push-API's gebruiken om inhoud en metagegevens van machtigingen handmatig te uploaden en te indexeren (zie Indexeringsmachtigingen met behulp van de PUSH REST API), of u kunt een indexeerfunctie of kennisbron gebruiken om gegevensopname te automatiseren. Dit artikel richt zich op de automatisering van het indexeren.

Tijdens de query wordt de identiteit van de aanroeper via de x-ms-query-source-authorization parameter opgenomen in de aanvraagheader. De identiteit moet overeenkomen met de machtigingsmetagegevens voor documenten als de gebruiker de zoekresultaten moet zien.

Dit artikel is gericht op de automatiseringsmethoden voor indexering, gebaseerd op deze basis:

Voorwaarden

  • Microsoft Entra ID verificatie en autorisatie. Services en apps moeten zich in dezelfde tenant bevinden. Gebruikers kunnen zich in verschillende tenants bevinden, zolang alle tenants Microsoft Entra ID gebruiken. Roltoewijzingen worden gebruikt voor elke geverifieerde verbinding.

  • Azure AI Zoeken, elke regio, maar u moet een factureerbare laag (basic en hoger) hebben voor ondersteuning van beheerde identiteiten. De zoekservice moet worden geconfigureerd voor op rollen gebaseerde toegang en moet een beheerde identiteit (systeem of gebruiker) hebben.

  • Azure Storage, Standaardprestaties (algemeen gebruik v2), op warme, koele en koude toegangslagen, met RBAC-beveiligde containers of blobs.

  • U moet begrijpen hoe indexeerfuncties en kennisbronnen werken en hoe u een index maakt. In dit artikel worden de configuratie-instellingen voor de gegevensbron en indexeerfunctie uitgelegd, maar bevat geen stappen voor het maken van de index. Zie Een index maken met machtigingsfiltervelden voor meer informatie over indexen die zijn ontworpen voor machtigingsfilters.

Limitations

  • Azure Portal biedt geen ondersteuning voor deze functie.

  • De volgende indexeerfuncties bieden geen ondersteuning voor overname van machtigingen in geïndexeerde documenten die afkomstig zijn van ADLS Gen2. Als u een van deze functies gebruikt in een vaardighedenset of indexeerfunctie, worden machtigingen op documentniveau niet opgenomen in de geïndexeerde inhoud.

Blob Storage configureren

Controleer of uw blobcontainer gebruikmaakt van op rollen gebaseerde toegang.

  1. Meld u aan bij de Azure-portal en zoek uw opslagaccount.

  2. Vouw containers uit en selecteer de container met de blobs die u wilt indexeren.

  3. Selecteer Access Control (IAM) om roltoewijzingen te controleren. Gebruikers en groepen met Opslagblobgegevenslezer of Inzender voor opslagblobgegevens hebben toegang tot het doorzoeken van documenten in de index nadat de container is geïndexeerd.

Vergunning

Voor de uitvoering van de indexeerfunctie moet uw zoekservice-id beschikken over de machtiging Opslagblobgegevenslezer . Zie Connect to Azure Storage using a managed identity voor meer informatie.

Zoals u weet, moet de zoekservice beschikken over:

Vergunning

Voor de uitvoering van de indexeerfunctie moet de client die de API-aanroep uitgeeft, Search Service Contributor machtiging hebben om objecten te maken, Search Index Data Contributor machtiging voor het importeren van gegevens en Search Index Data Reader om een query uit te voeren op een index, zie Connect to Azure AI Zoeken using roles.

Een kennisbron configureren

Als u een kennisbron gebruikt, worden definities in de kennisbron gebruikt om een volledige indexeringspijplijn (indexeerfunctie, gegevensbron en index) te genereren. Het RBAC-bereik wordt gedetecteerd en automatisch opgenomen in de gegenereerde index. Het is niet nodig om een van de gegenereerde objecten te wijzigen als u de overname van machtigingen in uw geïndexeerde inhoud wilt.

Belangrijke punten over de configuratie waarmee deze werkt voor dit scenario:

  • isADLSGen2 is ingesteld op false, wat betekent dat de gegevensbron is Azure Blob Storage.
  • ingestionPermissionOptions specificeert 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}}"
            }
        }
    }
}

Naslaginformatie:Knowledge Source maken of bijwerken (REST API)

Indexeerfunctie-gebaseerde indexering configureren

Als u een indexeerfunctie gebruikt, configureert u deze, de gegevensbron en de index om metagegevens van machtigingen op te halen uit blobs.

De gegevensbron maken

  • Het gegevensbrontype moet zijn azureblob.

  • De parseringsmodus voor gegevensbronnen moet de standaardmodus zijn.

  • De gegevensbron moet indexerPermissionOptions hebben met rbacScope.

JSON-voorbeeld met door het systeem beheerde identiteit en 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>"
    }
}

Voorbeeld van een JSON-schema met een door de gebruiker beheerde identiteit in de verbindingsreeks:

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

Machtigingsvelden maken in de index

Controleer in Azure AI Zoeken of uw index velddefinities bevat voor de machtigingsmetagegevens. Machtigingsmetagegevens kunnen worden geïndexeerd wanneer indexerPermissionOptions deze is opgegeven in de definitie van de gegevensbron.

Aanbevolen schemakenmerken voor RBAC-scope:

  • RBAC-bereikveld met rbacScope permissionFilter-waarde.
  • Eigenschap permissionFilterOption voor het inschakelen van filteren tijdens het uitvoeren van query's.
  • Stringvelden gebruiken voor machtigingsmetagegevens
  • Stel filterable in op waar voor alle velden.

U ziet dat dit retrievable onwaar is. U kunt het op 'waar' zetten tijdens de ontwikkeling om te controleren of de machtigingen aanwezig zijn, maar vergeet niet om het weer op 'onwaar' te zetten voordat u implementeert in een productieomgeving, zodat identiteiten van beveiligingsprincipes niet zichtbaar zijn in de resultaten.

JSON-schemavoorbeeld:

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

De indexeerfunctie configureren

Veldtoewijzingen in een indexer leggen het gegevenspad naar velden in een index. Voor doel- en doelvelden die per naam of gegevenstype variëren, is een expliciete veldtoewijzing vereist. De volgende metagegevensvelden in Azure Blob Storage hebben mogelijk veldtoewijzingen nodig als u de veldnaam wijzigt:

  • metadata_rbac_scope (Edm.String) - het RBAC-bereik van de container.

Geef fieldMappings in de indexeerfunctie op om de machtigingsmetagegevens tijdens het indexeren te routeren naar doelvelden.

JSON-schemavoorbeeld:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

De indexeerfunctie uitvoeren

Nadat uw indexeerfunctie, gegevensbron en index zijn geconfigureerd, voert u de indexeerfunctie uit om het proces in te stellen. Als er een probleem is met de configuratie of machtigingen, treden deze problemen op in deze stap.

Standaard wordt een indexeerfunctie uitgevoerd zodra u deze in een zoekservice plaatst, maar als de configuratie disabled van de indexeerfunctie is ingesteld op true, wordt de indexeerfunctie in een uitgeschakelde status geplaatst, zodat u de indexeerfunctie handmatig kunt uitvoeren.

Het wordt aanbevolen om de indexer vanuit de Azure-portal te runnen, zodat u de status en berichten kunt controleren.

Ervan uitgaande dat er geen fouten zijn, wordt de index nu ingevuld en kunt u verdergaan met query's en testen.

Verwijdering bijhouden

Als u het verwijderen van blobs effectief wilt beheren, moet u ervoor zorgen dat u het bijhouden van verwijderingen hebt ingeschakeld voordat uw indexeerfunctie voor het eerst wordt uitgevoerd. Met deze functie kan het systeem verwijderde blobs uit uw bron detecteren en de bijbehorende inhoud uit de index verwijderen.

Zie ook

  • Laatst bijgewerkt om