Connettersi a Azure Cosmos DB usando un'identità gestita (Azure AI Search)

Nota

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.

Questo articolo illustra come configurare una connessione dell'indicizzatore a un database Azure Cosmos DB usando un'identità gestita anziché fornire le credenziali nel stringa di connessione".

È possibile usare un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente. Le identità gestite di Microsoft Entra sono login e richiedono assegnazioni di ruolo di Azure per accedere ai dati in Azure Cosmos DB. Facoltativamente, è possibile applicare l'accesso basato su ruoli come unico metodo di autenticazione per le connessioni ai dati impostando disableLocalAuth su true per l'account Azure Cosmos DB per NoSQL.

Prerequisiti

Limitazioni

  • Gli indicizzatori che si connettono a Azure Cosmos DB per Gremlin e MongoDB (attualmente in anteprima) supportano solo l'approccio legacy.

Approcci supportati per l'autenticazione dell'identità gestita

Azure AI Search supporta due meccanismi per connettersi alle Azure Cosmos DB usando l'identità gestita.

  • L'approccio legacy richiede la configurazione dell'identità gestita per avere le autorizzazioni di lettura per il piano di controllo dell'account Azure Cosmos DB di destinazione. Azure AI Search usa tale identità per recuperare le chiavi dell'account Cosmos DB in background per accedere ai dati. Questo approccio non funzionerà se l'account Cosmos DB ha "disableLocalAuth": true.

  • L'approccio moderno richiede la configurazione dei ruoli appropriati per l'identità gestita nel controllo e nel piano dati dell'account Azure Cosmos DB di destinazione. Azure AI Search richiederà quindi un token di accesso per accedere ai dati nell'account Cosmos DB. Questo approccio funziona anche se l'account Cosmos DB ha "disableLocalAuth": true.

Gli indicizzatori che si connettono ad Azure Cosmos DB per NoSQL supportano sia l'approccio legacy che l'approccio moderno; l'approccio moderno è consigliato.

Connettersi a Azure Cosmos DB per NoSQL

Questa sezione descrive i passaggi per configurare la connessione a Azure Cosmos DB per NoSQL tramite l'approccio modern.

Configurare le assegnazioni di ruolo del piano di controllo

  1. Accedere al portale di Azure e trovare l'account Cosmos DB per NoSQL.

  2. Selezionare Controllo di accesso (IAM).

  3. Selezionare Aggiungi e quindi selezionare Assegnazione di ruolo.

  4. Nell'elenco dei ruoli delle funzioni di processo selezionare Lettore account Cosmos DB.

  5. Selezionare Avanti.

  6. Selezionare Identità gestita e quindi Membri.

  7. Filtrare in base alle identità gestite assegnate dal sistema o alle identità gestite assegnate dall'utente. Verrà visualizzata l'identità gestita creata in precedenza per il servizio di ricerca. Se non ne hai una, vedi Configurare la ricerca per l'uso di un'identità gestita. Se l'hai già configurato ma non è disponibile, attendi alcuni minuti.

  8. Selezionare l'identità e salvare l'assegnazione di ruolo.

Per altre informazioni, vedere Usare il controllo degli accessi in base al ruolo del piano di controllo con Azure Cosmos DB per NoSQL.

Configurare le assegnazioni di ruolo del piano dati

L'identità gestita dev'essere assegnata a un ruolo per poter leggere dal piano dati dell'account Cosmos DB. L'ID oggetto (entità) per l'identità assegnata dal sistema o dall'utente del servizio di ricerca è reperibile nella scheda "Identità" del servizio di ricerca. Questo passaggio può essere eseguito solo tramite interfaccia della riga di comando di Azure al momento.

Impostare variabili:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --query id --output tsv)

Definire un'assegnazione di ruolo per l'identità assegnata dal sistema:

az cosmosdb sql role assignment create --account-name $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope

Per altre informazioni, vedere Usare il controllo degli accessi in base al ruolo del piano dati con Azure Cosmos DB per NoSQL

Configurare la definizione dell'origine dati

Dopo aver configurato entrambe le assegnazioni di ruolo del piano di controllo e del piano dati nell'account di Azure Cosmos DB per NoSQL, è possibile creare una connessione a esso che opera con il ruolo assegnato.

Gli indicizzatori usano un oggetto origine dati per le connessioni a un'origine dati esterna. Questa sezione illustra come specificare un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente nella stringa di connessione dell'origine dati. Ulteriori esempi di stringhe di connessione sono disponibili nell'articolo sull'identità gestita.

Suggerimento

È possibile creare una connessione all'origine dati a Cosmos DB nel portale di Azure, specificando un'identità gestita assegnata dal sistema o dall'utente e quindi visualizzare la definizione JSON per vedere come viene formulata la stringa di connessione.

L'API REST, Azure portal e l'SDK .NET SDK supportano l'uso di un'identità gestita assegnata dal sistema o assegnata dall'utente.

Connettersi tramite l'identità assegnata dal sistema

Quando ci si connette con un'identità gestita assegnata dal sistema, l'unica modifica alla definizione dell'origine dati è il formato della proprietà "credentials". Specificare un nome di database e un ResourceId senza chiave dell'account o password. ResourceId deve includere l'ID sottoscrizione di Azure Cosmos DB, il gruppo di risorse e il nome dell'account Azure Cosmos DB.

Ecco un esempio che usa l'API REST Crea origine dati per sperimentare l'approccio moderno.

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Nota

Se la proprietà IdentityAuthType non fa parte della stringa di connessione, Azure AI Search utilizza l'approccio legacy per impostazione predefinita per garantire la compatibilità con le versioni precedenti.

Connettersi tramite l'identità assegnata dall'utente

È necessario aggiungere una proprietà "identity" alla definizione dell'origine dati, in cui si specifica l'identità specifica (tra quelle che possono essere assegnate al servizio di ricerca), che verrà usata per connettersi all'account Azure Cosmos DB.

Ecco un esempio di uso dell'identità assegnata dall'utente tramite l'approccio moderno .

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Connettersi a Azure Cosmos DB per Gremlin/MongoDB (anteprima)

Questa sezione descrive i passaggi per configurare la connessione a Azure Cosmos DB per Gremlin/Mongo tramite l'approccio legacy.

Configurare le assegnazioni di ruolo del piano di controllo

Seguire la stessa procedura descritta in precedenza per assegnare i ruoli appropriati nel piano di controllo del Azure Cosmos DB per Gremlin/MongoDB.

Impostare la stringa di connessione

  • Per le raccolte MongoDB, aggiungere "ApiKind=MongoDb" al stringa di connessione e usare un'API REST di anteprima.
  • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" al stringa di connessione e usare un'API REST di anteprima.
  • Per entrambi i tipi, è supportato solo l'approccio legacy, vale a dire che IdentityAuthType=AccountKey o ometterlo interamente costituiscono gli unici formati validi per la stringa di connessione.

Ecco un esempio per connettersi alle raccolte MongoDB usando l'identità assegnata dal sistema tramite l'API REST

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Ecco un esempio per connettersi ai grafici Gremlin usando l'identità assegnata dall'utente.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Eseguire l'indicizzatore per verificare le autorizzazioni

Le informazioni di connessione e le autorizzazioni per il servizio remoto vengono convalidate in fase di esecuzione durante l'esecuzione dell'indicizzatore. Se l'indicizzatore ha esito positivo, la sintassi di connessione e le assegnazioni di ruolo sono valide. Per altre informazioni, vedere Eseguire o reimpostare indicizzatori, competenze o documenti.

Risolvere i problemi relativi alle connessioni

  • Per Azure Cosmos DB per NoSQL, verificare se l'account ha accesso limitato alle reti selezionate. È possibile escludere eventuali problemi del firewall provando la connessione senza restrizioni. Per maggiori informazioni, vedere Accesso dell'indicizzatore al contenuto protetto dalla sicurezza di rete di Azure.

  • Per Azure Cosmos DB per NoSQL, se l'indicizzatore non riesce a causa di problemi di autenticazione, assicurarsi che le assegnazioni di ruolo siano state eseguite both sul piano di controllo e sul piano dati dell'account Cosmos DB.

  • Per Gremlin o MongoDB, se di recente hai ruotato le chiavi dell'account Azure Cosmos DB, è necessario attendere fino a 15 minuti affinché la stringa di connessione dell'identità gestita funzioni.

Vedere anche

  • Ultimo aggiornamento: