Ansluta till Azure Cosmos DB med hjälp av en hanterad identitet (Azure AI-sökning)

Den här artikeln beskriver hur du konfigurerar en indexeraranslutning till en Azure Cosmos DB databas med hjälp av en hanterad identitet i stället för att ange autentiseringsuppgifter i reťazec pripojenia."

Du kan använda en systemtilldelad hanterad identitet eller en användartilldelad hanterad identitet. Hanterade identiteter är Microsoft Entra inloggningar och kräver Azure rolltilldelningar för att komma åt data i Azure Cosmos DB. Du kan även tvinga rollbaserad åtkomst som den enda autentiseringsmetoden för dataanslutningar genom att ange disableLocalAuth till true för ditt Azure Cosmos DB för NoSQL-konto.

Förutsättningar

• Skapa en hanterad identitet för söktjänsten.

Begränsningar

• Indexerare som ansluter till Azure Cosmos DB för Gremlin och MongoDB (för närvarande i förhandsversion) stöder endast metoden legacy.

Metoder som stöds för autentisering av hanterad identitet

Azure AI-sökning stöder två mekanismer för att ansluta till Azure Cosmos DB med hjälp av hanterad identitet.

• Metoden legacy kräver att den hanterade identiteten konfigureras så att den har läsbehörighet på kontrollplanet för målkontot Azure Cosmos DB konto. Azure AI-sökning använder den identiteten för att hämta kontonycklarna för Cosmos DB-kontot i bakgrunden för att få åtkomst till data. Den här metoden fungerar inte om Cosmos DB-kontot har "disableLocalAuth": true.

• Metoden modern kräver att du konfigurerar lämpliga roller för den hanterade identiteten på kontroll- och dataplanet för målkontot Azure Cosmos DB. Azure AI-sökning begär sedan en åtkomsttoken för att få åtkomst till data i Cosmos DB-kontot. Den här metoden fungerar även om Cosmos DB-kontot har "disableLocalAuth": true.

Indexerare som ansluter till Azure Cosmos DB för NoSQL stöder både legacy- och modernmetoden – modernmetoden rekommenderas.

Anslut till Azure Cosmos DB för NoSQL

I det här avsnittet beskrivs stegen för att konfigurera anslutning till Azure Cosmos DB för NoSQL via metoden modern.

Konfigurera rolltilldelningar för kontrollplan

1. Logga in på Azure portalen och leta reda på ditt Cosmos DB för NoSQL konto.

2. Välj Åtkomstkontroll (IAM).

3. Välj Lägg till och välj sedan Rolltilldelning.

4. I listan över jobbfunktionsroller väljer du Cosmos DB-kontoläsare.

5. Välj Nästa.

6. Välj Hanterad identitet och välj sedan Medlemmar.

7. Filtrera efter systemtilldelade hanterade identiteter eller användartilldelade hanterade identiteter. Du bör se den hanterade identitet som du skapade tidigare för söktjänsten. Om du inte har någon kan du läsa Konfigurera sökning för att använda en hanterad identitet. Om du redan har konfigurerat en, men den inte är tillgänglig, kan du ge den några minuter.

8. Välj identiteten och spara rolltilldelningen.

Mer information finns i Använd rollbaserad åtkomstkontroll för kontrollplan med Azure Cosmos DB för NoSQL.

Konfigurera rolltilldelningar för dataplan

Den hanterade identiteten måste tilldelas en roll för att läsa från Cosmos DB-kontots dataplan. Objekt-ID :t (huvudnamn) för söktjänstens system-/användartilldelade identitet finns på söktjänstens "identitetsflik". Det här steget kan bara utföras via Azure CLI för tillfället.

Ange variabler:

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

Definiera en rolltilldelning för den systemtilldelade identiteten:

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

Mer information finns i Använd rollbaserad åtkomstkontroll för dataplan med Azure Cosmos DB för NoSQL

Konfigurera datakällans definition

När du har konfigurerat rolltilldelningarna för både kontrollplanet och dataplanet på Azure Cosmos DB för ett NoSQL-konto, kan du konfigurera en anslutning till den som fungerar under den rollen.

Indexerare använder ett datakällaobjekt för anslutningar till en extern datakälla. I det här avsnittet beskrivs hur du specificerar en systemtilldelad eller användartilldelad hanterad identitet i en reťazec pripojenia för en datakälla. Du kan hitta fler exempel på "reťazec pripojenias" i artikeln om hanterad identitet.

REST API:et, Azure-portalen och .NET SDK stöder användning av en systemtilldelad eller användartilldelad hanterad identitet.

Ansluta via systemtilldelad identitet

När du ansluter med en systemtilldelad hanterad identitet är den enda ändringen av datakällans definition formatet för egenskapen "autentiseringsuppgifter". Ange ett databasnamn och ett ResourceId som inte har någon kontonyckel eller lösenord. ResourceId måste innehålla prenumerations-ID för Azure Cosmos DB, resursgruppen och Azure Cosmos DB kontonamn.

Här är ett exempel med rest-API:et Skapa datakälla som använder den moderna metoden.

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

Ansluta via användartilldelad identitet

Du måste lägga till en "identitetsegenskap" i datakällans definition, där du anger den specifika identiteten (av flera som kan tilldelas till söktjänsten), som ska användas för att ansluta till Azure Cosmos DB-kontot.

Här är ett exempel med användartilldelad identitet via den moderna metoden.

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

Ansluta till Azure Cosmos DB för Gremlin/MongoDB (förhandsversion)

I det här avsnittet beskrivs stegen för att konfigurera anslutning till Azure Cosmos DB för Gremlin/Mongo via metoden legacy.

Konfigurera rolltilldelningar för kontrollplan

Följ samma steg som tidigare för att tilldela lämpliga roller på kontrollplanet för Azure Cosmos DB för Gremlin/MongoDB.

Ställ in anslutningssträng

• För MongoDB-samlingar lägger du till "ApiKind=MongoDb" i reťazec pripojenia och använder ett REST API för förhandsversion.
• För Gremlin-grafer lägger du till "ApiKind=Gremlin" i reťazec pripojenia och använder ett REST API för förhandsversion.
• För båda typerna stöds endast metoden legacy , det vill IdentityAuthType=AccountKey eller utelämna den helt och hållet är den enda giltiga reťazec pripojenia.

Här är ett exempel för att ansluta till MongoDB-samlingar med hjälp av systemtilldelad identitet via REST-API:et

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
}

Här är ett exempel för att ansluta till Gremlin-grafer med hjälp av användartilldelad identitet.

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

Kör indexeraren för att verifiera behörigheter

Anslutningsinformation och behörigheter för fjärrtjänsten verifieras under indexerarkörningen. Om indexeraren lyckas är anslutningssyntaxen och rolltilldelningarna giltiga. Mer information finns i Köra eller återställa indexerare, färdigheter eller dokument.

Felsöka anslutningar

• För Azure Cosmos DB för NoSQL kontrollerar du om kontot har begränsad åtkomst till utvalda nätverk. Du kan utesluta eventuella brandväggsproblem genom att prova anslutningen utan begränsningar. Mer information finns i Indexer-åtkomst till innehåll som skyddas av Azure nätverkssäkerhet

• Om indexeraren misslyckas på grund av autentiseringsproblem för Azure Cosmos DB för NoSQL kontrollerar du att rolltilldelningarna har gjorts both på kontrollplanet och dataplanet för Cosmos DB-kontot.

• Om du nyligen roterade dina Azure Cosmos DB-kontonycklar för Gremlin eller MongoDB måste du vänta upp till 15 minuter innan den hanterade identitetens anslutningssträng fungerar.

Se även

• Indexering genom Azure Cosmos DB för NoSQL
• Indexering via en Azure Cosmos DB för MongoDB (förhandsversion)
• Indexering via en Azure Cosmos DB för Apache Gremlin (förhandsversion)