Sdílet prostřednictvím

Připojení ke službě Azure Cosmos DB pomocí spravované identity (Azure AI Search)

  • Článek

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í Microsoft Entra a vyžadují přiřazení rolí Azure pro přístup k datům ve službě Azure Cosmos DB. Volitelně můžete vynutit přístup na základě role jako jedinou metodu ověřování pro datová připojení nastavením disableLocalAuth pro true váš účet Azure Cosmos DB for NoSQL.

Požadavky

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

Azure AI Search podporuje dva mechanismy připojení ke službě Azure Cosmos DB pomocí spravované identity.

  • Starší verze přístupu vyžaduje, aby spravovaná identita měla oprávnění čtenáře k řídicí rovině cílového účtu služby Azure Cosmos DB. Azure AI Search využívá danou identitu k načtení klíčů úč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.

  • Moderní přístup vyžaduje konfiguraci odpovídajících rolí spravované identity v řídicí rovině a rovině dat cílového účtu služby Azure Cosmos DB. Azure AI Search 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í ke službě Azure Cosmos DB for NoSQL, podporují starší i moderní přístup – moderní přístup se důrazně doporučuje.

Omezení

  • Indexery, které se připojují ke službě Azure Cosmos DB pro Gremlin a MongoDB (aktuálně ve verzi Preview), podporují pouze starší přístup.

Připojení ke službě Azure Cosmos DB for NoSQL

Tato část popisuje kroky konfigurace připojení ke službě Azure Cosmos DB for NoSQL prostřednictvím moderního přístupu.

Konfigurace přiřazení rolí řídicí roviny

  1. Přihlaste se k webu Azure Portal a vyhledejte svůj účet Cosmos DB for NoSQL.

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

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

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

  5. Vyberte Další.

  6. Vyberte Spravovanou identitu a pak vyberte Členové.

  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í řízení přístupu na základě role se službou Azure Cosmos DB for NoSQL.

Konfigurace přiřazení rolí roviny dat

Spravovaná identita musí přiřadit roli ke čtení z roviny dat úč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 přes Azure CLI.

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-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

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

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

Další informace najdete v tématu Použití řízení přístupu na základě role na základě roviny dat se službou Azure Cosmos DB for NoSQL.

Konfigurace definice zdroje dat

Jakmile nakonfigurujete přiřazení rolí řídicí roviny i roviny dat v účtu Azure Cosmos DB for NoSQL, můžete k ní 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 spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem ve zdroji dat připojovací řetězec. Další připojovací řetězec příklady najdete v článku o spravované identitě.

Tip

Připojení ke zdroji dat ke službě Cosmos DB můžete vytvořit na webu Azure Portal, zadat spravovanou identitu přiřazenou systémem nebo uživatelem a pak zobrazit definici JSON a podívat se, jak se připojovací řetězec formuluje.

Rozhraní REST API, Azure Portal a podpora sady .NET SDK pomocí 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 musí obsahovat ID předplatného služby Azure Cosmos DB, skupinu prostředků a název účtu služby 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=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]" }
}

Poznámka:

IdentityAuthType Pokud tato vlastnost není součástí připojovací řetězec, azure AI Search ve výchozím nastavení používá starší verzi, aby se zajistila zpětná kompatibilita.

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

Připojení ke službě Azure Cosmos DB pro Gremlin nebo MongoDB (Preview)

Tato část popisuje postup konfigurace připojení ke službě Azure Cosmos DB pro Gremlin/Mongo prostřednictvím starší verze přístupu.

Konfigurace přiřazení rolí řídicí roviny

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

Nastavit 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ů je podporován pouze starší přístup – to znamená, IdentityAuthType=AccountKey že je vynechání zcela 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=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
}

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

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 tématu Spuštění nebo resetování indexerů, dovedností nebo dokumentů.

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

  • V případě služby Azure Cosmos DB for 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 tématu Přístup indexeru k obsahu chráněnému zabezpečením sítě Azure.

  • Pokud indexer kvůli problémům s ověřováním selže, ujistěte se, že se přiřazení rolí prováděla v řídicí rovině i v rovině dat účtu Cosmos DB.

  • Pokud jste nedávno obměněli klíče účtu Služby Azure Cosmos DB pro Gremlin nebo MongoDB, musíte počkat až 15 minut, než spravovaná identita připojovací řetězec fungovat.

Viz také