Delen via

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

  • Artikel

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 optioneel op rollen gebaseerde toegang afdwingen als de enige verificatiemethode voor gegevensverbindingen door deze in te true stellen disableLocalAuth voor uw Azure Cosmos DB for NoSQL-account.

Vereisten

Ondersteunde benaderingen voor verificatie van beheerde identiteiten

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

  • Voor de verouderde benadering moet u de beheerde identiteit configureren om leesmachtigingen te hebben op het besturingsvlak van het Azure Cosmos DB-doelaccount. Azure AI Search 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

  • De moderne benadering vereist het configureren van de juiste rollen voor de beheerde identiteit op het besturings- en gegevensvlak van het Azure Cosmos DB-doelaccount. Azure AI Search 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

Indexeerfuncties die verbinding maken met Azure Cosmos DB for NoSQL ondersteunen zowel de verouderde als de moderne benadering. De moderne benadering wordt ten zeerste aanbevolen.

Beperkingen

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

Verbinding maken met Azure Cosmos DB for NoSQL

In deze sectie vindt u een overzicht van de stappen voor het configureren van verbinding met Azure Cosmos DB for NoSQL via de moderne benadering.

Roltoewijzingen van het besturingsvlak configureren

  1. Meld u aan bij Azure Portal en zoek uw Cosmos DB for NoSQL-account.

  2. Klik op 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 deze niet beschikbaar is, geeft u deze 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-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Definieer een roltoewijzing voor de door het systeem toegewezen identiteit:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

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

De definitie van de gegevensbron configureren

Zodra u zowel de roltoewijzingen van het besturingsvlak als het gegevensvlak hebt geconfigureerd in het Azure Cosmos DB for 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 op een gegevensbron verbindingsreeks opgeeft. Meer verbindingsreeks voorbeelden vindt u in het artikel over beheerde identiteiten.

Tip

U kunt een gegevensbronverbinding maken met Cosmos DB in Azure Portal, een door het systeem of de gebruiker toegewezen beheerde identiteit opgeven en vervolgens de JSON-definitie bekijken om te zien hoe de verbindingsreeks is geformuleerd.

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

Notitie

Als de IdentityAuthType eigenschap geen deel uitmaakt van de verbindingsreeks, wordt azure AI Search standaard ingesteld op de verouderde benadering om compatibiliteit met eerdere versies te garanderen.

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

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

In deze sectie vindt u een overzicht van de stappen voor het configureren van verbinding met Azure Cosmos DB voor Gremlin/Mongo via de verouderde benadering.

Roltoewijzingen van het besturingsvlak configureren

Volg dezelfde stappen als voorheen om de juiste rollen toe te wijzen op het besturingsvlak van 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 verouderde benadering ondersteund, dat wil IdentityAuthType=AccountKey gezegd, of het volledig weglaten 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=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
}

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

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 for NoSQL of het account toegang heeft tot het selecteren van netwerken. U kunt firewallproblemen uitsluiten door de verbinding zonder beperkingen uit te voeren. Raadpleeg de toegang van indexeerfunctie tot inhoud die wordt beveiligd door Azure-netwerkbeveiliging voor meer informatie

  • Als de indexeerfunctie mislukt vanwege verificatieproblemen in Azure Cosmos DB for NoSQL, moet u ervoor zorgen dat de roltoewijzingen zowel op het besturingsvlak als op het gegevensvlak van het Cosmos DB-account zijn uitgevoerd.

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

Zie ook