Verbinding maken met Azure Cosmos DB met behulp van een beheerde identiteit (Azure AI Zoeken)

In dit artikel wordt uitgelegd hoe u een indexeerfunctieverbinding met een Azure Cosmos DB-database instelt met behulp van een beheerde identiteit in plaats van referenties op te geven in de verbindingsreeks.'

U kunt een door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit gebruiken. Beheerde identiteiten zijn Microsoft Entra aanmeldingen en vereisen Azure roltoewijzingen voor toegang tot gegevens in Azure Cosmos DB. U kunt eventueel rolgebaseerde toegang afdwingen als de enige verificatiemethode voor gegevensverbindingen door disableLocalAuth in te stellen op true voor uw Azure Cosmos DB-account voor NoSQL.

Voorwaarden

• Maak een beheerde identiteit voor uw zoekservice.

Beperkingen

• Indexeerfuncties die verbinding maken met Azure Cosmos DB voor Gremlin en MongoDB (momenteel in preview) ondersteunen alleen de benadering legacy.

Ondersteunde benaderingen voor verificatie van beheerde identiteiten

Azure AI Zoeken ondersteunt twee mechanismen om verbinding te maken met Azure Cosmos DB met behulp van een beheerde identiteit.

• Voor de legacy benadering is het nodig om de beheerde identiteit zo te configureren dat deze leesmachtigingen heeft op het besturingsvlak van het Azure Cosmos DB-doelaccount. Azure AI Zoeken gebruikt die identiteit om de accountsleutels van het Cosmos DB-account op de achtergrond op te halen voor toegang tot de gegevens. Deze benadering werkt niet als het Cosmos DB-account "disableLocalAuth": true heeft.

• Voor de benadering modern moet u de juiste rollen voor de beheerde identiteit configureren op het besturings- en gegevensvlak van het doelaccount Azure Cosmos DB. Azure AI Zoeken vraagt vervolgens een toegangstoken aan om toegang te krijgen tot de gegevens in het Cosmos DB-account. Deze methode werkt zelfs als het Cosmos DB-account "disableLocalAuth": true heeft.

Indexeerfuncties die verbinding maken met Azure Cosmos DB voor NoSQL ondersteunen zowel de methode legacy als de modern- de modern benadering wordt aanbevolen.

Verbinding maken met Azure Cosmos DB voor NoSQL

In deze sectie worden de stappen beschreven voor het configureren van verbinding met Azure Cosmos DB voor NoSQL via de methode modern.

Roltoewijzingen van het besturingsvlak configureren

1. Meld u aan bij Azure portal en zoek uw Cosmos DB voor NoSQL account.

2. Selecteer Toegangsbeheer (IAM).

3. Selecteer Toevoegen en selecteer vervolgens Roltoewijzing.

4. Selecteer Cosmos DB-accountlezer in de lijst met functierollen.

5. Selecteer Volgende.

6. Selecteer Beheerde identiteit en selecteer vervolgens Leden.

7. Filter op door het systeem toegewezen beheerde identiteiten of door de gebruiker toegewezen beheerde identiteiten. U ziet nu de beheerde identiteit die u eerder hebt gemaakt voor uw zoekservice. Als u er nog geen hebt, raadpleegt u Zoeken configureren om een beheerde identiteit te gebruiken. Als u er al een hebt ingesteld maar het is niet beschikbaar, geef het een paar minuten.

8. Selecteer de identiteit en sla de roltoewijzing op.

Zie Op rollen gebaseerd toegangsbeheer op basis van besturingsvlak gebruiken met Azure Cosmos DB voor NoSQL voor meer informatie.

Roltoewijzingen voor gegevensvlak configureren

Aan de beheerde identiteit moet een rol zijn toegewezen om te lezen uit het gegevensvlak van het Cosmos DB-account. De object-id (principal) voor de door het systeem/de gebruiker toegewezen identiteit van de zoekservice vindt u op het tabblad Identiteit van de zoekservice. Deze stap kan momenteel alleen worden uitgevoerd via Azure CLI.

Variabelen instellen:

$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)

Definieer een roltoewijzing voor de door het systeem toegewezen identiteit:

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

Zie voor meer informatie Toegangsbeheer op basis van gegevensvlak gebruiken met Azure Cosmos DB voor NoSQL

De definitie van de gegevensbron configureren

Zodra u both roltoewijzingen voor besturingsvlak en gegevensvlak hebt geconfigureerd op de Azure Cosmos DB voor NoSQL account, kunt u een verbinding instellen die onder die rol werkt.

Indexeerfuncties gebruiken een gegevensbronobject voor verbindingen met een externe gegevensbron. In deze sectie wordt uitgelegd hoe u een door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit opgeeft op de verbindingsreeks van een gegevensbron. Meer verbindingsreeks voorbeelden vindt u in het artikel over beheerde identiteiten.

De REST-API, Azure portal en de .NET SDK ondersteuning met behulp van een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit.

Verbinding maken via door het systeem toegewezen identiteit

Wanneer u verbinding maakt met een door het systeem toegewezen beheerde identiteit, is de enige wijziging in de definitie van de gegevensbron de indeling van de eigenschap Referenties. Geef een databasenaam en een ResourceId op die geen accountsleutel of wachtwoord heeft. De ResourceId moet de abonnements-id van Azure Cosmos DB, de resourcegroep en de naam van het Azure Cosmos DB-account bevatten.

Hier volgt een voorbeeld met behulp van de REST API voor gegevensbron maken waarmee de moderne benadering wordt uitgevoerd.

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]" }
}

Verbinding maken via door de gebruiker toegewezen identiteit

U moet een eigenschap 'identiteit' toevoegen aan de definitie van de gegevensbron, waarbij u de specifieke identiteit opgeeft (uit verschillende identiteiten die kunnen worden toegewezen aan de zoekservice), die wordt gebruikt om verbinding te maken met het Azure Cosmos DB-account.

Hier volgt een voorbeeld van het gebruik van door de gebruiker toegewezen identiteit via de moderne benadering.

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]" 
    }
}

Verbinding maken met Azure Cosmos DB voor Gremlin/MongoDB (preview)

In deze sectie worden de stappen beschreven voor het configureren van verbinding met Azure Cosmos DB voor Gremlin/Mongo via de methode legacy.

Roltoewijzingen van het besturingsvlak configureren

Volg dezelfde stappen als voorheen om de juiste rollen toe te wijzen op het besturingsvlak van de Azure Cosmos DB voor Gremlin/MongoDB.

De verbindingsreeks instellen

• Voor MongoDB-verzamelingen voegt u ApiKind=MongoDb toe aan de verbindingsreeks en gebruikt u een preview-REST API.
• Voor Gremlin-grafieken voegt u ApiKind=Gremlin toe aan de verbindingsreeks en gebruikt u een preview-REST API.
• Voor beide soorten wordt alleen de benadering legacy ondersteund. Dat wil gezegd, IdentityAuthType=AccountKey of het volledig weglaten ervan is de enige geldige verbindingsreeks.

Hier volgt een voorbeeld om verbinding te maken met MongoDB-verzamelingen met behulp van door het systeem toegewezen identiteit via de REST API

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
}

Hier volgt een voorbeeld om verbinding te maken met Gremlin-grafieken met behulp van door de gebruiker toegewezen identiteit.

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]" 
    }
}

Voer de indexeerfunctie uit om machtigingen te verifiëren

Verbindingsgegevens en machtigingen voor de externe service worden tijdens runtime gevalideerd tijdens de uitvoering van de indexeerfunctie. Als de indexeerfunctie is geslaagd, zijn de verbindingssyntaxis en roltoewijzingen geldig. Zie Indexeerfuncties, vaardigheden of documenten uitvoeren of opnieuw instellen voor meer informatie.

Problemen met verbindingen oplossen

• Controleer voor Azure Cosmos DB voor NoSQL of het account zijn toegang tot geselecteerde netwerken beperkt is. U kunt firewallproblemen uitsluiten door de verbinding zonder beperkingen uit te voeren. Raadpleeg Indexer-toegang tot inhoud die wordt beveiligd door Azure netwerkbeveiliging voor meer informatie

• Voor Azure Cosmos DB voor NoSQL, als de indexeerfunctie mislukt vanwege verificatieproblemen, moet u ervoor zorgen dat de roltoewijzingen zijn uitgevoerd both op het besturingsvlak en het gegevensvlak van het Cosmos DB-account.

• Als u voor Gremlin of MongoDB onlangs uw Azure Cosmos DB-accountsleutels hebt gewisseld, moet u maximaal 15 minuten wachten voordat de beheerde identiteit verbindingsreeks werkt.

Zie ook

• Indexering via een Azure Cosmos DB voor NoSQL
• Indexeren via een Azure Cosmos DB voor MongoDB (preview)
• Indexeren via een Azure Cosmos DB voor Apache Gremlin (preview)