Condividi tramite

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

  • Articolo

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

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

Prerequisiti

Approcci supportati per l'autenticazione dell'identità gestita

Ricerca di intelligenza artificiale di Azure supporta due meccanismi per connettersi ad 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. Ricerca di intelligenza artificiale di Azure 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. Ricerca di intelligenza artificiale di Azure 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 quello moderno . L'approccio moderno è altamente consigliato.

Limiti

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

Connettersi ad Azure Cosmos DB for NoSQL

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

Configurare le assegnazioni di ruolo del piano di controllo

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

  2. Seleziona Controllo di accesso (IAM).

  3. Selezionare Aggiungi e quindi selezionare Assegnazione di ruolo.

  4. Nell'elenco dei ruoli della funzione di processo selezionare Lettore account Cosmos DB.

  5. Selezionare Avanti.

  6. Selezionare Identità gestita e selezionare 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 è disponibile, vedere Configurare la ricerca per l'uso di un'identità gestita. Se ne è già stato configurata una ma non è disponibile, attendere qualche minuto.

  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 deve assegnare un ruolo per la lettura 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 l'interfaccia della riga di comando di Azure al momento.

Impostare le 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-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

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

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_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 sia il piano di controllo che le assegnazioni di ruolo del piano dati nell'account Azure Cosmos DB per NoSQL, è possibile configurare una connessione che opera con tale ruolo.

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 in una stringa di connessione dell'origine dati. Altre esempi di stringhe di connessione sono disponibili nell'articolo sull'identità gestita.

Suggerimento

È possibile creare una connessione all'origine dati a Cosmos DB nella 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, portale di Azure e .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 o password dell'account. 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 che esercita l'approccio moderno .

POST https://[service name].search.windows.net/datasources?api-version=2024-11-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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Nota

Se la IdentityAuthType proprietà non fa parte del stringa di connessione, Ricerca di intelligenza artificiale di Azure usa per impostazione predefinita l'approccio legacy 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 (da più assegnabili 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=2024-11-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];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 ad Azure Cosmos DB per Gremlin/MongoDB (anteprima)

Questa sezione descrive i passaggi per configurare la connessione ad 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 di Azure Cosmos DB per Gremlin/MongoDB.

Impostare la stringa di connessione

  • Per le raccolte MongoDB, aggiungere "ApiKind=MongoDb" alla stringa di connessione e usare un'anteprima dell’API REST.
  • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" alla stringa di connessione e usare un'anteprima dell’API REST.
  • Per entrambi i tipi, è supportato solo l'approccio legacy, IdentityAuthType=AccountKey ovvero o omettendolo interamente è l'unico stringa di connessione valido.

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=2024-11-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=2024-11-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 delle 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 altre 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 sia sul piano di controllo che sul piano dati dell'account Cosmos DB.

  • Per Gremlin o MongoDB, se di recente sono state ruotate le chiavi dell'account Azure Cosmos DB, è necessario attendere fino a 15 minuti per il funzionamento della stringa di connessione dell'identità gestita.

Vedi anche