Guida introduttiva: Connettersi senza chiavi

Articolo
12/20/2024

Configurare Ricerca intelligenza artificiale di Azure per l'uso dell'autenticazione e del controllo degli accessi in base al ruolo (RBAC) di Microsoft Entra ID in modo che sia possibile connettersi dal sistema locale senza chiavi API, usando notebook jupyter o un client REST per interagire con il servizio di ricerca.

Se sono state illustrate altre guide introduttive che si connettono usando le chiavi API, questa guida introduttiva illustra come passare all'autenticazione basata su identità in modo da evitare chiavi hardcoded nel codice di esempio.

Prerequisiti

Una sottoscrizione di Azure. Crearne una gratuitamente.
Ricerca di intelligenza artificiale di Azure, qualsiasi area o livello, ma è necessario Basic o versione successiva per configurare un'identità gestita per Ricerca di intelligenza artificiale di Azure.
Uno strumento da riga di comando, ad esempio PowerShell o Bash, e l'interfaccia della riga di comando di Azure.

Passaggio 1: Ottenere la sottoscrizione di Azure e gli ID tenant

Questo passaggio è necessario se sono presenti più sottoscrizioni o tenant.

Ottenere la sottoscrizione e il tenant di Azure per il servizio di ricerca:
1. Accedere al portale di Azure e passare al servizio di ricerca.
2. Si noti il nome e l'ID della sottoscrizione in Overview>Essentials.
3. Selezionare ora il nome della sottoscrizione per visualizzare il gruppo di gestione padre (ID tenant) nella pagina successiva.
Ora si conosce la sottoscrizione e il tenant in Cui si trova Ricerca di intelligenza artificiale di Azure. Passare al dispositivo locale e al prompt dei comandi e identificare la sottoscrizione e il tenant di Azure attivi nel dispositivo:
```
az account show
```
Se la sottoscrizione attiva e il tenant differiscono dalle informazioni ottenute nel passaggio precedente, modificare l'ID sottoscrizione. Accedere quindi ad Azure usando l'ID tenant trovato nel passaggio precedente:
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

Passaggio 2: Configurare Ricerca di intelligenza artificiale di Azure per il controllo degli accessi in base al ruolo

Accedere al portale di Azure e passare al servizio di ricerca di intelligenza artificiale di Azure.
Abilitare il controllo degli accessi in base al ruolo:
1. Passare a Impostazioni>Chiavi.
2. Scegliere Controllo basato su ruoli o Entrambi se è necessario passare i client al controllo degli accessi in base al ruolo.
  
  Se si sceglie Controllo basato su ruoli, assicurarsi di assegnare a se stessi tutti i ruoli denominati nell'istruzione successiva oppure non sarà possibile completare le attività nel portale di Azure o tramite un client locale.
Assegnare ruoli nel portale di Azure:
1. Passare al servizio di ricerca.
2. Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.
3. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.
4. Scegliere un ruolo (Collaboratore servizio di ricerca, Collaboratore indice di ricerca, Lettore dati indice di ricerca) e assegnarlo all'identità dell'utente o del gruppo Microsoft Entra.
  
  Ripetere per ogni ruolo.
  
  Per creare, caricare ed eseguire query sugli oggetti in Ricerca di intelligenza artificiale di Azure, è necessario disporre di Collaboratore ai servizi di ricerca e Collaboratore ai dati dell'indice di ricerca. Per altre informazioni, vedere Connettersi usando i ruoli.

Suggerimento

In seguito, se si verificano errori di autenticazione, controllare di nuovo le impostazioni in questa sezione. Potrebbero essere presenti criteri a livello di sottoscrizione o gruppo di risorse che eseguono l'override di tutte le impostazioni API specificate.

Passaggio 3: Connettersi dal sistema locale

Se non è ancora stato eseguito l'accesso ad Azure:

az login

Uso di Notebook Python e Jupyter

Installare le librerie di Azure Identity e Ricerca di Azure:
```
pip install azure-identity azure-search-documents
```

Eseguire l'autenticazione e connettersi a Ricerca intelligenza artificiale di Azure:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

Uso di un client REST

Diverse guide introduttive e esercitazioni usano un client REST, ad esempio Visual Studio Code con l'estensione REST. Ecco come connettersi a Ricerca intelligenza artificiale di Azure da Visual Studio Code.

È necessario avere un .rest file o .http , simile a quello descritto in Guida introduttiva: Ricerca vettoriale.

Genera un token di accesso.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Nella parte superiore del file impostare le variabili usate per la connessione, incollando l'endpoint completo del servizio di ricerca e il token di accesso ottenuto nel passaggio precedente. Le variabili dovrebbero essere simili all'esempio seguente. Si noti che i valori non sono racchiusi tra virgolette.
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

Specificare il token di connessione dell'autorizzazione in una chiamata REST:

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

Risolvere gli errori 401

Controllare la sottoscrizione attiva e il tenant (az account show) e assicurarsi che sia valido per il servizio di ricerca.
Controllare le opzioni delle chiavi delle impostazioni>del servizio di ricerca nella portale di Azure e verificare che il servizio sia configurato per il controllo degli accessi in base al ruolo o per il controllo degli accessi in base al ruolo.
Solo per il client REST: controllare il token e l'endpoint specificati nel file e assicurarsi che non ci siano virgolette circostanti o spazi aggiuntivi.

Se tutto il resto ha esito negativo, riavviare il dispositivo per rimuovere tutti i token memorizzati nella cache e quindi ripetere i passaggi descritti in questa sezione, a partire da az login.

Configurazione aggiuntiva

Configurare un'identità gestita per le connessioni in uscita:

Configurare un'identità gestita assegnata dal sistema o assegnata dall'utente per il servizio di ricerca.
Usare le assegnazioni di ruolo per autorizzare l'accesso ad altre risorse di Azure.

Configurazione dell'accesso alla rete:

Impostare le regole in ingresso per accettare o rifiutare le richieste a Ricerca di intelligenza artificiale di Azure in base all'indirizzo IP.

Condividi tramite