Guida introduttiva: Connettere un servizio di Foundry IQ (Azure AI Search)

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

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:

  1. Passare al servizio IQ Foundry nel portale di Azure.

  2. Nel riquadro sinistro selezionare Impostazioni > Chiavi.

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

    Screenshot delle opzioni di controllo di accesso nel portale di Azure.

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

  5. Seleziona Aggiungi>Aggiungi assegnazione ruolo.

    Screenshot del menu a discesa per l'aggiunta di un'assegnazione di ruolo nel portale di Azure.

  6. Assegna il ruolo Collaboratore servizio di ricerca al tuo account utente o identità gestita.

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

  1. Passare al servizio IQ Foundry nel portale di Azure.

  2. Nel riquadro sinistro selezionare Panoramica.

  3. Prendere nota dell'ID sottoscrizione e dell'endpoint.

    Screenshot dell'ID sottoscrizione e dell'endpoint nel portale Azure.

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:

  1. Nel sistema locale aprire uno strumento da riga di comando.

  2. Controllare la sottoscrizione attiva e il tenant nell'ambiente locale.

    az account show
    
  3. Se 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:

  1. Nel sistema locale aprire Visual Studio Code.

  2. Creare un file .ipynb.

  3. Creare una cella di codice per installare le azure-identity librerie e azure-search-documents .

    pip install azure-identity azure-search-documents
    
  4. Creare 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))
    
  5. Impostare service_endpoint sul valore ottenuto in Ottenere informazioni sul servizio.

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

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:

  1. Passare al servizio IQ Foundry nel portale di Azure.

  2. Nel riquadro sinistro selezionare Impostazioni > Chiavi.

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

    Screenshot delle opzioni di controllo di accesso nel portale di Azure.

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

  5. Seleziona Aggiungi>Aggiungi assegnazione ruolo.

    Screenshot del menu a discesa per l'aggiunta di un'assegnazione di ruolo nel portale di Azure.

  6. Assegna il ruolo Collaboratore servizio di ricerca al tuo account utente o identità gestita.

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

  1. Passare al servizio IQ Foundry nel portale di Azure.

  2. Nel riquadro sinistro selezionare Panoramica.

  3. Prendere nota dell'ID sottoscrizione e dell'endpoint.

    Schermata dell'ID della sottoscrizione e dell'endpoint nel portale di Azure.

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:

  1. Nel sistema locale aprire uno strumento da riga di comando.

  2. Controllare la sottoscrizione attiva e il tenant nell'ambiente locale.

    az account show
    
  3. Se 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:

  1. 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 tsv
    
  2. Prendere 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:

  1. Nel sistema locale aprire Visual Studio Code.

  2. Creare un file .rest o .http.

  3. 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}}
    
  4. Impostare @baseUrl sul valore ottenuto in Ottenere informazioni sul servizio.

  5. Impostare @token sul valore ottenuto in Ottieni token.

  6. In ### List existing indexesselezionare Invia richiesta.

    Si dovrebbe ricevere una HTTP/1.1 200 OK risposta, 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.