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.

Vereisten

Beperkingen

Ondersteuning voor indexeerfuncties voor Azure Cosmos DB voor Gremlin- en MongoDB-verzamelingen is momenteel beschikbaar als preview-versie. Op dit moment vereist een preview-beperking dat Azure AI Search verbinding maakt met behulp van sleutels. U kunt nog steeds een beheerde identiteit en roltoewijzing instellen, maar Azure AI Search gebruikt alleen de roltoewijzing om sleutels voor de verbinding op te halen. Deze beperking betekent dat u geen op rollen gebaseerde benadering kunt configureren als uw indexeerfuncties verbinding maken met Gremlin of MongoDB.

Een roltoewijzing maken in Azure Cosmos DB

  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 configureren met Microsoft Entra ID voor uw Azure Cosmos DB-account voor meer informatie.

Een beheerde identiteit opgeven in een verbindingsreeks

Zodra u een roltoewijzing hebt, kunt u een verbinding instellen met Azure Cosmos DB for NoSQL 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 CosmosDB 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.

Door het systeem toegewezen beheerde identiteit

De REST API, Azure Portal en de .NET SDK-ondersteuning met behulp van een door het systeem toegewezen beheerde 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.

  • Voor SQL-verzamelingen is voor de verbindingsreeks geen ApiKind vereist.
  • Voor SQL-verzamelingen voegt u IdentityAuthType=AccessToken toe als op rollen gebaseerde toegang wordt afgedwongen als de enige verificatiemethode. Deze is niet van toepassing op MongoDB- en Gremlin-verzamelingen.
  • 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.

Hier volgt een voorbeeld van het maken van een gegevensbron voor het indexeren van gegevens uit een Cosmos DB-account met behulp van de REST API voor gegevensbron maken en een beheerde identiteit verbindingsreeks. De indeling van de beheerde identiteit verbindingsreeks is hetzelfde voor de REST API, .NET SDK en Azure Portal.

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

 
}

Door de gebruiker toegewezen beheerde identiteit

Wanneer u verbinding maakt met een door de gebruiker toegewezen beheerde identiteit, zijn er twee wijzigingen in de definitie van de gegevensbron:

  • Eerst is de indeling van de eigenschap Referenties de naam van de database en een ResourceId 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.

    • Voor SQL-verzamelingen is voor de verbindingsreeks geen ApiKind vereist.
    • Voor SQL-verzamelingen voegt u IdentityAuthType=AccessToken toe als op rollen gebaseerde toegang wordt afgedwongen als de enige verificatiemethode. Deze is niet van toepassing op MongoDB- en Gremlin-verzamelingen.
    • Voor MongoDB-verzamelingen voegt u 'ApiKind=MongoDb' toe aan de verbindingsreeks
    • Voor Gremlin-grafieken voegt u 'ApiKind=Gremlin' toe aan de verbindingsreeks.

  • Ten tweede voegt u een 'identiteit'-eigenschap toe die de verzameling door de gebruiker toegewezen beheerde identiteiten bevat. Er moet slechts één door de gebruiker toegewezen beheerde identiteit worden opgegeven bij het maken van de gegevensbron. Stel deze in om 'userAssignedIdentities' te typen.

Hier volgt een voorbeeld van het maken van een gegevensbronobject voor een indexeerfunctie met behulp van de REST API.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

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.

Probleemoplossing

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.

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