Csatlakozás Azure Cosmos DB felügyelt identitással (Azure AI Keresés)

Ez a cikk azt ismerteti, hogyan állíthat be indexelő kapcsolatot egy Azure Cosmos DB adatbázishoz felügyelt identitással ahelyett, hogy hitelesítő adatokat ad meg a kapcsolati karakterlánc."

Használhat rendszer által hozzárendelt felügyelt identitást vagy felhasználó által hozzárendelt felügyelt identitást. Az Entra által felügyelt identitások Microsoft bejelentkezések, és az Azure szerepkör-hozzárendeléseket igényelnek az Azure Cosmos DB adatainak eléréséhez. Igény szerint kényszerítheti a szerepköralapú hozzáférést, mint az egyetlen hitelesítési módszert az disableLocalAuth beállításával true, az Azure Cosmos DB NoSQL-fiókjához.

Előfeltételek

• Felügyelt identitás létrehozása a keresési szolgáltatáshoz.

Korlátozások

• A Gremlin és a MongoDB Azure Cosmos DB csatlakozó indexelői (jelenleg előzetes verzióban) csak a legacy megközelítést támogatják.

A felügyelt identitás hitelesítésének támogatott megközelítései

Azure AI Keresés két mechanizmust támogat az Azure Cosmos DB felügyelt identitással való csatlakozáshoz.

• A legacy megközelítéshez úgy kell konfigurálnia a felügyelt identitást, hogy olvasói engedélyekkel rendelkezzen a cél Azure Cosmos DB fiók vezérlősíkján. Azure AI Keresés ezt az identitást használja a Cosmos DB-fiók fiókkulcsainak lekérésére a háttérben az adatok eléréséhez. Ez a módszer nem működik, ha a Cosmos DB-fiók rendelkezik "disableLocalAuth": true.

• A modern megközelítéshez konfigurálni kell a felügyelt identitás megfelelő szerepkörét a cél Azure Cosmos DB fiók vezérlő- és adatsíkján. Azure AI Keresés ezután hozzáférési jogkivonatot kér a Cosmos DB-fiók adatainak eléréséhez. Ez a módszer akkor is működik, ha a Cosmos DB-fiók rendelkezik "disableLocalAuth": true.

A NoSQL Azure Cosmos DB csatlakozó indexelői támogatják a legacy és a modern megközelítést – a modern megközelítést javasoljuk.

Csatlakozás az Azure Cosmos DB-hez a NoSQL adatbázisokhoz.

Ez a szakasz a Azure Cosmos DB NoSQL modern megközelítésen keresztül történő csatlakozás konfigurálásának lépéseit ismerteti.

Vezérlősík szerepkör-hozzárendeléseinek konfigurálása

1. Jelentkezzen be Azure portálra, és keresse meg a Cosmos DB-t NoSQL-fiókjához.

2. Válassza a Hozzáférés-vezérlés (IAM) lehetőséget.

3. Válassza a Hozzáadás , majd a Szerepkör-hozzárendelés lehetőséget.

4. A feladatfüggvény-szerepkörök listájában válassza a Cosmos DB-fiókolvasó lehetőséget.

5. Válassza a Tovább gombot.

6. Válassza a Felügyelt identitás lehetőséget, majd válassza a Tagok lehetőséget.

7. Szűrés rendszer által hozzárendelt felügyelt identitások vagy felhasználó által hozzárendelt felügyelt identitások alapján. Látnia kell a keresési szolgáltatáshoz korábban létrehozott felügyelt identitást. Ha nincs ilyenje, olvassa el a Keresés konfigurálása felügyelt identitás használatára című témakört. Ha már beállított egyet, de nem érhető el, várjon pár percet.

8. Jelölje ki az identitást, és mentse a szerepkör-hozzárendelést.

További információért tekintse meg: Szerepköralapú hozzáférés-vezérlés használata a vezérlősíkon az Azure Cosmos DB NoSQL esetében.

Adatsík szerepkör-hozzárendeléseinek konfigurálása

A felügyelt identitásnak hozzá kell rendelnie egy szerepkört a Cosmos DB-fiók adatsíkjáról való olvasáshoz. A keresési szolgáltatás rendszer-/felhasználó által hozzárendelt identitásának objektum-(egyszerű) azonosítója a keresési szolgáltatás "Identitás" lapján található. Ez a lépés jelenleg csak Azure CLI keresztül hajtható végre.

Változók beállítása:

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

Szerepkör-hozzárendelés definiálása a rendszer által hozzárendelt identitáshoz:

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

További információért tekintse meg az alábbi elemet: Az adatsík szerepkör-alapú hozzáférés-vezérlésének használata az Azure Cosmos DB-NoSQL-hez.

Az adatforrás definíciójának konfigurálása

Miután konfigurálta both vezérlősík- és adatsík-szerepkör-hozzárendeléseket a Azure Cosmos DB NoSQL-fiókhoz, beállíthatja az adott szerepkör alatt működő kapcsolatot.

Az indexelők adatforrás-objektumot használnak külső adatforráshoz való kapcsolatokhoz. Ez a szakasz elmagyarázza, hogyan lehet megadni a rendszer által hozzárendelt felügyelt identitást vagy a felhasználó által hozzárendelt felügyelt identitást egy adatforrás kapcsolati sztringen. A felügyelt identitásról szóló cikkben további kapcsolati karakterlánc példákat talál.

A REST API, Azure portál és a .NET SDK a rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitás használatával támogatja.

Csatlakozás rendszer által hozzárendelt identitáson keresztül

Ha egy rendszer által hozzárendelt felügyelt identitással csatlakozik, az adatforrás definíciójának egyetlen változása a "hitelesítő adatok" tulajdonság formátuma. Adjon meg egy adatbázisnevet és egy ResourceId azonosítót, amelyhez nem tartozik sem fiókkulcs, sem jelszó. A ResourceId-nek tartalmaznia kell a Azure Cosmos DB előfizetési azonosítóját, az erőforráscsoportot és a Azure Cosmos DB fiók nevét.

Íme egy példa az Adatforrás létrehozása REST API-val, amely a modern megközelítést alkalmazza.

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

Csatlakozás felhasználó által hozzárendelt identitáson keresztül

Hozzá kell adnia egy "identity" tulajdonságot az adatforrás-definícióhoz, amelyben meg kell adnia azt a konkrét identitást (a keresési szolgáltatáshoz rendelhető számos közül), amelyet a Azure Cosmos DB-fiókhoz való csatlakozáshoz fog használni.

Íme egy példa, amely a felhasználó által hozzárendelt identitást használja a modern megközelítéssel.

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

Csatlakozás az Azure Cosmos DB-hoz Gremlin/MongoDB esetén (előzetes)

Ez a szakasz a Gremlin/Mongo Azure Cosmos DB való csatlakozásának konfigurálásának lépéseit ismerteti a legacy megközelítésen keresztül.

Vezérlősík szerepkör-hozzárendeléseinek konfigurálása

A Gremlin/MongoDB Azure Cosmos DB vezérlősíkján a korábbiakhoz hasonló lépéseket követve rendelje hozzá a megfelelő szerepköröket.

A kapcsolati karakterlánc beállítása

• MongoDB-gyűjtemények esetén adja hozzá az "ApiKind=MongoDb" kifejezést a kapcsolati karakterlánc, és használjon egy előzetes REST API-t.
• Gremlin-grafikonok esetén adja hozzá az "ApiKind=Gremlin" kifejezést a kapcsolati karakterlánc, és használjon egy előzetes REST API-t.
• Mindkét típus esetében csak a legacy megközelítés támogatott, vagyis a IdentityAuthType=AccountKey vagy annak teljes kihagyása az egyetlen érvényes kapcsolati karakterlánc.

Íme egy példa a MongoDB-gyűjteményekhez való csatlakozáshoz rendszer által hozzárendelt identitással a REST API-val

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
}

Íme egy példa a Gremlin-gráfokhoz való csatlakozáshoz felhasználó által hozzárendelt identitás használatával.

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

Az engedélyek ellenőrzéséhez futtassa az indexelőt

A távoli szolgáltatás kapcsolati adatai és engedélyei futásidőben lesznek érvényesítve az indexelő végrehajtása során. Ha az indexelő sikeres, a kapcsolat szintaxisa és a szerepkör-hozzárendelések érvényesek. További információ: Indexelők, készségek vagy dokumentumok futtatása vagy alaphelyzetbe állítása.

Kapcsolatok hibaelhárítása

• Ellenőrizze, hogy a(z) Azure Cosmos DB NoSQL-hoz az adott fiók hozzáférése korlátozott-e a kiválasztott hálózatokra. A tűzfallal kapcsolatos problémákat kizárhatja, ha korlátozás nélkül próbálja meg a kapcsolatot. További információért tekintse meg Indexer hozzáférését Azure hálózati biztonság által védett tartalmakhoz

• A NoSQL Azure Cosmos DB esetén, ha az indexelő hitelesítési problémák miatt meghiúsul, győződjön meg arról, hogy a szerepkör-hozzárendelések both lettek végrehajtva a Cosmos DB-fiók vezérlősíkján és adatsíkján.

• Gremlin vagy MongoDB esetén, ha nemrég elforgatta az Azure Cosmos DB hozzáférési kulcsait, akár 15 percet is várnia kell, amíg a felügyelt identitás kapcsolati karakterlánc működni kezd.

Lásd még:

• Indexelés egy Azure Cosmos DB segítségével NoSQL-hez
• Indexelés a MongoDB Azure Cosmos DB keresztül (előzetes verzió)
• Indexelés az Azure Cosmos DB for Apache Gremlin használatával (előzetes verzió)