Configurare un servizio di ricerca per la connessione tramite un'identità gestita

Note

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

È possibile usare i principali di sicurezza di Microsoft Entra ID e le assegnazioni di ruolo per le connessioni in uscita da Azure AI Search ad altre risorse Azure che forniscono dati, intelligenza artificiale applicata o vettorizzazione durante l'indicizzazione o le query.

Per usare i ruoli in una connessione in uscita, configurare prima di tutto il servizio di ricerca per l'uso di un'identità gestita, sia essa assegnata dal sistema o dall'utente, come entità di sicurezza per il servizio di ricerca in un tenant Microsoft Entra. Dopo avere ottenuto un'identità gestita, è possibile assegnare ruoli per l'accesso autorizzato. Le identità gestite e le assegnazioni di ruolo eliminano la necessità di passare segreti e credenziali in un stringa di connessione o codice.

Prerequisiti

Un servizio Azure AI Search in qualsiasi area geografica per il livello Basic o superiore.
Una risorsa di Azure che accetta le richieste in ingresso da un'entità di sicurezza Microsoft Entra con un'assegnazione di ruolo valida.
Per creare un'identità gestita, è necessario essere proprietario o amministratore accesso utenti. Per assegnare ruoli, è necessario essere proprietario, amministratore accesso utenti, amministratore di controllo degli accessi in base al ruolo o membro di un ruolo personalizzato con autorizzazioni Microsoft.Authorization/roleAssignments/write.

Scenari supportati

È possibile usare le identità gestite per gli scenari seguenti.

Scenario	Assegnata dal sistema	Utente assegnato
Connettersi alle origini dati dell'indicizzatore¹	Sì	Sì
Connettersi ai modelli di incorporamento e completamento chat in Azure OpenAI, Microsoft Foundry e Funzioni di Azure tramite capacità/vettorizzatori ²	Sì	Sì
Connetti a Azure Key Vault per le chiavi gestite dal cliente	Sì	Sì
Connetti a sessioni di debug (ospitate in Archiviazione di Azure)¹	Sì	No
Connettersi a una cache di arricchimento, ospitata in Archiviazione di Azure (anteprima)^1,3	Sì	Sì ⁴
Connettersi a un Knowledge Store (ospitato in Archiviazione di Azure)¹	Sì	Sì

¹ Per la connettività tra la ricerca e l'archiviazione, la sicurezza di rete impone vincoli per il tipo di identità gestita che è possibile usare. È possibile usare solo un'identità gestita dal sistema per una connessione nella stessa area di Archiviazione di Azure e tale connessione deve essere tramite l'eccezione del trusted service o la regola dell'istanza di risorsa. Per informazioni dettagliate, vedere Accesso a un account di archiviazione protetto dalla rete .

² Connessioni ad Azure OpenAI, Fonderia e Funzioni di Azure tramite competenze/funzionalità di vettorializzazione includono: Competenza personalizzata, Funzionalità di vettorializzazione personalizzata, Competenza di incorporamento Azure OpenAI, Funzionalità di vettorializzazione di Azure OpenAI, Competenza AML e Funzionalità di vettorializzazione del catalogo dei modelli Microsoft Fonderia.

³ Il servizio di ricerca di intelligenza artificiale attualmente non è in grado di connettersi alle tabelle in un account di archiviazione con accesso con chiave condivisa disattivato.

⁴ L'identità gestita assegnata dall'utente per le connessioni alla cache di arricchimento richiede un'API REST di anteprima (2025-11-01-preview o successiva) o un pacchetto SDK di anteprima. Tutti gli altri scenari di identità gestita assegnati dall'utente in questa tabella sono supportati nell'API REST versione 2026-04-01 e successive.

Creare un'identità gestita dal sistema

Un'identità gestita assegnata dal sistema è un'entità di sicurezza Microsoft Entra ID creata e collegata automaticamente a una risorsa Azure, ad esempio un servizio Azure AI Search.

È possibile avere un'identità gestita assegnata dal sistema per ogni servizio di ricerca. È univoco per il servizio di ricerca e associato al servizio per l'intero ciclo di vita.

Quando si abilita un'identità gestita assegnata dal sistema, Microsoft Entra ID crea un'entità di sicurezza per il servizio di ricerca usato per l'autenticazione ad altre risorse Azure. È quindi possibile usare questa identità nelle assegnazioni di ruolo per l'accesso autorizzato ai dati e alle operazioni.

Passare al servizio di ricerca nel portale Azure.
Nel riquadro sinistro selezionare Impostazioni>Identità.
Nella scheda Assegnata dal sistema , in Stato, selezionare Sì.
Selezionare Salva.

Dopo aver salvato le impostazioni, la pagina viene aggiornata per visualizzare un identificatore di oggetto assegnato al servizio di ricerca.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Per altre informazioni, vedere Creare un servizio di ricerca con un'identità gestita assegnata dal sistema (Azure PowerShell.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Per altre informazioni, vedere Creare un servizio di ricerca con un'identità gestita assegnata dal sistema (interfaccia della riga di comando di Azure).

Usare Servizi - Creare o aggiornare (API REST) per formulare la richiesta.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

La risposta include una conferma e un identificatore di oggetto per l'identità gestita assegnata dal sistema.

Creare un'identità gestita assegnata dall'utente

Un'identità gestita assegnata dall'utente è una risorsa Azure con ambito sottoscrizioni, gruppi di risorse o tipi di risorse.

È possibile creare più identità gestite assegnate dall'utente per una maggiore granularità nelle assegnazioni di ruolo. Ad esempio, è possibile che si vogliano identità separate per applicazioni e scenari diversi. Come risorsa gestita e creata in modo indipendente, non è associata al servizio stesso.

I passaggi per configurare un'identità gestita assegnata dall'utente sono i seguenti:

Nella sottoscrizione Azure creare un'identità gestita assegnata dall'utente.
Nel servizio di ricerca associare l'identità gestita assegnata dall'utente al servizio di ricerca.
In altri servizi di Azure a cui ci si vuole connettere, creare un'assegnazione di ruolo per l'identità.

L'associazione di un'identità gestita assegnata dall'utente a un servizio di Azure AI Search è supportata nel portale di Azure, nelle API REST di gestione della ricerca e nei pacchetti SDK che forniscono la funzionalità.

Portale di Azure
REST API

Accedere al portale Azure.
Nell'angolo superiore sinistro del dashboard selezionare Crea una risorsa.
Usare la casella di ricerca per trovare l'identità gestita assegnata dall'utente e quindi selezionare Crea.
Selezionare la sottoscrizione, il gruppo di risorse e l'area. Assegnare all'identità un nome descrittivo.
Selezionare Crea e attendere il completamento della distribuzione della risorsa.

Prima di poter usare l'identità, sono necessari alcuni minuti.
Nella pagina del servizio di ricerca selezionare Impostazioni>Identità.
Nella scheda Assegnata dall'utente selezionare Aggiungi.
Selezionare la sottoscrizione e l'identità gestita assegnata dall'utente creata in precedenza.

Anziché il portale di Azure, è possibile usare le API REST di gestione della ricerca per assegnare un'identità gestita assegnata dall'utente.

Usare Services - Update (API REST) per formulare la richiesta.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[name of resource group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Impostare identity.type sul tipo di identità.
- I valori validi sono SystemAssigned, UserAssignedo SystemAssigned, UserAssigned per entrambi.
- Un valore None cancella le identità assegnate in precedenza dal servizio di ricerca.
Aggiornare identity.userAssignedIdentities per includere i dettagli dell'identità gestita assegnata dall'utente. Questa identità deve esistere già prima di poterla specificare nella richiesta.

Assegnare un ruolo

Dopo aver ottenuto un'identità gestita, assegnare ruoli che determinano le autorizzazioni del servizio di ricerca per la risorsa Azure.

Le autorizzazioni di lettura sono necessarie per le connessioni dati dell'indicizzatore e per l'accesso a una chiave gestita dal cliente in Azure Key Vault.
Le autorizzazioni di scrittura sono necessarie per le funzionalità di arricchimento tramite intelligenza artificiale che usano Archiviazione di Azure per ospitare i dati delle sessioni di debug, la memorizzazione nella cache di arricchimento e l'archiviazione di contenuti a lungo termine in un archivio conoscenze.

I passaggi seguenti illustrano il flusso di lavoro dell'assegnazione di ruolo. Questo esempio è per Azure OpenAI. Per altre risorse Azure, vedere Connect to Archiviazione di Azure, Connect to Azure Cosmos DB, or Connect to Azure SQL.

Passare alla risorsa Azure OpenAI nel portale Azure.
Selezionare Controllo di accesso dal menu a sinistra.
Selezionare Aggiungi e quindi Aggiungi assegnazione di ruolo.
In Ruoli della funzione lavorativa selezionare Servizi cognitivi OpenAI User e quindi selezionare Avanti.
In Membri selezionare Identità gestita e quindi selezionare Membri.
Filtrare in base alla sottoscrizione e al tipo di risorsa (servizi di ricerca) e quindi selezionare l'identità gestita del servizio di ricerca.
Selezionare Rivedi + assegna.

Esempi di stringa di connessione

Si ricordi dalla descrizione degli scenari che è possibile usare le identità gestite nelle stringhe di connessione ad altre risorse Azure. In questa sezione vengono forniti esempi.

Le connessioni di identità gestite assegnate dal sistema usano versioni dell'API REST disponibili a livello generale. Le connessioni identità gestite assegnate dall'utente usano l'API REST versione 2026-04-01 o successiva, ad eccezione delle connessioni alla cache di arricchimento, che richiedono comunque una versione dell'API di anteprima.

Suggerimento

È possibile creare la maggior parte di questi oggetti nel portale di Azure, specificando un'identità gestita assegnata dal sistema o dall'utente e quindi visualizzare la definizione JSON per ottenere il stringa di connessione.

Origine dati BLOB (identità gestita dal sistema):

Un'origine dati dell'indicizzatore include una credentials proprietà che determina la modalità di connessione all'origine dati. Nell'esempio seguente viene illustrato un stringa di connessione che specifica l'ID risorsa univoco di un account di archiviazione.

Un'identità gestita dal sistema è indicata quando un stringa di connessione è l'ID risorsa univoco di un servizio o di un'applicazione compatibile con Microsoft Entra ID. Un'identità gestita assegnata dall'utente viene specificata tramite una identity proprietà .

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Origine dati BLOB (identità gestita dall'utente):

Un'identità gestita assegnata dall'utente è supportata tramite la identity proprietà in SearchIndexerDataSource con l'API REST versione 2026-04-01 o successiva.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Archivio conoscenze (identità gestita dal sistema):

Una definizione dell'archivio conoscenze include una stringa di connessione a Archiviazione di Azure. La stringa di connessione è l'ID risorsa univoco dell'account di archiviazione. Si noti che la stringa non include contenitori o tabelle nel percorso. Questi vengono definiti nella definizione di proiezione incorporata, non nella stringa di connessione.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Archivio conoscenze (identità gestita dall'utente):

Un'identità gestita assegnata dall'utente è supportata tramite la identity proprietà in SearchIndexerKnowledgeStore con l'API REST versione 2026-04-01 o successiva.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};",
  "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }
}

Cache di arricchimento (anteprima):

Un indicizzatore crea, usa e memorizza il contenitore usato per gli arricchimenti memorizzati nella cache. Non è necessario includere il contenitore nella cache stringa di connessione. È possibile trovare l'ID oggetto nella pagina Identity del servizio di ricerca nel portale di Azure.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sessione di debug:

Una sessione di debug viene eseguita nel portale di Azure e accetta un stringa di connessione all'avvio della sessione. È possibile incollare una stringa simile all'esempio seguente.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Competenza personalizzata:

Una competenza personalizzata è destinata all'endpoint di una funzione Azure o di un'app che ospita codice personalizzato.

uri è l'endpoint della funzione o dell'app.
authResourceId indica al servizio di ricerca di connettersi usando un'identità gestita, passando l'ID applicazione della funzione o dell'app di destinazione nella proprietà.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Esempi di connessione per i modelli

Per le connessioni effettuate tramite identità gestite, in questa sezione vengono illustrati esempi di informazioni di connessione usate da un servizio di ricerca per connettersi a un modello in un'altra risorsa. Una connessione tramite un'identità gestita dal sistema è trasparente; l'identità e i ruoli sono presenti e la connessione ha esito positivo se sono configurate correttamente. Al contrario, un'identità gestita dall'utente richiede proprietà di connessione aggiuntive.

Competenza di incorporamento di Azure OpenAI e Funzionalità di vettorializzazione di Azure OpenAI:

Una funzionalità di incorporamento Azure OpenAI e un vettorizzatore in AI Search mirano all'endpoint di un Azure OpenAI che ospita un modello di incorporamento. L'endpoint viene specificato nella definizione dell'abilità di incorporamento Azure OpenAI e/o nella definizione del vettore Azure OpenAI.

L'identità gestita dal sistema viene usata automaticamente se "apikey" e "authIdentity" sono vuote, come illustrato nell'esempio seguente. La "authIdentity" proprietà viene usata solo per l'identità gestita assegnata dall'utente.

Esempio di identità gestita dal sistema:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Ecco un esempio di vettorizzatore configurato per un'identità gestita assegnata dal sistema. Un vettorizzatore è specificato in un indice di ricerca.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

Esempio di identità gestita assegnata dall'utente:

Viene usata un'identità gestita assegnata dall'utente se "apiKey" è vuota e viene fornito un valore valido "authIdentity" .

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

Ecco un esempio di vettorizzatore configurato per un'identità gestita assegnata dall'utente. Un vettorizzatore è specificato in un indice di ricerca.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Verificare l'accesso al firewall

Se la risorsa Azure si trova dietro un firewall, assicurarsi che sia presente una regola in ingresso che ammette le richieste dal servizio di ricerca e dal portale di Azure.

Per connessioni nella stessa area ad Archiviazione BLOB di Azure o a Azure Data Lake Storage Gen2, usare un'identità gestita dal sistema e l'eccezione del servizio attendibile. Facoltativamente, è possibile configurare una regola di istanza della risorsa per ammettere le richieste.
Per tutte le altre risorse e connessioni, configurare una regola del firewall IP che ammette le richieste provenienti da Azure AI Search. Per informazioni dettagliate, vedere Accesso dell'indexer al contenuto protetto dalle funzionalità di sicurezza di rete di Azure.

Vedere anche

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-07-03