Connettersi a Azure AI Search usando i ruoli

Azure offre un'autenticazione globale e un controllo degli accessi in base al ruolo tramite Microsoft Entra ID per tutti i servizi in esecuzione nella piattaforma. Questo articolo illustra i ruoli che forniscono l'accesso al contenuto di ricerca e all'amministrazione in Ricerca di intelligenza artificiale di Azure.

In Azure AI Search è possibile assegnare ruoli di Azure per:

• Amministrazione del servizio
• Sviluppo o accesso in scrittura a un servizio di ricerca
• Accesso in sola lettura per le query
• Accesso con ambito limitato a un singolo indice

L'accesso per utente ai risultati della ricerca (talvolta definito sicurezza a livello di riga o sicurezza a livello di documento) non è supportato tramite le assegnazioni di ruolo. Come soluzione alternativa, creare filtri di sicurezza che tagliano i risultati in base all'identità utente, rimuovendo i documenti ai quali il richiedente non deve avere accesso. Per una dimostrazione, vedere questo esempio di chat aziendale tramite RAG.

Le assegnazioni di ruolo sono cumulative e diffuse su tutti gli strumenti e le librerie client. È possibile assegnare ruoli usando uno degli approcci supportati descritti nella documentazione sul controllo degli accessi in base al ruolo di Azure.

L'accesso basato sui ruoli è facoltativo, ma consigliato. L'alternativa è l’autenticazione basata su chiave, ovvero l'impostazione predefinita.

Prerequisiti

• Un servizio di ricerca in qualsiasi area, a qualsiasi livello, abilitato per l'accesso basato sui ruoli.

• Proprietario, Amministratore accesso utenti, Amministratore Controllo di accesso basato su ruoli o un ruolo personalizzato con autorizzazioni Microsoft.Authorization/roleAssignments/write.

Come assegnare ruoli nel portale

La procedura seguente funziona per tutte le assegnazioni di ruolo.

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Abilitare l'accesso in base al ruolo.

4. Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.

5. Selezionare + Aggiungi aggiungi>assegnazione di ruolo per avviare la procedura guidata Aggiungi assegnazione di ruolo.

   

6. Selezionare un ruolo. È possibile assegnare più entità di sicurezza, sia utenti che identità gestite a un ruolo in un solo passaggio della procedura guidata, ma è necessario ripetere questi passaggi per ogni ruolo definito.

7. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio di Azure, selezionare un'identità gestita dal sistema o dall'utente.

8. Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.

Ruoli predefiniti usati nella ricerca

Il piano dati fa riferimento alle operazioni sull'endpoint del servizio di ricerca, ad esempio l'indicizzazione o le query, o qualsiasi altra operazione specificata nelle API REST del servizio di ricerca o nelle librerie client equivalenti di Azure SDK.

Il piano di controllo si riferisce alla gestione delle risorse di Azure, ad esempio la creazione o la configurazione di un servizio di ricerca.

Vengono compilati i ruoli seguenti. Se questi ruoli non sono sufficienti, creare un ruolo personalizzato.

Ruolo	Plane	Descrizione
Proprietario	Controllo e dati	Accesso completo al piano di controllo della risorsa di ricerca, inclusa la possibilità di assegnare ruoli di Azure. Solo il ruolo Proprietario può abilitare o disabilitare le opzioni di autenticazione o gestire i ruoli per altri utenti. Gli amministratori delle sottoscrizioni sono membri per impostazione predefinita. Nel piano dati, questo ruolo ha lo stesso accesso del ruolo Collaboratore del servizio di ricerca. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query o indicizzare documenti.
Collaboratore	Controllo e dati	Stesso livello di accesso al piano di controllo del ruolo Proprietario, ma senza la possibilità di assegnare ruoli o modificare le opzioni di autenticazione. Nel piano dati, questo ruolo ha lo stesso accesso del ruolo Collaboratore del servizio di ricerca. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query o indicizzare documenti.
Lettore	Controllo e dati	Accesso in lettura sull’intero servizio, incluse le metriche di ricerca, le metriche del contenuto (archiviazione utilizzata, numero di oggetti) e le definizioni degli oggetti delle risorse del piano dati (indici, indicizzatori e così via). Tuttavia, non può leggere le chiavi API né il contenuto all'interno degli indici.
Collaboratore servizi di ricerca	Controllo e dati	Accesso in lettura/scrittura alle definizioni di oggetti (indici, alias, mappe sinonimi, indicizzatori, origini dati e set di competenze). Questo ruolo è destinato agli sviluppatori che creano oggetti e agli amministratori che gestiscono un servizio di ricerca e i relativi oggetti, ma senza accesso al contenuto dell'indice. Usare questo ruolo per creare, eliminare ed elencare indici, ottenere definizioni di indice, ottenere informazioni sul servizio (statistiche e quote), testare analizzatori, creare e gestire mappe sinonimiche, indicizzatori, origini dati e set di competenze. Vedere Microsoft.Search/searchServices/* per consultare l'elenco delle autorizzazioni.
Collaboratore ai dati dell'indice di ricerca	Dati	Accesso in lettura/scrittura al contenuto degli indici. Questo ruolo è destinato agli sviluppatori o ai proprietari di indici che devono importare, aggiornare o eseguire query sulla raccolta documenti di un indice. Questo ruolo non supporta la creazione o la gestione degli indici. Per impostazione predefinita, questo ruolo è per tutti gli indici in un servizio di ricerca. Vedere Concedere l'accesso a un singolo indice per restringere l'ambito.
Lettore di dati dell'indice di ricerca	Dati	Accesso in sola lettura per l'esecuzione di query sugli indici di ricerca. Questo ruolo è destinato ad app e utenti che eseguono query. Questo ruolo non supporta l'accesso in lettura alle definizioni degli oggetti. Ad esempio, non è possibile leggere la definizione di un indice di ricerca o ottenere statistiche del servizio di ricerca. Per impostazione predefinita, questo ruolo è per tutti gli indici in un servizio di ricerca. Vedere Concedere l'accesso a un singolo indice per restringere l'ambito.

Combinare questi ruoli per ottenere autorizzazioni sufficienti per il caso d’uso.

Nota

Se si disabilita l'accesso in base al ruolo di Azure, i ruoli predefiniti per il piano di controllo (Proprietario, Collaboratore, Lettore) continuano a essere disponibili. La disabilitazione dell'accesso basato sui ruoli rimuove solo le autorizzazioni correlate ai dati associate a tali ruoli. Se i ruoli del piano dati sono disabilitati, Collaboratore del servizio di ricerca equivale a Collaboratore del piano di controllo.

Riepilogo

Autorizzazioni	Lettore di dati dell'indice di ricerca	Collaboratore ai dati dell'indice di ricerca	Collaboratore servizi di ricerca	Proprietario/Collaboratore	Lettore
Visualizzare la risorsa nel portale di Azure	❌	❌	✅	✅	✅
Visualizzare le proprietà delle risorse/metriche/endpoint	❌	❌	✅	✅	✅
Elencare tutti gli oggetti nella risorsa	❌	❌	✅	✅	✅
Quote di accesso e statistiche del servizio	❌	❌	✅	✅	❌
Lettura/query di un indice	✅	❌	❌	❌	❌
Caricare i dati per l'indicizzazione	❌	✅	❌	❌	❌
Creare o modificare indici/alias	❌	❌	✅	✅	❌
Creare, modificare ed eseguire indicizzatori/origini dati/set di competenze	❌	❌	✅	✅	❌
Creare o modificare mappe sinonimi	❌	❌	✅	✅	❌
Creare o modificare sessioni di debug	❌	❌	✅	✅	❌
Creare o gestire distribuzioni	❌	❌	✅	✅	❌
Creare o configurare risorse di Ricerca intelligenza artificiale di Azure	❌	❌	✅	✅	❌
Visualizzare/Copiare/Rigenerare le chiavi in Chiavi	❌	❌	✅	✅	❌
Visualizzare ruoli/criteri/definizioni	❌	❌	✅	✅	❌
Impostare le opzioni di autenticazione	❌	❌	✅	✅	❌
Configurare connessioni private	❌	❌	✅	✅	❌
Configurare la sicurezza di rete	❌	❌	✅	✅	❌

I proprietari e i collaboratori concedono le stesse autorizzazioni, ad eccezione del fatto che solo i proprietari possono assegnare ruoli.

I proprietari e i collaboratori possono creare, leggere, aggiornare ed eliminare oggetti nel portale di Azure se sono abilitate le chiavi API. Il portale usa le chiavi nelle chiamate interne alle API del piano dati. In seguito si configura Ricerca intelligenza artificiale di Azure per usare "solo ruoli", il proprietario e il collaboratore non saranno in grado di gestire gli oggetti nel portale usando solo tali assegnazioni di ruolo. La soluzione consiste nell'assegnare più ruoli, ad esempio Lettore dati indice di ricerca, Collaboratore dati indice di ricerca e Collaboratore servizio di ricerca.

Assegnazione di ruoli

In questa sezione assegnare ruoli per:

• Amministrazione del servizio
• Sviluppo o accesso in scrittura a un servizio di ricerca
• Accesso in sola lettura per le query

Assegnare ruoli per l'amministrazione del servizio

Gli amministratori del servizio possono creare e configurare un servizio di ricerca ed eseguire tutte le operazioni del piano di controllo descritte nell'API REST di gestione o nelle librerie client equivalenti. Se si è un proprietario o un collaboratore, è anche possibile eseguire la maggior parte delle attività dell'API REST di ricerca del piano dati nella portale di Azure.

Ruolo	ID
Owner	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure portal

1. Accedere al portale di Azure.

2. Assegnare questi ruoli:

   • Proprietario (accesso completo a tutte le operazioni del piano dati e del piano di controllo, ad eccezione delle autorizzazioni di query)
   • Collaboratore (uguale a Proprietario, ad eccezione delle autorizzazioni per assegnare i ruoli)
   • Lettore (accettabile per il monitoraggio e la visualizzazione delle metriche)

PowerShell

Quando si usa PowerShell per assegnare ruoli, chiamare New-AzRoleAssignment, specificando il nome dell’utente o del gruppo di Azure e l'ambito dell'assegnazione.

In questo esempio viene creata un'assegnazione di ruolo con ambito definito per un servizio di ricerca:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Assegnare ruoli per lo sviluppo

Le assegnazioni di ruolo sono globali su tutto il servizio di ricerca. Per definire l'ambito delle autorizzazioni per un singolo indice, usare PowerShell o l'interfaccia della riga di comando di Azure per creare un ruolo personalizzato.

Attività	Ruolo	ID
Operazioni CRUD	Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Caricare documenti ed eseguire processi di indicizzazione	Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Eseguire una query su un indice	Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

Un'altra combinazione di ruoli che fornisce l'accesso completo è Collaboratore o Proprietario, oltre a Lettore dati dell’indice di ricerca.

Importante

Se si configura l’accesso in base al ruolo per un servizio o un indice e si fornisce anche una chiave API nella richiesta, il servizio di ricerca usa la chiave API per l’autenticazione.

Azure portal

1. Accedere al portale di Azure.

2. Assegnare questi ruoli:

   • Collaboratore al servizio di ricerca (operazioni create-read-update-delete su indici, indicizzatori, set di competenze e altri oggetti di primo livello)
   • Collaboratore ai dati dell'indice di ricerca (caricare documenti ed eseguire processi di indicizzazione)
   • Lettore di dati dell'indice di ricerca (eseguire query su un indice)

PowerShell

Quando si usa PowerShell per assegnare ruoli, chiamare New-AzRoleAssignment, specificando il nome dell’utente o del gruppo di Azure e l'ambito dell'assegnazione.

In questo esempio viene creata un'assegnazione di ruolo con ambito definito per un servizio di ricerca:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

In questo esempio viene creata un'assegnazione di ruolo con ambito definito per un indice specifico:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Assegnare ruoli per query di sola lettura

Usare il ruolo Lettore dati dell'indice di ricerca per app e processi che richiedono il solo accesso in lettura a un indice.

Ruolo	ID
Search Index Data Reader con PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

Questo è un ruolo molto specifico. Concede l'accesso GET o POST alla raccolta di documenti di un indice di ricerca per la ricerca, il completamento automatico e i suggerimenti. Non supporta operazioni GET o LIST su un indice o su altri oggetti di primo livello, né statistiche del servizio GET.

Questa sezione illustra i passaggi di base per configurare l’assegnazione di ruolo ed è qui per completezza ma è consigliabile Usare Azure AI Search senza chiavi per istruzioni complete sulla configurazione dell’app per l’accesso basato sui ruoli.

Azure portal

1. Accedere al portale di Azure.

2. Assegnare il ruolo Lettore dati indice di ricerca.

PowerShell

Quando si usa PowerShell per assegnare ruoli, chiamare New-AzRoleAssignment, specificando il nome dell’utente o del gruppo di Azure e l'ambito dell'assegnazione.

1. Ottenere l'ID sottoscrizione, il gruppo di risorse del servizio di ricerca e il nome del servizio di ricerca.

2. Ottenere l'identificatore dell'oggetto del servizio di Azure, ad esempio Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Ottenere la definizione del ruolo ed esaminare le autorizzazioni per assicurarsi che si tratta del ruolo desiderato.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Creare l'assegnazione di ruolo sostituendo valori validi ai segnaposto.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Di seguito è riportato un esempio di assegnazione di ruolo con ambito definito per un indice specifico:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

Testare le assegnazioni di ruolo

Usare un client per testare le assegnazioni di ruolo. Tenere presente che i ruoli sono cumulativi e che i ruoli ereditati con ambito a livello di sottoscrizione o gruppo di risorse non possono essere eliminati o negati a livello di risorsa (servizio di ricerca).

Configurare l’applicazione per le connessioni senza chiave e disporre di assegnazioni di ruolo prima del test.

Azure portal

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Nella pagina di panoramica selezionare la scheda Indici:

   • I collaboratori del servizio di ricerca possono visualizzare e creare qualsiasi oggetto, ma non caricare documenti o eseguire query su un indice. Per verificare le autorizzazioni, creare un indice di ricerca.

   • I collaboratori ai dati dell'indice di ricerca possono caricare documenti. Non è disponibile alcuna opzione per caricare i documenti nel portale al di fuori dell’Importazione guidata dati, ma è possibile reimpostare ed eseguire un indicizzatore per confermare le autorizzazioni per il caricamento dei documenti.

   • I lettori dati dell'indice di ricerca possono eseguire query sull'indice. Per verificare le autorizzazioni, usare Esplora ricerche. Dovrebbe essere possibile inviare query e visualizzare i risultati, ma non visualizzare la definizione dell'indice o crearne una.

REST API

Questo approccio presuppone Visual Studio Code con un'estensione client REST.

1. Aprire una shell dei comandi per l'interfaccia della riga di comando di Azure e accedere alla sottoscrizione di Azure.

   az login
   

2. Ottenere l'ID tenant e l'ID sottoscrizione. L'ID viene usato come variabile in un passaggio successivo.

   az account show
   

3. Ottenere un token di accesso.

   az account get-access-token --query accessToken --output tsv
   

4. Incollare queste variabili in un nuovo file di testo in Visual Studio Code.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Incollare e quindi inviare una richiesta che usa le variabili specificate. Per il ruolo "Lettore dati dell’indice di ricerca", è possibile inviare una query. È possibile usare qualsiasi versione dell'API supportata.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Per altre informazioni su come acquisire un token per un ambiente specifico, vedere Gestire un servizio di ricerca Azure AI con le API REST e Librerie di autenticazione di Microsoft Identity Platform.

.NET

1. Usare il pacchetto Azure.Search.Documents.

2. Usare Azure.Identity per .NET per l'autenticazione del token. Microsoft consiglia DefaultAzureCredential() per la maggior parte degli scenari.

3. Di seguito è riportato un esempio di connessione client tramite DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Ecco un altro esempio dell’uso delle credenziali del segreto client:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Usare azure.search.documents (SDK Azure per Python).

2. Usare Azure.Identity per Python per l'autenticazione del token.

3. Usare DefaultAzureCredential se il client Python è un'applicazione che viene eseguita lato server. Abilitare l’autenticazione interattiva se l'app viene eseguita in un browser.

4. Ecco un esempio:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Usare @azure/search-documents (SDK Azure per JavaScript), versione 11.3.

2. Usare Azure.Identity per JavaScript per l'autenticazione del token.

3. Se si usa React, usare InteractiveBrowserCredential per l'autenticazione Microsoft Entra per la ricerca. Per informazioni dettagliate, vedere Quando usare @azure/identity.

Java

1. Usare azure-search-documents (SDK Azure per Java).

2. Usare Azure.Identity per Java per l'autenticazione del token.

3. Microsoft consiglia DefaultAzureCredential per le app eseguite in Azure.

Testare come utente corrente

Se si è già un collaboratore o proprietario del servizio di ricerca, è possibile presentare un token di connessione per l'autenticazione dell’identità utente in Azure AI Search.

1. Ottenere un token di connessione per l'utente corrente usando l'interfaccia della riga di comando di Azure:

   az account get-access-token --scope https://search.azure.com/.default
   

   O usando PowerShell:

   Get-AzAccessToken -ResourceUrl https://search.azure.com
   

2. Incollare queste variabili in un nuovo file di testo in Visual Studio Code.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

3. Incollare e inviare una richiesta per confermare l'accesso. In questo esempio viene eseguita una query sull'indice hotels-quickstart

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Concedere l'accesso a un singolo indice

In alcuni scenari, è possibile limitare l'accesso di un'applicazione a una singola risorsa, ad esempio un indice.

Il portale attualmente non supporta le assegnazioni di ruolo a questo livello di granularità, ma può essere eseguito con PowerShell o con l'interfaccia della riga di comando di Azure.

In PowerShell usare New-AzRoleAssignment, specificando il nome dell'utente o del gruppo di Azure e l'ambito dell'assegnazione.

1. Caricare i moduli Azure e AzureAD e connettersi all'account Azure:

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

2. Aggiungere un'assegnazione di ruolo con ambito definito per un singolo indice:

   New-AzRoleAssignment -ObjectId <objectId> `
       -RoleDefinitionName "Search Index Data Contributor" `
       -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
   

Creare un ruolo personalizzato

Se i ruoli predefiniti non forniscono la corretta combinazione di autorizzazioni, è possibile creare un ruolo personalizzato per supportare le operazioni necessarie.

In questo esempio viene clonato Lettore dati dell'indice di ricerca e poi viene aggiunta la possibilità di elencare gli indici in base al nome. In genere, elencare gli indici in un servizio di ricerca è considerato un diritto amministrativo.

Azure portal

Questi passaggi sono derivati da Creare o aggiornare ruoli personalizzati di Azure con il portale di Azure. La clonazione di un ruolo esistente è supportata in una pagina del servizio di ricerca.

Questa procedura crea un ruolo personalizzato che aumenta i diritti di query di ricerca includendo la possibilità di elencare gli indici in base al nome. In genere, l'elenco degli indici è considerato una funzione da amministratore.

1. Nel portale di Azure passare al servizio di ricerca.

2. Nel pannello di navigazione a sinistra selezionare Controllo di accesso (IAM).

3. Nella barra delle azioni selezionare Ruoli.

4. Fare clic con il pulsante destro del mouse su Lettore dati dell’indice di ricercar (o su un altro ruolo) e selezionare Clona per aprire la procedura guidata Crea un ruolo personalizzato.

5. Nella scheda Informazioni di base specificare un nome per il ruolo personalizzato, ad esempio "Esplora dati dell'indice di ricerca", quindi selezionare Avanti.

6. Nella scheda Autorizzazioni selezionare Aggiungi autorizzazione.

7. Nella scheda Aggiungi autorizzazioni cercare e selezionare il riquadro Microsoft Search.

8. Impostare le autorizzazioni per il ruolo personalizzato. Nella parte superiore della pagina, usando la selezione predefinita Azioni:

   • In Microsoft.Search/operations selezionare Lettura: elencare tutte le operazioni disponibili.
   • In Microsoft.Search/searchServices/indexes selezionare Lettura: Lettura indice.

9. Nella stessa pagina passare a Azioni dati e in Microsoft.Search/searchServices/indexes/documents selezionare Lettura: Lettura documenti.

   La definizione JSON è simile all'esempio seguente:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. Selezionare Rivedi e crea per creare il ruolo. È ora possibile assegnare utenti e gruppi al ruolo.

Azure PowerShell

L'esempio di PowerShell mostra la sintassi JSON per la creazione di un ruolo personalizzato che è un clone di Lettore dati dell'indice di ricerca, ma con la possibilità di elencare tutti gli indici in base al nome.

1. Esaminare l'elenco delle autorizzazioni atomiche per determinare quelle necessarie. Per questo esempio, è necessario quanto segue:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Configurare una sessione di PowerShell per creare il ruolo personalizzato. Per istruzioni dettagliate, vedere Azure PowerShell

3. Specificare la definizione del ruolo come documento JSON. L'esempio seguente illustra la sintassi per la creazione di un ruolo personalizzato con PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Nota

Se l'ambito assegnabile è a livello di indice, l'azione sui dati deve essere "Microsoft.Search/searchServices/indexes/documents/read".

REST API

1. Esaminare l'elenco delle autorizzazioni atomiche per determinare quelle necessarie.

2. Per consultare la procedura, vedere Creare o aggiornare ruoli personalizzati di Azure con l'API REST.

3. Copiare o creare un ruolo oppure usare JSON per specificare il ruolo personalizzato (vedere la scheda PowerShell per la sintassi JSON).

Interfaccia della riga di comando di Azure

1. Esaminare l'elenco delle autorizzazioni atomiche per determinare quelle necessarie.

2. Per consultare la procedura, vedere Creare o aggiornare ruoli personalizzati di Azure con l'interfaccia della riga di comando di Azure.

3. Vedere la scheda PowerShell per la sintassi JSON.

Accesso condizionale

È consigliabile usare l'accesso condizionale Microsoft Entra se è necessario applicare criteri aziendali, ad esempio l'autenticazione a più fattori.

Per abilitare determinati criteri di accesso condizionale per Azure AI Search, seguire questa procedura:

1. Accedere al portale di Azure.

2. Cercare Accesso condizionale Microsoft Entra.

3. Selezionare Criteri.

4. Selezionare Nuovi criteri.

5. Nella sezione App o azioni cloud dei criteri aggiungere Azure AI Search come app cloud a seconda di come si vogliono configurare i criteri.

6. Aggiornare i parametri rimanenti dei criteri. Ad esempio, specificare a quali utenti e gruppi si applica questo criterio.

7. Salvare il criterio.

Importante

Se al servizio di ricerca è assegnata un'identità gestita, il servizio di ricerca specifico verrà visualizzato come app cloud che può essere inclusa o esclusa dai criteri di accesso condizionale. I criteri di accesso condizionale non possono essere applicati a un servizio di ricerca specifico. Assicurarsi invece di selezionare l'app cloud Azure AI Search generale.

Limiti

• Il controllo degli accessi in base al ruolo può aumentare la latenza di alcune richieste. Ogni combinazione univoca di risorsa del servizio (indice, indicizzatore e così via) ed entità servizio attiva un controllo di autorizzazione. Questi controlli di autorizzazione possono aggiungere fino a 200 millisecondi di latenza per richiesta.

• Nei rari casi in cui le richieste provengono da un numero elevato di entità servizio diverse, tutte destinate a risorse del servizio diverse (indici, indicizzatori e così via), è possibile che i controlli di autorizzazione comportino una limitazione delle richieste. La limitazione si verifica solo se vengono usate centinaia di combinazioni univoche di risorse del servizio di ricerca ed entità servizio nell’arco di un secondo.

Risoluzione dei problemi relativi al controllo di accesso basato sui ruoli

Quando si sviluppano applicazioni che usano il controllo degli accessi in base al ruolo per l'autenticazione, possono verificarsi alcuni problemi comuni:

• Se il token di autorizzazione proviene da un'identità gestita e le autorizzazioni appropriate sono state assegnate di recente, potrebbero essere necessarie diverse ore affinché queste assegnazioni delle autorizzazioni siano effettive.

• La configurazione predefinita per un servizio di ricerca è l’autenticazione basata su chiave. Se l'impostazione della chiave predefinita non è stata modificata in Entrambi o Controllo degli accessi in base al ruolo, tutte le richieste che usano l'autenticazione basata su ruoli vengono negate in automatico, indipendentemente dalle autorizzazioni sottostanti.