Herstellen einer Verbindung mit Azure Cosmos DB mithilfe einer verwalteten Identität (Azure KI-Suche)

In diesem Artikel wird erläutert, wie Sie eine Indexerverbindung mit einer Azure Cosmos DB-Datenbank mithilfe einer verwalteten Identität einrichten, anstatt Anmeldeinformationen im Verbindungszeichenfolge bereitzustellen."

Sie können eine vom System zugewiesene verwaltete Identität oder eine vom Benutzer zugewiesene verwaltete Identität verwenden. Verwaltete Identitäten sind Microsoft Entra Anmeldungen und erfordern Azure Rollenzuweisungen für den Zugriff auf Daten in Azure Cosmos DB. Sie können optional den rollenbasierten Zugriff als einzige Authentifizierungsmethode für Datenverbindungen festlegen, indem Sie für Ihr Azure Cosmos DB für NoSQL-Konto auf disableLocalAuth setzen.

Voraussetzungen

• Erstellen Sie eine verwaltete Identität für Ihren Suchdienst.

Einschränkungen

• Indexer, die eine Verbindung mit Azure Cosmos DB für Gremlin und MongoDB (derzeit in der Vorschau) herstellen, unterstützen nur den Ansatz legacy.

Unterstützte Ansätze für die verwaltete Identitätsauthentifizierung

Azure KI-Suche unterstützt zwei Mechanismen zum Herstellen einer Verbindung mit Azure Cosmos DB mithilfe der verwalteten Identität.

• Der Ansatz legacy erfordert die Konfiguration der verwalteten Identität, um Leseberechtigungen auf der Kontrollebene des Zielkontos Azure Cosmos DB zu haben. Azure KI-Suche verwendet diese Identität, um die Kontoschlüssel des Cosmos DB-Kontos im Hintergrund abzurufen, um auf die Daten zuzugreifen. Dieser Ansatz funktioniert nicht, wenn das Cosmos DB-Konto "disableLocalAuth": true hat.

• Der Ansatz modern erfordert die Konfiguration der entsprechenden Rollen der verwalteten Identität auf der Steuerungs- und Datenebene des Ziel-Azure-Cosmos-DB-Kontos. Azure KI-Suche fordert dann ein Zugriffstoken für den Zugriff auf die Daten im Cosmos DB-Konto an. Dieser Ansatz funktioniert auch dann, wenn das Cosmos DB-Konto "disableLocalAuth": true hat.

Indexer, die eine Verbindung mit Azure Cosmos DB für NoSQL herstellen, unterstützen sowohl den legacy als auch den ansatz modern – der modern Ansatz wird empfohlen.

Herstellen einer Verbindung mit Azure Cosmos DB für NoSQL

In diesem Abschnitt werden die Schritte zum Konfigurieren der Verbindung mit Azure Cosmos DB für NoSQL über den Ansatz modern beschrieben.

Konfigurieren von Rollenzuweisungen für die Steuerungsebene

1. Melden Sie sich bei Azure Portal an, und suchen Sie Ihr Cosmos DB für NoSQL Konto.

2. Wählen Sie access control (IAM) aus.

3. Wählen Sie "Hinzufügen" und dann "Rollenzuweisung" aus.

4. Wählen Sie in der Liste der Rollen der Auftragsfunktion die Option Cosmos DB Account Reader aus.

5. Wählen Sie "Weiter" aus.

6. Wählen Sie "Verwaltete Identität " und dann " Mitglieder" aus.

7. Filtern Nach vom System zugewiesenen verwalteten Identitäten oder vom Benutzer zugewiesenen verwalteten Identitäten. Sie sollten die verwaltete Identität sehen, die Sie zuvor für Ihren Suchdienst erstellt haben. Wenn Sie keins haben, lesen Sie " Konfigurieren der Suche für die Verwendung einer verwalteten Identität". Wenn Sie bereits eins eingerichtet haben, aber es nicht verfügbar ist, geben Sie es ein paar Minuten.

8. Wählen Sie die Identität aus, und speichern Sie die Rollenzuweisung.

Weitere Informationen finden Sie unter Verwenden Sie rollenbasierte Zugriffssteuerung für die Steuerungsebene mit Azure Cosmos DB für NoSQL.

Konfigurieren Sie Rollenzuweisungen in der Datenebene

Der verwalteten Identität muss eine Rolle zugewiesen werden, damit sie von der Datenebene des Cosmos DB-Kontos lesen kann. Die Objekt-ID (Prinzipal-ID) für die system-/benutzer zugewiesene Identität des Suchdiensts finden Sie auf der Registerkarte "Identität" des Suchdiensts. Dieser Schritt kann derzeit nur über Azure CLI ausgeführt werden.

Festlegen von Variablen:

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

Definieren Sie eine Rollenzuweisung für die vom System zugewiesene Identität:

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

Weitere Informationen finden Sie unter Datenebene rollenbasierte Zugriffskontrolle mit Azure Cosmos DB für NoSQL verwenden

Konfigurieren der Datenquellendefinition

Sobald Sie die Rollenzuweisungen für beide, die Steuer- und die Datenebene, im Azure Cosmos DB für das NoSQL-Konto konfiguriert haben, können Sie eine Verbindung dazu einrichten, die unter diesen Rollen ausgeführt wird.

Indexer verwenden ein Datenquellenobjekt für Verbindungen mit einer externen Datenquelle. In diesem Abschnitt wird erläutert, wie Sie eine vom System zugewiesene verwaltete Identität oder eine vom Benutzer zugewiesene verwaltete Identität in einer Verbindungszeichenfolge einer Datenquelle angeben. Weitere Verbindungszeichenfolge Beispiele finden Sie im Artikel zur verwalteten Identität.

Die REST-API, Azure Portal und das .NET SDK unterstützen die Verwendung einer vom System zugewiesenen oder vom Benutzer zugewiesenen verwalteten Identität.

Verbinden über vom System zugewiesene Identität

Wenn Sie eine Verbindung mit einer vom System zugewiesenen verwalteten Identität herstellen, ist die einzige Änderung an der Datenquellendefinition das Format der Eigenschaft "credentials". Geben Sie einen Datenbanknamen und eine ResourceId mit keinem Kontoschlüssel oder Kennwort an. Die ResourceId muss die Abonnement-ID von Azure Cosmos DB, die Ressourcengruppe und den namen des Azure Cosmos DB Kontos enthalten.

Hier ist ein Beispiel mit der REST-API zum Erstellen von Datenquellen , die den modernen Ansatz ausübt.

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

Verbinden über die vom Benutzer zugewiesene Identität

Sie müssen der Datenquellendefinition eine "Identity"-Eigenschaft hinzufügen, in der Sie die spezifische Identität angeben (aus mehreren, die dem Suchdienst zugewiesen werden können), die zum Herstellen einer Verbindung mit dem Azure Cosmos DB Konto verwendet werden.

Hier ist ein Beispiel für die Verwendung der vom Benutzer zugewiesenen Identität über den modernen Ansatz.

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

Herstellen einer Verbindung mit Azure Cosmos DB für Gremlin/MongoDB (Vorschau)

In diesem Abschnitt werden die Schritte zum Konfigurieren der Verbindung mit Azure Cosmos DB für Gremlin/Mongo über den Ansatz legacy beschrieben.

Konfigurieren von Rollenzuweisungen für die Steuerungsebene

Führen Sie die gleichen Schritte wie zuvor aus, um die entsprechenden Rollen auf der Kontrollebene der Azure Cosmos DB für Gremlin/MongoDB zuzuweisen.

Festlegen der Verbindungszeichenfolge

• Fügen Sie für MongoDB-Sammlungen "ApiKind=MongoDb" zum Verbindungszeichenfolge hinzu, und verwenden Sie eine Vorschau-REST-API.
• Fügen Sie für Gremlin-Diagramme "ApiKind=Gremlin" zum Verbindungszeichenfolge hinzu, und verwenden Sie eine Vorschau-REST-API.
• Bei beiden Arten wird nur der Legacy-Ansatz unterstützt, d. h. die einzige gültige Verbindungszeichenfolge ist IdentityAuthType=AccountKey oder das vollständige Auslassen.

Hier ist ein Beispiel zum Herstellen einer Verbindung mit MongoDB-Sammlungen mithilfe der vom System zugewiesenen Identität über die 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
}

Hier ist ein Beispiel zum Herstellen einer Verbindung mit Gremlin-Diagrammen mithilfe der vom Benutzer zugewiesenen Identität.

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

Führen Sie den Indexer aus, um Berechtigungen zu überprüfen.

Verbindungsinformationen und -berechtigungen für den Remotedienst werden während der Indexerausführung zur Laufzeit überprüft. Wenn der Indexer erfolgreich ist, sind die Verbindungssyntax und Rollenzuweisungen gültig. Weitere Informationen finden Sie unter Ausführen oder Zurücksetzen von Indexern, Qualifikationen oder Dokumenten.

Problembehandlung bei Verbindungen

• Überprüfen Sie für Azure Cosmos DB für NoSQL, ob das Konto seinen Zugriff auf ausgewählte Netzwerke beschränkt hat. Sie können Alle Firewallprobleme ausschließen, indem Sie die Verbindung ohne Einschränkungen ausprobieren. Weitere Informationen finden Sie unter Indexer-Zugriff auf Inhalte, die durch Azure Netzwerksicherheit geschützt sind

• Stellen Sie für Azure Cosmos DB für NoSQL sicher, dass die Rollenzuweisungen both auf der Steuerungsebene und datenebene des Cosmos DB-Kontos durchgeführt wurden, wenn der Indexer aufgrund von Authentifizierungsproblemen fehlschlägt.

• Wenn Ihre Azure Cosmos DB-Kontoschlüssel für Gremlin oder MongoDB kürzlich rotiert wurden, müssen Sie bis zu 15 Minuten warten, bis die Verbindungszeichenfolge für verwaltete Identitäten funktioniert.

Siehe auch

• Indexing über eine Azure Cosmos DB für NoSQL
• Indizierung über Azure Cosmos DB for MongoDB (Vorschau)
• Indizierung über Azure Cosmos DB für Apache Gremlin (Vorschau)