Připojení k Azure Cosmos DB pomocí spravované identity (Azure AI Vyhledávač)

Tento článek vysvětluje, jak nastavit připojení indexeru k databázi Azure Cosmos DB pomocí spravované identity místo zadání přihlašovacích údajů v připojovací řetězec.

Můžete použít spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem. Spravované identity jsou přihlášení systému Microsoft Entra a vyžadují přiřazení role v Azure pro přístup k datům v Azure Cosmos DB. Volitelně můžete vynutit přístup založený na rolích jako jedinou metodu ověřování pro datová připojení nastavením disableLocalAuth na true pro váš Azure Cosmos DB pro účet NoSQL.

Požadavky

• Vytvořte spravovanou identitu pro vyhledávací službu.

Omezení

• Indexery, které se připojují k Azure Cosmos DB pro Gremlin a MongoDB (aktuálně ve verzi Preview), podporují pouze přístup legacy.

Podporované přístupy pro ověřování spravovaných identit

Azure AI Vyhledávač podporuje dva mechanismy připojení k Azure Cosmos DB pomocí spravované identity.

• Přístup legacy vyžaduje konfiguraci spravované identity tak, aby měla oprávnění čtenáře k řídicí rovině cílového účtu Azure Cosmos DB. Azure AI Vyhledávač pomocí této identity získává klíče účtu služby Cosmos DB na pozadí pro přístup k datům. Tento přístup nebude fungovat, pokud účet Cosmos DB obsahuje "disableLocalAuth": true.

• Přístup modern vyžaduje konfiguraci odpovídajících rolí spravované identity v řídicí rovině a rovině dat cílového účtu Azure Cosmos DB. Azure AI Vyhledávač pak požádá o přístupový token pro přístup k datům v účtu Cosmos DB. Tento přístup funguje i v případě, že účet Cosmos DB má "disableLocalAuth": true.

Indexery, které se připojují k Azure Cosmos DB pro NoSQL, podporují jak přístup legacy, tak modern. Doporučuje se přístup modern.

Připojení k Azure Cosmos DB pro NoSQL

Tato část popisuje postup konfigurace připojení k Azure Cosmos DB pro NoSQL prostřednictvím přístupu modern.

Konfigurujte přiřazení rolí řídicí plochy

1. Přihlaste se k portálu Azure a vyhledejte svůj účet cosmos DB pro NoSQL.

2. Vyberte Řízení přístupu (IAM).

3. Vyberte Přidat a pak vyberte Přiřazení role.

4. V seznamu rolí pracovních funkcí vyberte Čtenář účtů služby Cosmos DB.

5. Vyberte Další.

6. Vyberte Spravovanou identitu a pak vyberte Členy.

7. Filtrování podle spravovaných identit přiřazených systémem nebo spravovaných identit přiřazených uživatelem Měla by se zobrazit spravovaná identita, kterou jste dříve vytvořili pro vyhledávací službu. Pokud ho nemáte, přečtěte si téma Konfigurace vyhledávání pro použití spravované identity. Pokud jste ho už nastavili, ale není k dispozici, dejte mu pár minut.

8. Vyberte identitu a uložte přiřazení role.

Další informace najdete v tématu Použití řízení přístupu na základě role pomocí Azure Cosmos DB pro NoSQL.

Konfigurace přiřazení rolí roviny dat

Spravované identitě musí být přiřazena role umožňující čtení z datové roviny účtu Cosmos DB. ID objektu (instančního objektu) pro identitu přiřazenou systémem nebo uživatelem vyhledávací služby najdete na kartě Identita vyhledávací služby. Tento krok je možné provést pouze prostřednictvím Azure CLI v tuto chvíli.

Nastavení proměnných:

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

Definujte přiřazení role pro identitu přiřazenou systémem:

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

Další informace najdete v tématu Použití řízení přístupu založeného na rolích v datové rovině s Azure Cosmos DB pro NoSQL

Konfigurace definice zdroje dat

Po nakonfigurování both přiřazení řídicí roviny a roviny dat na Azure Cosmos DB pro účet NoSQL můžete nastavit připojení, které funguje v rámci této role.

Indexery používají objekt zdroje dat pro připojení k externímu zdroji dat. Tato část vysvětluje, jak určit systémem přiřazenou spravovanou identitu nebo uživatelem přiřazenou spravovanou identitu v připojovacím řetězci k datovému zdroji. Další příklady připojovacích řetězců najdete v článku o spravované identitě.

Rozhraní REST API, portál Azure a .NET SDK podporuje použití spravované identity přiřazené systémem nebo přiřazené uživatelem.

Připojení prostřednictvím identity přiřazené systémem

Když se připojujete se spravovanou identitou přiřazenou systémem, jedinou změnou definice zdroje dat je formát vlastnosti "credentials". Zadejte název databáze a ID prostředku, které nemá žádný klíč účtu ani heslo. Id prostředku (ResourceId) musí zahrnovat ID předplatného Azure Cosmos DB, skupinu prostředků a název účtu Azure Cosmos DB.

Tady je příklad použití rozhraní REST API pro vytvoření zdroje dat , které provádí moderní přístup.

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

Připojení prostřednictvím identity přiřazené uživatelem

Do definice zdroje dat je potřeba přidat vlastnost identity, do které zadáte konkrétní identitu (z několika položek, které se dají přiřadit vyhledávací službě), která se použije pro připojení k účtu Azure Cosmos DB.

Tady je příklad použití identity přiřazené uživatelem prostřednictvím moderního přístupu.

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

Připojení k Azure Cosmos DB pro Gremlin nebo MongoDB (Preview)

Tato část popisuje postup konfigurace připojení k Azure Cosmos DB pro Gremlin/Mongo prostřednictvím přístupu legacy.

Konfigurujte přiřazení rolí řídicí plochy

Podle stejných kroků jako předtím přiřaďte příslušné role v řídicí rovině Azure Cosmos DB pro Gremlin/MongoDB.

Nastavte "připojovací řetězec"

• Pro kolekce MongoDB přidejte do připojovací řetězec "ApiKind=MongoDb" a použijte rozhraní REST API ve verzi Preview.
• V případě grafů Gremlin přidejte do připojovací řetězec "ApiKind=Gremlin" a použijte rozhraní REST API ve verzi Preview.
• U obou typů se podporuje pouze přístup legacy – tedy buď IdentityAuthType=AccountKey, anebo jej úplně vynechat jako jediný platný připojovací řetězec.

Tady je příklad připojení ke kolekcím MongoDB pomocí identity přiřazené systémem přes rozhraní 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
}

Tady je příklad připojení k grafům Gremlin pomocí identity přiřazené uživatelem.

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

Spuštěním indexeru ověřte oprávnění.

Informace o připojení a oprávnění ke vzdálené službě se během provádění indexeru ověřují za běhu. Pokud je indexer úspěšný, syntaxe připojení a přiřazení rolí jsou platné. Další informace najdete v sekci Spuštění nebo resetování indexerů, dovedností či dokumentů.

Řešení potíží s připojeními

• V případě Azure Cosmos DB pro NoSQL zkontrolujte, jestli má účet omezený přístup k vybraným sítím. Případné problémy s bránou firewall můžete vyloučit tak, že připojení vyzkoušíte bez omezení. Další informace najdete v Indexer přístupu k obsahu chráněnému zabezpečením sítě Azure

• V případě Azure Cosmos DB pro NoSQL, pokud indexer selže kvůli problémům s ověřováním, ujistěte se, že přiřazení rolí byla provedena jak na řídicí rovině, tak na datové rovině účtu Cosmos DB.

• Pokud jste v případě Gremlin nebo MongoDB nedávno obměněli klíče účtu Azure Cosmos DB, musíte počkat až 15 minut, než začne fungovat řetězec připojení pro spravovanou identitu.

Viz také

• Indexování pomocí Azure Cosmos DB pro NoSQL
• Indexování prostřednictvím Azure Cosmos DB pro MongoDB (Preview)
• Indexování prostřednictvím Azure Cosmos DB pro Apache Gremlin (Preview)