Usa un indicizzatore blob o un'origine conoscenze per acquisire i metadati relativi agli ambiti RBAC (anteprima)

Nota

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

Important

Le funzionalità, le funzionalità o le proprietà contrassegnate (anteprima) non sono coperte da un contratto di servizio, non sono consigliate per i carichi di lavoro di produzione e potrebbero cambiare o essere vincolate prima che diventino disponibili a livello generale. Le condizioni di anteprima Azure AI Search si applicano a tutte le funzionalità di anteprima, indipendente o parte di una funzionalità disponibile a livello generale.

Archiviazione di Azure consente l'accesso basato sui ruoli nei contenitori nell'archiviazione BLOB, in cui ruoli come Lettore Dati BLOB di Archiviazione o Collaboratore Dati BLOB di Archiviazione determinano se un utente ha accesso al contenuto. Azure AI Search supporta l'inserimento di autorizzazioni utente (anteprima) insieme all'inserimento di documenti in modo da poter usare tali autorizzazioni per controllare l'accesso ai risultati della ricerca. Se un utente non dispone delle autorizzazioni per una directory o un file specifico in Archiviazione di Azure, tale utente non ha accesso ai documenti corrispondenti nei risultati di Azure AI Search, anche se personalmente si dispone di un'assegnazione di Search Index Data Reader sull'indice.

  • 2025-05-01-preview e versioni successive, i metadati degli ambiti RBAC possono essere inseriti usando l'indicizzatore BLOB.
  • A partire dalla versione 2025-11-01-preview, è disponibile un supporto equivalente per le fonti di conoscenza BLOB in Archiviazione di Azure.

L'ambito del controllo degli accessi in base al ruolo viene impostato a livello di contenitore e passa a tutti i BLOB (documenti) tramite l'ereditarietà delle autorizzazioni di accesso. L'ambito di RBAC viene acquisito durante l'indicizzazione come metadati delle autorizzazioni. È possibile usare le API push per caricare e indicizzare manualmente il contenuto e i metadati delle autorizzazioni (vedere Autorizzazioni di indicizzazione tramite l'API REST push) oppure è possibile usare un indicizzatore o un'origine conoscenze per automatizzare l'inserimento dei dati. Questo articolo è incentrato sull'automazione dell'indicizzazione.

In fase di query, l'identità del chiamante viene inclusa nell'intestazione della richiesta tramite il x-ms-query-source-authorization parametro . L'identità deve corrispondere ai metadati delle autorizzazioni per i documenti se l'utente deve visualizzare i risultati della ricerca.

Questo articolo è incentrato sugli approcci di automazione dell'indicizzazione basati su questa base:

Prerequisiti

  • Autenticazione e autorizzazione di Microsoft Entra ID. I servizi e le app devono trovarsi nello stesso tenant. Gli utenti possono trovarsi in tenant diversi purché tutti i tenant siano Microsoft Entra ID. Le assegnazioni di ruolo vengono usate per ogni connessione autenticata.

  • Azure AI Search, qualsiasi area, ma è necessario avere un livello fatturabile (basic e superiore) per il supporto delle identità gestite. Il servizio di ricerca deve essere configurato per l'accesso basato sui ruoli e deve avere un'identità gestita (sistema o utente).

  • Archiviazione di Azure, prestazioni Standard (utilizzo generico v2), nei livelli di accesso frequente, ad accesso sporadico e sporadico, con contenitori o BLOB protetti con controllo degli accessi in base al ruolo.

  • È necessario comprendere come funzionano gli indicizzatori e le origini conoscenze e come creare un indice. Questo articolo illustra le impostazioni di configurazione per l'origine dati e l'indicizzatore, ma non fornisce i passaggi per la creazione dell'indice. Per altre informazioni sugli indici progettati per i filtri di autorizzazione, vedere Creare un indice con campi di filtro delle autorizzazioni.

Limitations

Configurare l'archiviazione Blob

Verificare che il blob container utilizzi l'accesso in base al ruolo.

  1. Accedere al portale di Azure e trovare l'account di archiviazione.

  2. Espandere i contenitori e selezionare il contenitore con i BLOB da indicizzare.

  3. Selezionare Controllo di accesso (IAM) per controllare le assegnazioni di ruolo. Gli utenti e i gruppi con Storage Blob Data Reader o Storage Blob Data Contributor hanno accesso ai documenti di ricerca nell'indice dopo che il contenitore è stato indicizzato.

Autorizzazione

Per l'esecuzione dell'indicizzatore, l'identità del servizio di ricerca deve disporre dell'autorizzazione Lettore dati BLOB di archiviazione. Per altre informazioni, vedere Connetti ad Archiviazione di Azure utilizzando un'identità gestita.

Tenere presente che il servizio di ricerca deve avere:

Autorizzazione

Per l'esecuzione dell'indicizzatore, il client che esegue la chiamata API deve disporre dell'autorizzazione Search Service Contributor per creare oggetti. Search Index Data Contributor autorizzazione per eseguire l'importazione dei dati e Search Index Data Reader per eseguire query su un indice, vedere Connect to Azure AI Search using roles.

Configurare un'origine conoscenza

Se si utilizza un'origine della conoscenza, le definizioni nell'origine della conoscenza vengono usate per generare una pipeline di indicizzazione completa (indicizzatore, origine dati e indice). L'ambito RBAC viene rilevato e incluso automaticamente nell'indice generato. Non è necessario modificare uno degli oggetti generati se si vuole l'ereditarietà delle autorizzazioni nel contenuto indicizzato.

Punti chiave sulla configurazione che lo rendono funzionante per questo scenario:

  • isADLSGen2 è impostato su false, il che significa che l'origine dati è Archiviazione BLOB di Azure.
  • ingestionPermissionOptions specifica 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}}"
            }
        }
    }
}

Reference:Create or Update Knowledge Source (API REST)

Configurare l'indicizzazione basata su indicizzatore

Se stai usando un indicizzatore, configura l'indicizzatore stesso, l'origine dati e l'indice per recuperare i metadati delle autorizzazioni dai BLOB.

Creare l'origine dati

  • Il tipo di origine dati deve essere azureblob.

  • La modalità di analisi dell'origine dati deve essere l'impostazione predefinita.

  • L'origine dati deve avere indexerPermissionOptions con rbacScope.

Esempio JSON con identità gestita dal sistema e 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>"
    }
}

Esempio di schema JSON con un'identità gestita dall'utente nel stringa di connessione:

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

Creare campi di autorizzazione nell'indice

In Azure AI Search verificare che l'indice contenga definizioni di campo per i metadati delle autorizzazioni. I metadati di autorizzazione possono essere indicizzati quando indexerPermissionOptions viene specificato nella definizione dell'origine dati.

Ambito del controllo RBAC per gli attributi di schema consigliati:

  • Campo dell'ambito RBAC con il valore rbacScope permissionFilter.
  • Proprietà permissionFilterOption per abilitare il filtro durante la query.
  • Usare i campi stringa per i metadati delle autorizzazioni
  • Impostare filterable su true in tutti i campi.

Si noti che retrievable è false. È possibile impostare true durante lo sviluppo per verificare che le autorizzazioni siano presenti, ma ricordarsi di reimpostare su false prima di eseguire la distribuzione in un ambiente di produzione affinché le identità dell'entità di sicurezza non siano visibili nei risultati.

Esempio di schema JSON:

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

Configurare l'indicizzatore

Il mapping dei campi all'interno di un indicizzatore imposta il percorso dei dati ai campi di un indice. I campi di origine e di destinazione che variano in base al nome o al tipo di dati richiedono un mapping dei campi esplicito. I campi di metadati seguenti in Archiviazione BLOB di Azure potrebbero richiedere mapping dei campi se si modifica il nome del campo:

  • metadata_rbac_scope (Edm.String): ambito RBAC del contenitore.

Specificare fieldMappings nell'indicizzatore per instradare i metadati delle autorizzazioni ai campi di destinazione durante l'indicizzazione.

Esempio di schema JSON:

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

Eseguire l'indicizzatore

Dopo aver configurato l'indicizzatore, l'origine dati e l'indice, esegui l'indicizzatore per avviare il processo. Se si verifica un problema con la configurazione o le autorizzazioni, questi problemi si verificano in questo passaggio.

Per impostazione predefinita, un indicizzatore viene eseguito non appena lo si pubblica in un servizio di ricerca, ma se la configurazione dell'indicizzatore include disabled impostato su true, l'indicizzatore viene pubblicato in uno stato disabilitato in modo da poter eseguire manualmente l'indicizzatore.

È consigliabile eseguire l'indicizzatore dal portale di Azure in modo da poter monitorare lo stato e i messaggi.

Supponendo che non siano presenti errori, l'indice è ora popolato ed è possibile procedere con query e test.

Rilevamento delle eliminazioni

Per gestire in modo efficace l'eliminazione dei BLOB, assicurarsi di aver abilitato il rilevamento delle eliminazioni prima che l'indicizzatore venga eseguito per la prima volta. Questa funzionalità consente al sistema di rilevare i BLOB eliminati dall'origine ed eliminare il contenuto corrispondente dall'indice.

Vedere anche

  • Ultimo aggiornamento: