Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Annotazioni
Foundry IQ (Azure AI Search) fornisce API dirette di indicizzazione e query, oltre ad API di livello superiore per origini dati di conoscenza e knowledge base per il recupero gestito. Usare il portale di Azure, le API REST o Azure SDK per configurare queste funzionalità o connettere gli agenti alle knowledge base nel portale di Microsoft Foundry.
In questa guida introduttiva si usa il controllo degli accessi in base al ruolo e Microsoft Entra ID per stabilire una connessione senza chiave al servizio IQ Foundry (Azure AI Search). Si usa quindi Python in Visual Studio Code per interagire con il servizio.
Le connessioni senza chiave offrono una sicurezza avanzata tramite autorizzazioni granulari e autenticazione basata sull'identità. Non consigliamo di usare chiavi API codificate, ma, se preferisci, consulta Connettersi a Foundry IQ usando chiavi.
Prerequisiti
Un account Azure con una sottoscrizione attiva. Creare gratuitamente un account.
Servizio IQ foundry in qualsiasi area o livello.
Interfaccia della riga di comando di Azure per l'autenticazione senza chiave con MICROSOFT Entra ID.
Visual Studio Code con l'estensione Python e il pacchetto Jupyter.
Configurare l'accesso in base al ruolo
In questa sezione si abilita il controllo degli accessi in base al ruolo nel servizio IQ foundry (Azure AI Search) e si assegnano i ruoli necessari per la creazione, il caricamento e l'esecuzione di query sugli oggetti di ricerca. Per altre informazioni su questi passaggi, vedere Connettersi a Foundry IQ usando i ruoli.
Per configurare l'accesso:
Passare al servizio IQ Foundry nel portale di Azure.
Nel riquadro sinistro selezionare Impostazioni > Chiavi.
Selezionare Controllo degli accessi in base al ruolo o Entrambi se hai bisogno di tempo per effettuare la transizione dei client a RBAC (controllo degli accessi in base al ruolo).
Nel riquadro sinistro selezionare Controllo di accesso (IAM).
Seleziona Aggiungi>Aggiungi assegnazione ruolo.
Assegna il ruolo Collaboratore servizio di ricerca al tuo account utente o identità gestita.
Ripeti l'assegnazione del ruolo per Collaboratore Dati di Indice di Ricerca.
Ottenere informazioni sul servizio
In questa sezione vengono recuperati l'ID sottoscrizione e l'endpoint del servizio Foundry IQ. Se si ha una sola sottoscrizione, ignorare l'ID della sottoscrizione e recuperare soltanto l'endpoint. Questi valori vengono usati nelle sezioni rimanenti di questa guida introduttiva.
Per ottenere le informazioni sul servizio:
Passare al servizio IQ Foundry nel portale di Azure.
Nel riquadro sinistro selezionare Panoramica.
Prendere nota dell'ID sottoscrizione e dell'endpoint.
Accedere ad Azure
Prima di connettersi al servizio Foundry IQ, usare interfaccia della riga di comando di Azure per accedere alla sottoscrizione che contiene il servizio. Questo passaggio stabilisce l'identità di Microsoft Entra, che DefaultAzureCredential usa per autenticare le richieste nella sezione successiva.
Per accedere:
Nel sistema locale aprire uno strumento da riga di comando.
Controllare la sottoscrizione attiva e il tenant nell'ambiente locale.
az account showSe la sottoscrizione attiva e il tenant non sono validi per il servizio IQ Foundry, eseguire i comandi seguenti per aggiornare i valori. È possibile trovare l'ID sottoscrizione nella pagina Panoramica del servizio Foundry IQ nel portale di Azure. Per trovare l'ID tenant, selezionare il nome della sottoscrizione nella pagina Panoramica e quindi individuare il valore del Gruppo di gestione principale.
az account set --subscription <your-subscription-id> az login --tenant <your-tenant-id>
Connettersi a Foundry IQ
Annotazioni
Questa sezione illustra il modello Python di base per le connessioni senza chiave. Per indicazioni complete, vedere una guida introduttiva o un'esercitazione specifica, ad esempio Avvio rapido: Recupero agentico.
È possibile usare i notebook Python in Visual Studio Code per inviare richieste al servizio Foundry IQ. Per richiedere l'autenticazione, usare la DefaultAzureCredential classe dalla libreria di identità di Azure.
Per connettersi con Python:
Nel sistema locale aprire Visual Studio Code.
Creare un file
.ipynb.Creare una cella di codice per installare le
azure-identitylibrerie eazure-search-documents.pip install azure-identity azure-search-documentsCreare un'altra cella di codice per autenticare e connettersi al servizio Foundry IQ.
import json from azure.identity import DefaultAzureCredential from azure.search.documents.indexes import SearchIndexClient service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE" credential = DefaultAzureCredential() client = SearchIndexClient(endpoint = service_endpoint, credential = credential) # List existing indexes indexes = client.list_indexes() for index in indexes: index_dict = index.as_dict() print(json.dumps(index_dict, indent = 2))Impostare
service_endpointsul valore ottenuto in Ottenere informazioni sul servizio.Selezionare Esegui tutto per eseguire entrambe le celle di codice.
L'output dovrebbe elencare gli indici esistenti (se presenti) nel servizio Foundry IQ, a indicare una connessione riuscita.
Risolvere i problemi relativi agli errori 401
Se si verifica un errore 401, seguire questa procedura di risoluzione dei problemi:
Rivedere Configurare l'accesso in base al ruolo. Il servizio IQ Foundry deve avere il controllo degli accessi in base al ruolo o Entrambi abilitato. Le politiche a livello di sottoscrizione o di gruppo di risorse potrebbero prevalere sulle assegnazioni di ruolo.
Riaccedi ad Accedi ad Azure. È necessario accedere alla sottoscrizione che contiene il servizio Foundry IQ.
Verifica che la variabile endpoint abbia virgolette intorno.
Se tutto il resto ha esito negativo, riavviare il dispositivo per rimuovere i token memorizzati nella cache e ripetere i passaggi descritti in questa guida introduttiva, a partire da Accedi ad Azure.
In questa guida introduttiva si usa il controllo degli accessi in base al ruolo e Microsoft Entra ID per stabilire una connessione senza chiave al servizio IQ Foundry (Azure AI Search). Usare quindi REST in Visual Studio Code per interagire con il servizio.
Le connessioni senza chiave offrono una sicurezza avanzata tramite autorizzazioni granulari e autenticazione basata sull'identità. Non consigliamo le chiavi API codificate nel codice, ma, se le preferisci, consulta Connettersi a Foundry IQ tramite chiavi.
Prerequisiti
Un account Azure con una sottoscrizione attiva. Creare gratuitamente un account.
Un servizio Foundry IQ in qualsiasi area o livello.
Interfaccia della riga di comando di Azure per l'autenticazione senza chiave con MICROSOFT Entra ID.
Configurare l'accesso in base al ruolo
In questa sezione si abilita il controllo degli accessi in base al ruolo nel servizio IQ foundry (Azure AI Search) e si assegnano i ruoli necessari per la creazione, il caricamento e l'esecuzione di query sugli oggetti di ricerca. Per altre informazioni su questi passaggi, vedere Connettersi a Foundry IQ usando i ruoli.
Per configurare l'accesso:
Passare al servizio IQ Foundry nel portale di Azure.
Nel riquadro sinistro selezionare Impostazioni > Chiavi.
Selezionare Controllo degli accessi in base al ruolo o Entrambi se hai bisogno di tempo per effettuare la transizione dei client a RBAC (controllo degli accessi in base al ruolo).
Nel riquadro sinistro selezionare Controllo di accesso (IAM).
Seleziona Aggiungi>Aggiungi assegnazione ruolo.
Assegna il ruolo Collaboratore servizio di ricerca al tuo account utente o identità gestita.
Ripeti l'assegnazione del ruolo per Collaboratore Dati di Indice di Ricerca.
Ottenere informazioni sul servizio
In questa sezione vengono recuperati l'ID sottoscrizione e l'endpoint del servizio IQ Foundry. Se si ha una sola sottoscrizione, ignorare l'ID della sottoscrizione e recuperare soltanto l'endpoint. Questi valori vengono usati nelle sezioni rimanenti di questa guida introduttiva.
Per ottenere le informazioni sul servizio:
Passare al servizio IQ Foundry nel portale di Azure.
Nel riquadro sinistro selezionare Panoramica.
Prendere nota dell'ID sottoscrizione e dell'endpoint.
Accedere ad Azure
Prima di connettersi al servizio Foundry IQ, usare interfaccia della riga di comando di Azure per accedere alla sottoscrizione che contiene il servizio.
Per accedere:
Nel sistema locale aprire uno strumento da riga di comando.
Controllare la sottoscrizione attiva e il tenant nell'ambiente locale.
az account showSe la sottoscrizione attiva e il tenant non sono validi per il servizio IQ Foundry, eseguire i comandi seguenti per aggiornare i valori. È possibile trovare l'ID sottoscrizione nella pagina Panoramica del servizio Foundry IQ nel portale di Azure. Per trovare l'ID tenant, selezionare il nome della sottoscrizione nella pagina Panoramica e quindi individuare il valore del Gruppo di gestione principale.
az account set --subscription <your-subscription-id> az login --tenant <your-tenant-id>
Ottenere un token
Le chiamate API REST richiedono l'inclusione di un token ID Microsoft Entra. Questo token viene usato per autenticare le richieste nella sezione successiva.
Per ottenere il token:
Usando lo stesso strumento da riga di comando, generare un token di accesso.
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsvPrendere nota dell'output del token.
Connettersi a Foundry IQ
Annotazioni
In questa sezione viene illustrato il modello REST di base per le connessioni senza chiave. Per indicazioni complete, vedere una guida introduttiva o un'esercitazione specifica, ad esempio Avvio rapido: Recupero agentico.
È possibile usare l'estensione client REST in Visual Studio Code per inviare richieste al servizio IQ Foundry. Per l'autenticazione della richiesta, includere un'intestazione Authorization con il token ID Microsoft Entra generato in precedenza.
Per connettersi tramite REST:
Nel sistema locale aprire Visual Studio Code.
Creare un file
.resto.http.Incollare le variabili e la richiesta seguenti nel file.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE ### List existing indexes GET {{baseUrl}}/indexes?api-version=2026-10-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}Impostare
@baseUrlsul valore ottenuto in Ottenere informazioni sul servizio.Impostare
@tokensul valore ottenuto in Ottieni token.In
### List existing indexesselezionare Invia richiesta.Si dovrebbe ricevere una
HTTP/1.1 200 OKrisposta, che indica una connessione riuscita al servizio Foundry IQ.
Risolvere i problemi relativi agli errori 401
Se si verifica un errore 401, seguire questa procedura di risoluzione dei problemi:
Rivedere Configurare l'accesso in base al ruolo. Il servizio IQ Foundry deve avere il controllo degli accessi in base al ruolo o Entrambi abilitato. Le politiche a livello di sottoscrizione o di gruppo di risorse potrebbero prevalere sulle assegnazioni di ruolo.
Riaccedi ad Accedi ad Azure. È necessario accedere alla sottoscrizione che contiene il servizio Foundry IQ.
Assicurarsi che le variabili endpoint e token non abbiano virgolette o spazi aggiuntivi.
Assicurarsi che il token non abbia il
@simbolo nell'intestazione della richiesta. Ad esempio, se la variabile è@token, il riferimento nella richiesta deve essere{{token}}.Se tutto il resto ha esito negativo, riavviare il dispositivo per rimuovere i token memorizzati nella cache e ripetere i passaggi descritti in questa guida introduttiva, a partire da Accedi ad Azure.