Connettersi a Azure AI Search usando i ruoli

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

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

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

5. Selezionare un ruolo valido:

   • 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)

6. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra.

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

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

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

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

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

   

5. Selezionare un ruolo:

   • 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)

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

6. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra.

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

8. Ripetere l’operazione per gli altri ruoli. La maggior parte degli sviluppatori ha bisogno di tutti e tre.

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

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

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

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

5. Selezionare il ruolo Lettore dati dell’indice di ricerca.

6. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio, è possibile usare un'identità gestita dal sistema o dall'utente. Scegliere questa opzione se l'assegnazione di ruolo è per un'identità del servizio.

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

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
   

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.

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.

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);
   

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)
   

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.

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.

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.

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

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

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.