Configurare la connettività in ingresso privata

Importante

Questa serie di esercitazioni usa l'API REST 2026-08-01-preview per il recupero agentico. L'anteprima 2026-08-01-preview viene concessa in licenza all'utente come parte della sottoscrizione di Azure ed è soggetta alle condizioni applicabili alle "Anteprime" nei Microsoft Product Terms, nel Microsoft Products and Services Data Protection Addendum ("DPA") e nelle Condizioni d'uso supplementari per le anteprime di Microsoft Azure.

Questo articolo fa parte di una serie di esercitazioni in tre parti. In questa parte dell'esercitazione è stata configurata la connettività privata in ingresso da Microsoft Foundry a Azure AI Search. Stabilendo questo percorso di richiesta privata, assicurarsi che il recupero successivo e la convalida delle dipendenze si verifichino all'interno del limite di rete previsto.

Prerequisites

  • Una sottoscrizione di Azure per la quale l'account dispone di accesso Contributor o Owner nell'ambito della sottoscrizione o del gruppo di risorse usato per questa esercitazione.

  • I provider di risorse seguenti registrati nella sottoscrizione:

    • Microsoft.CognitiveServices
    • Microsoft.MachineLearningServices
    • Microsoft.App
    • Microsoft.ContainerService
    • Microsoft.ContainerRegistry
    • Microsoft.Network
    • Microsoft.Search
    • Microsoft.Storage
    • Microsoft.DocumentDB

  • L'interfaccia della riga di comando di Azure deve essere installata e autenticata con az login.

  • Un client all’interno della rete virtuale (VNet), ad esempio un jumpbox, una macchina virtuale, una dev box o una workstation connessa tramite Azure Bastion, connesso al percorso di rete privato usato nella distribuzione e in grado di raggiungere gli endpoint privati. Nella terza parte si usa questo stesso client per eseguire chiamate REST del piano dati su endpoint privati.

Creare una rete privata

Creare i limiti della rete virtuale che trasportano traffico privato tra Foundry e Azure AI Search. Questa sezione definisce le subnet per il runtime, gli endpoint privati e i client di test facoltativi nella rete virtuale.

Per creare la rete privata:

  1. Creare il gruppo di risorse e la rete virtuale.

    az group create \
  --name rg-private-retrieval \
  --location westus3

az network vnet create \
  --resource-group rg-private-retrieval \
  --name vnet-private-retrieval \
  --location westus3 \
  --address-prefixes 10.42.0.0/16

  2. Creare due subnet: agent-subnet per il runtime dell'agente e pe-subnet per gli endpoint privati.

    Importante

    La distribuzione richiede che agent-subnet sia dedicato a questo ambiente. Se la subnet è già usata da un altro ambiente o servizio, la distribuzione può non riuscire. Usa una nuova VNet o un nuovo intervallo di subnet non ancora utilizzato per ogni distribuzione isolata del tutorial.

    # Agent runtime subnet
az network vnet subnet create \
  --resource-group rg-private-retrieval \
  --vnet-name vnet-private-retrieval \
  --name agent-subnet \
  --address-prefixes 10.42.0.0/24

# Private endpoint subnet
az network vnet subnet create \
  --resource-group rg-private-retrieval \
  --vnet-name vnet-private-retrieval \
  --name pe-subnet \
  --address-prefixes 10.42.1.0/24

  3. (Facoltativo) Creare una subnet nella rete virtuale denominata mcp-subnet se è necessario inserire carichi di lavoro all'interno della rete virtuale, ad esempio jumpbox, macchine virtuali di convalida o host MCP. Se non ti servono componenti nella VNet, salta questo passaggio.

    # In-VNet test subnet
az network vnet subnet create \
  --resource-group rg-private-retrieval \
  --vnet-name vnet-private-retrieval \
  --name mcp-subnet \
  --address-prefixes 10.42.2.0/24

Distribuire un'infrastruttura privata

Una volta configurata la rete, utilizza l'artefatto di distribuzione foundry-samples per creare l'infrastruttura privata (servizi privati, endpoint privati e zone DNS private) per questa serie di tutorial.

Per distribuire l'infrastruttura privata:

  1. Ottieni l'ID della sottoscrizione da usare come <subscription-id> in tutta la serie di tutorial.

    az account show --query id -o tsv

  2. Imposta l'URL del modello di distribuzione e l'ID della risorsa VNet esistente usato per la distribuzione.

    templateUri='https://raw.githubusercontent.com/microsoft-foundry/foundry-samples/main/infrastructure/infrastructure-setup-bicep/15-private-network-standard-agent-setup/azuredeploy.json'
vnetId='/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Network/virtualNetworks/vnet-private-retrieval'

  3. Convalidare la configurazione della distribuzione.

    az deployment group validate \
  --resource-group rg-private-retrieval \
  --template-uri "$templateUri" \
  --parameters \
    location='westus3' \
    aiServices='private-retrieval' \
    firstProjectName='project-private-retrieval' \
    displayName='private foundry project' \
    projectDescription='Private Foundry plus private Azure AI Search' \
    vnetName='vnet-private-retrieval' \
    existingVnetResourceId="$vnetId" \
    agentSubnetName='agent-subnet' \
    peSubnetName='pe-subnet' \
    agentSubnetPrefix='10.42.0.0/24' \
    peSubnetPrefix='10.42.1.0/24'

    Se la sottoscrizione impone un criterio che richiede ad Azure AI Search di disabilitare l'autenticazione locale, la distribuzione di questo esempio può essere rifiutata durante la convalida o la distribuzione. In tal caso, creare un servizio di Azure AI Search conforme e riutilizzarlo fornendo il parametro di modello facoltativoaiSearchResourceId.

    Un servizio di ricerca bring-your-own compatibile per questa esercitazione deve soddisfare i seguenti requisiti prima di passare l'ID della relativa risorsa al modello:

    • Un'area e uno SKU supportati per il recupero agentico.
    • Identità gestita assegnata dal sistema.
    • Accesso basato sui ruoli abilitato sul piano dati.
    • L'autenticazione locale è disabilitata se richiesto dai criteri.
    • L'accesso alla rete pubblica è disabilitato se richiesto dai criteri.

    Per esempio:

    az search service create \
  --name <search-service-name> \
  --resource-group rg-private-retrieval \
  --location westus3 \
  --sku standard \
  --identity-type SystemAssigned \
  --disable-local-auth true \
  --public-access disabled

  4. Distribuire i servizi privati, gli endpoint e le zone DNS.

    La distribuzione richiede in genere da 10 a 20 minuti e il comando non viene restituito fino al completamento.

    az deployment group create \
  --name dg-private-retrieval \
  --resource-group rg-private-retrieval \
  --template-uri "$templateUri" \
  --parameters \
    location='westus3' \
    aiServices='private-retrieval' \
    firstProjectName='project-private-retrieval' \
    displayName='private foundry project' \
    projectDescription='Private Foundry plus private Azure AI Search' \
    vnetName='vnet-private-retrieval' \
    existingVnetResourceId="$vnetId" \
    agentSubnetName='agent-subnet' \
    peSubnetName='pe-subnet' \
    agentSubnetPrefix='10.42.0.0/24' \
    peSubnetPrefix='10.42.1.0/24'

    Se si riutilizza un servizio di Azure AI Search esistente per soddisfare i criteri di sottoscrizione, aggiungere aiSearchResourceId='<search-resource-id>' ai parametri di distribuzione.

  5. Verificare che la distribuzione ha creato le risorse seguenti:

    • Risorsa e progetto di fonderia
    • Servizio Ricerca intelligenza artificiale di Azure
    • Account di archiviazione di Azure
    • Account di Azure Cosmos DB
    • Registro Azure Container che supporta l'ambiente dell'agente standard
    • Endpoint privati per le risorse distribuite
    • DNS privato zone con collegamenti di rete virtuale richiesti dalla distribuzione
    az deployment group show \
  --resource-group rg-private-retrieval \
  --name dg-private-retrieval \
  --query properties.provisioningState \
  -o tsv

    Il comando deve restituire Succeeded. Il numero esatto di endpoint privati e zone DNS può cambiare man mano che la distribuzione di esempio si evolve; usare pertanto l'output della distribuzione come fonte autorevole.

  6. Registrare i nomi delle risorse generate.

    La distribuzione aggiunge un suffisso univoco a risorse univoche globali per evitare conflitti di denominazione, in modo che i nomi distribuiti differiscano dai nomi di input. Registrare ora i nomi effettivi. In questa serie di esercitazioni, sostituirli con i segnaposto <foundry-resource-name>, <search-service-name>, <storage-account-name>e <cosmos-account-name>.

    # Foundry resource name
az cognitiveservices account list \
  --resource-group rg-private-retrieval \
  --query "[?kind=='AIServices'].name | [0]" \
  -o tsv

# Azure AI Search service name
az search service list \
  --resource-group rg-private-retrieval \
  --query "[0].name" \
  -o tsv

# Azure Storage account name
az storage account list \
  --resource-group rg-private-retrieval \
  --query "[0].name" \
  -o tsv

# Azure Cosmos DB account name
az cosmosdb list \
  --resource-group rg-private-retrieval \
  --query "[0].name" \
  -o tsv

Verificare l'infrastruttura privata

La connettività privata in ingresso dipende da tre controlli che interagiscono: impostazioni di esposizione di rete, stato degli allegati dell'endpoint privato e percorsi di risoluzione DNS privati. In questa sezione viene convalidato ogni controllo in modo da poter considerare attendibili le richieste vincolate alle route di rete private.

Per verificare l'infrastruttura privata:

  1. Verificare che l'accesso pubblico sia disabilitato per tutti e quattro i servizi.

    # Foundry resource
az cognitiveservices account show \
  --name <foundry-resource-name> \
  --resource-group rg-private-retrieval \
  --query 'properties.publicNetworkAccess'

# Azure AI Search
az search service show \
  --name <search-service-name> \
  --resource-group rg-private-retrieval \
  --query 'publicNetworkAccess'

# Azure Storage
az storage account show \
  --name <storage-account-name> \
  --resource-group rg-private-retrieval \
  --query 'publicNetworkAccess'

# Azure Cosmos DB
az cosmosdb show \
  --name <cosmos-account-name> \
  --resource-group rg-private-retrieval \
  --query 'publicNetworkAccess'

    Ogni servizio deve restituire Disabled.

  2. Verificare che le connessioni dell'endpoint privato siano approvate per i quattro servizi principali.

    # Foundry resource
az network private-endpoint-connection list \
  --id /subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name> \
  --query "[].{name:name,status:properties.privateLinkServiceConnectionState.status}" \
  -o table

# Azure AI Search
az network private-endpoint-connection list \
  --id /subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Search/searchServices/<search-service-name> \
  --query "[].{name:name,status:properties.privateLinkServiceConnectionState.status}" \
  -o table

# Azure Storage
az network private-endpoint-connection list \
  --id /subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Storage/storageAccounts/<storage-account-name> \
  --query "[].{name:name,status:properties.privateLinkServiceConnectionState.status}" \
  -o table

# Azure Cosmos DB
az network private-endpoint-connection list \
  --id /subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.DocumentDB/databaseAccounts/<cosmos-account-name> \
  --query "[].{name:name,status:properties.privateLinkServiceConnectionState.status}" \
  -o table

    Ogni connessione a un endpoint privato deve mostrare lo stato Approved.

  3. Verificare che le zone DNS private necessarie esistano e siano collegate alla rete virtuale.

    az network private-dns link vnet list \
  --resource-group rg-private-retrieval \
  --zone-name privatelink.cognitiveservices.azure.com \
  --query "[].name" \
  -o table

az network private-dns link vnet list \
  --resource-group rg-private-retrieval \
  --zone-name privatelink.openai.azure.com \
  --query "[].name" \
  -o table

az network private-dns link vnet list \
  --resource-group rg-private-retrieval \
  --zone-name privatelink.services.ai.azure.com \
  --query "[].name" \
  -o table

az network private-dns link vnet list \
  --resource-group rg-private-retrieval \
  --zone-name privatelink.search.windows.net \
  --query "[].name" \
  -o table

az network private-dns link vnet list \
  --resource-group rg-private-retrieval \
  --zone-name privatelink.blob.core.windows.net \
  --query "[].name" \
  -o table

az network private-dns link vnet list \
  --resource-group rg-private-retrieval \
  --zone-name privatelink.documents.azure.com \
  --query "[].name" \
  -o table

    Ogni comando deve restituire un collegamento di rete virtuale, che conferma che la zona DNS privata è collegata alla rete virtuale.

Convalidare la connettività privata

Con la rete configurata, convalidare la raggiungibilità confermando la risoluzione DNS privata e la connettività TCP 443. È necessario eseguire questi controlli dall'interno della rete virtuale, ad esempio da una macchina virtuale con connessione Azure Bastion, jumpbox, dev box o da un altro percorso di accesso privato.

Se non si dispone ancora di un client nella rete virtuale, crearne uno in (Facoltativo) Aggiungere un jumpbox Linux e Azure Bastion o (facoltativo) Aggiungere una macchina virtuale Windows e Azure Bastion e quindi tornare a questa sezione.

Per convalidare la connettività privata:

  1. Verificare che la risoluzione DNS restituisca indirizzi IP privati.

    getent hosts <search-service-name>.search.windows.net
getent hosts <foundry-resource-name>.services.ai.azure.com
getent hosts <foundry-resource-name>.openai.azure.com
getent hosts <storage-account-name>.blob.core.windows.net

    Questi endpoint devono risolversi in indirizzi IP privati nell'intervallo 10.x.x.x.

  2. Verificare la connettività TCP 443 agli endpoint usati nelle parti successive dell'esercitazione.

    timeout 10 bash -c '</dev/tcp/<search-service-name>.search.windows.net/443' && \
  echo 'Azure AI Search: OK' || echo 'Azure AI Search: FAILED'

timeout 10 bash -c '</dev/tcp/<foundry-resource-name>.services.ai.azure.com/443' && \
  echo 'Foundry: OK' || echo 'Foundry: FAILED'

timeout 10 bash -c '</dev/tcp/<foundry-resource-name>.openai.azure.com/443' && \
  echo 'Foundry OpenAI endpoint: OK' || echo 'Foundry OpenAI endpoint: FAILED'

timeout 10 bash -c '</dev/tcp/<storage-account-name>.blob.core.windows.net/443' && \
  echo 'Azure Blob Storage: OK' || echo 'Azure Blob Storage: FAILED'

    Ogni endpoint deve restituire OK.

(Facoltativo) Aggiungere un jumpbox Linux e Azure Bastion

Se è necessario un client riusabile nella VNet per la verifica tramite CLI e REST tramite endpoint privati, eseguire il provisioning di una jumpbox Linux protetta da Azure Bastion.

Per configurare questa configurazione:

  1. Assicurarsi che mcp-subnet esista. Se non è ancora stata creata questa subnet, completare il passaggio facoltativo mcp-subnet in Creare la rete privata.

  2. Creare l'interfaccia di rete e la macchina virtuale Linux.

    az network nic create \
  --resource-group rg-private-retrieval \
  --name vm-linux-nic \
  --vnet-name vnet-private-retrieval \
  --subnet mcp-subnet

az vm create \
  --resource-group rg-private-retrieval \
  --name vm-linux \
  --computer-name vm-linux \
  --nics vm-linux-nic \
  --image Ubuntu2204 \
  --authentication-type password \
  --admin-username azureuser \
  --admin-password <admin-password> \
  --size Standard_B2s \
  --storage-sku Premium_LRS

  3. Creare la subnet Azure Bastion e l'indirizzo IP pubblico.

    az network vnet subnet create \
  --resource-group rg-private-retrieval \
  --vnet-name vnet-private-retrieval \
  --name AzureBastionSubnet \
  --address-prefixes 10.42.3.0/26

az network public-ip create \
  --resource-group rg-private-retrieval \
  --name bastion-pip \
  --sku Standard \
  --allocation-method Static

  4. Distribuire Azure Bastion.

    az network bastion create \
  --resource-group rg-private-retrieval \
  --name bastion-private-retrieval \
  --public-ip-address bastion-pip \
  --vnet-name vnet-private-retrieval

Dopo aver configurato il jumpbox Linux e Azure Bastion:

  1. Connettersi alla macchina virtuale tramite Azure Bastion usando una sessione interattiva della shell.

  2. Nella macchina virtuale Linux, esegui i controlli della risoluzione DNS e della connettività TCP sulla porta 443 da Convalidare la connettività privata per confermare che il percorso in ingresso funzioni.

  3. Usare az vm run-command invoke per la convalida ripetibile e non interattiva quando si automatizzano i flussi di lavoro di test.

  4. Salvare i dettagli della connessione della macchina virtuale se si prevede di convalidare i comandi dall'interno della rete virtuale nelle parti successive dell'esercitazione.

(Facoltativo) Aggiungere una macchina virtuale Windows e Azure Bastion

Se si desidera testare il portale Foundry basato su browser o il playground dell'agente tramite il percorso privato, eseguire il provisioning di una VM Windows dietro Azure Bastion.

Per configurare questa configurazione:

  1. Assicurarsi che mcp-subnet esista. Se non è ancora stata creata questa subnet, completare il passaggio facoltativo mcp-subnet in Creare la rete privata.

  2. Creare l'interfaccia di rete e la VM Windows.

    az network nic create \
  --resource-group rg-private-retrieval \
  --name vm-windows-nic \
  --vnet-name vnet-private-retrieval \
  --subnet mcp-subnet

az vm create \
  --resource-group rg-private-retrieval \
  --name vm-windows \
  --computer-name vm-windows \
  --nics vm-windows-nic \
  --image MicrosoftWindowsServer:WindowsServer:2022-datacenter-azure-edition:latest \
  --authentication-type password \
  --admin-username azureuser \
  --admin-password <admin-password> \
  --size Standard_B2s \
  --public-ip-address "" \
  --storage-sku Premium_LRS

  3. Creare la subnet Azure Bastion e l'indirizzo IP pubblico.

    az network vnet subnet create \
  --resource-group rg-private-retrieval \
  --vnet-name vnet-private-retrieval \
  --name AzureBastionSubnet \
  --address-prefixes 10.42.3.0/26

az network public-ip create \
  --resource-group rg-private-retrieval \
  --name bastion-pip \
  --sku Standard \
  --allocation-method Static

  4. Distribuire Azure Bastion.

    az network bastion create \
  --resource-group rg-private-retrieval \
  --name bastion-private-retrieval \
  --public-ip-address bastion-pip \
  --vnet-name vnet-private-retrieval

Dopo aver configurato la macchina virtuale Windows e Azure Bastion:

  1. Aprire Azure Bastion nel portale di Azure e connettersi alla macchina virtuale Windows usando il nome utente e la password impostati durante la creazione della macchina virtuale.

  2. Dall'interno della macchina virtuale avviare Edge o Chrome e verificare che sia possibile accedere al portale Foundry tramite il percorso di rete privato. Ciò conferma la connettività del browser tramite l'endpoint privato in ingresso.

  3. Salvare i dettagli della connessione della macchina virtuale se si prevede di convalidare i comandi dall'interno della rete virtuale nelle parti successive dell'esercitazione.

Tip

Per gli accessi ad Azure Bastion tramite nome utente e password, usare password complesse per evitare errori durante le operazioni di copia e incolla.

Risoluzione dei problemi

Quando il percorso privato di ingresso tra Foundry e Azure AI Search non si comporta come previsto, inizia verificando la risoluzione DNS, l'approvazione del private endpoint e la raggiungibilità sulla porta TCP 443 da un client all'interno della VNet.

Controllo o sintomo Problema probabile Operazioni da eseguire successivamente
403 Forbidden La richiesta non raggiunge Azure AI Search sul percorso privato previsto. Convalidare il percorso privato dal client a Azure AI Search controllando la risoluzione DNS, la connettività TCP 443 e l'approvazione dell'endpoint privato. Un servizio di ricerca con restrizioni può restituire 403 Forbidden quando la richiesta non arriva su un percorso di rete consentito.
Timeout della connessione Il client non si trova sul percorso privato oppure gli endpoint privati non sono raggiungibili. Dalla macchina virtuale di test eseguire i controlli DNS e TCP da Convalidare la connettività privata per verificare che sia possibile raggiungere i servizi tramite il percorso privato.

Learn more

Per altre informazioni sugli argomenti trattati in questa parte dell'esercitazione, vedere gli articoli seguenti:

Passo successivo

Configurare la connettività in uscita privata

  • Last updated on