Connettersi a Azure AI Search usando i ruoli

1. Passare al servizio di ricerca nel portale Azure.

2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.

   

4. Selezionare un ruolo: Proprietario, Collaboratore o Lettore.

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

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

Quando si assegnano ruoli utilizzando PowerShell, quindi chiamare New-AzRoleAssignment, specificando il nome utente o il gruppo 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>"

Riferimento:New-AzRoleAssignment

1. Passare al servizio di ricerca nel portale Azure.

2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.

   

4. Selezionare Collaboratore servizio di ricerca.

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

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

7. Ripeti questi passaggi per assegnare Search Index Data Contributor e Search Index Data Reader.

Quando si assegnano ruoli utilizzando PowerShell, chiamare New-AzRoleAssignment, specificando il nome utente o il gruppo 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>"

Riferimento:New-AzRoleAssignment

1. Passare al servizio di ricerca nel portale Azure.

2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.

   

4. Selezionare il ruolo Lettore dati indice di ricerca .

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

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

Quando si assegnano ruoli utilizzando PowerShell, utilizzare New-AzRoleAssignment, fornendo il nome utente o il gruppo 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 Azure, ad esempio Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <your-azure-openai-resource-name>
   

   L'output include una proprietà Id che contiene l'ID oggetto necessario per l'assegnazione di ruolo.

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>
   

   Un'assegnazione con esito positivo restituisce i dettagli dell'assegnazione di ruolo, incluso RoleAssignmentId.

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>
   

   Riferimento:New-AzRoleAssignment

1. Passare al servizio di ricerca nel portale Azure.

2. Nel riquadro sinistro selezionareIndici> per testare le autorizzazioni correlate all'indice:

   • I collaboratori del servizio di ricerca possono creare, modificare ed eliminare oggetti di ricerca, ma non possono caricare documenti o eseguire query. Per verificare le autorizzazioni, creare un indice di ricerca.

   • I collaboratori ai dati dell'indice di ricerca possono caricare documenti. Nel portale di Azure non esiste un'opzione per caricare i documenti tranne la procedura guidata Importa dati, ma è possibile reimpostare ed eseguire un indicizzatore per confermare le autorizzazioni al caricamento dei documenti.

   • I lettori di dati dell'indice di ricerca possono eseguire query sugli indici. Per verificare le autorizzazioni, usare Esplora ricerche. Dovrebbe essere possibile inviare query e visualizzare i risultati, ma non è consigliabile visualizzare le definizioni di indice o creare indici.

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

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

   az login
   

2. Ottenere l'ID tenant e l'ID sottoscrizione. Usare l'ID come variabile in un passaggio futuro.

   az account show
   

3. Ottenere un token di accesso per il piano dati Azure AI Search.

   az account get-access-token --scope https://search.azure.com/.default --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. Inviare una richiesta che usi le variabili specificate. Per il ruolo Lettore dati dell'indice di ricerca, è possibile inviare una query usando qualsiasi versione dell'API supportata.

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

   Informazioni di riferimento:Cerca documenti

   Una query con esito positivo restituisce i risultati della ricerca con documenti corrispondenti. Se l'indice è vuoto o non ha corrispondenze, value contiene una matrice vuota.

   Suggerimento

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

1. Installare i pacchetti necessari:

   dotnet add package Azure.Search.Documents
   dotnet add package Azure.Identity
   

2. Usare Azure. Identità 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 con DefaultAzureCredential():

   // Create a SearchIndexClient to send create/delete index commands
   // Requires Search Service Contributor role
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   // Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

   Reference:SearchClient, SearchIndexClient, 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);
   

5. Ecco un esempio di esecuzione di una query:

   SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
   foreach (SearchResult<SearchDocument> result in response.GetResults())
   {
       Console.WriteLine(result.Document["HotelName"]);
   }
   

   Una query con esito positivo restituisce i risultati della ricerca. Se nessun documento corrisponde, la raccolta dei risultati è vuota.

1. Installare i pacchetti necessari:

   pip install azure-search-documents azure-identity
   

2. Usare Azure. Identità per Python per l'autenticazione del token.

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

4. Ad 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)
   

   Reference:SearchClient, DefaultAzureCredential

1. Installare i pacchetti necessari:

   npm install @azure/search-documents @azure/identity
   

2. Usare Azure. Identità per JavaScript per l'autenticazione del token.

3. Se usi React, usa InteractiveBrowserCredential per l'autenticazione di Microsoft Entra a Azure AI Search. Per altre informazioni, vedere Quando usare @azure/identity.

   Reference:SearchClient, DefaultAzureCredential

1. Aggiungi le dipendenze necessarie a pom.xml:

   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-search-documents</artifactId>
     <version>11.7.4</version>
   </dependency>
   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-identity</artifactId>
     <version>1.15.0</version>
   </dependency>
   

2. Usare Azure. Identità per Java per l'autenticazione del token.

3. Usare DefaultAzureCredential per le app eseguite in Azure.

1. Accedere al portale di Azure e passare al servizio di ricerca.

2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

3. Nella scheda Ruoli, trova Lettore dati indice di ricerca o un altro ruolo, seleziona i tre puntini (...), quindi seleziona Clona.

4. Nella scheda Basics immettere un nome per il ruolo personalizzato, ad esempio "Cerca indice Esplora dati", quindi selezionare Next.

5. Nella scheda Autorizzazioni selezionare Aggiungi autorizzazioni.

6. Nel riquadro Aggiungi autorizzazioni selezionare il riquadro Microsoft Search.

7. Con Actions selezionata nella parte superiore, impostare le autorizzazioni seguenti:

   • In Microsoft.Search/operations selezionare Read : Elenca tutte le operazioni disponibili.
   • In Microsoft.Search/searchServices/indexes selezionare Read : Read Index.

8. Passare a Data Actions nella parte superiore e in Microsoft.Search/searchServices/indexes/documents selezionare Read : Read Documents.

   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": []
            }
        ]
      }
    }
   

9. Selezionare Aggiungi per chiudere il riquadro.

10. Selezionare Rivedi e crea per creare il ruolo.

    È ora possibile assegnare utenti e gruppi al ruolo. Per altre informazioni su questi passaggi, vedere Creare o aggiornare Azure ruoli personalizzati usando il portale di Azure.

L'esempio di PowerShell mostra la sintassi JSON per la creazione di un ruolo personalizzato che è un clone del lettore di 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 sono necessarie le autorizzazioni seguenti:

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

   Note

   Se si assegna l'ambito a livello di indice, utilizzare l'azione sui dati "Microsoft.Search/searchServices/indexes/documents/read".

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

2. Per la procedura, vedere Creare o aggiornare Azure ruoli personalizzati usando 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).

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

2. Per la procedura, vedere Creare o aggiornare Azure ruoli personalizzati usando interfaccia della riga di comando di Azure.

3. Vedere la scheda PowerShell per la sintassi JSON.