Freigeben über

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

  • Artikel

In diesem Artikel wird erläutert, wie Sie eine Indexerverbindung mit einer Azure Cosmos DB-Datenbank mithilfe einer verwalteten Identität einrichten, statt Anmeldeinformationen in der Verbindungszeichenfolge anzugeben.'

Sie können eine systemseitig zugewiesene verwaltete Identität oder eine benutzerseitig 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. Optional können Sie rollenbasierten Zugriff als einzige Authentifizierungsmethode für Datenverbindungen erzwingen, indem Sie disableLocalAuth für Ihr Azure Cosmos DB for NoSQL-Konto auf true festlegen.

Voraussetzungen

Unterstützte Ansätze für die Authentifizierung mit verwalteter Identität

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

  • Der Legacy-Ansatz erfordert, dass die verwaltete Identität über Leseberechtigungen auf der Kontrollebene des Azure Cosmos DB-Zielkontos verfügt. Azure KI-Suche verwendet diese Identität, um die Kontoschlüssel des Cosmos DB-Kontos im Hintergrund abzurufen und auf die Daten zuzugreifen. Dieser Ansatz funktioniert nicht, wenn das Cosmos DB-Konto "disableLocalAuth": true hat.

  • Der moderne Ansatz erfordert die Konfiguration der entsprechenden Rollen der verwalteten Identität auf der Steuerungs- und Datenebene des Azure Cosmos DB-Zielkontos. 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 for NoSQL herstellen, unterstützen sowohl den Legacy-Ansatz als auch den modernen Ansatz – wobei der moderne Ansatz dringend empfohlen wird.

Einschränkungen

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

Herstellen einer Verbindung mit Azure Cosmos DB for NoSQL

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

Konfigurieren von Rollenzuweisungen auf Steuerungsebene

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie Ihr Cosmos DB for NoSQL-Konto.

  2. Wählen Sie Zugriffssteuerung (IAM) aus.

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

  4. Wählen Sie in der Liste der Stellenfunktionsrollen Cosmos DB Account Reader aus.

  5. Wählen Sie Weiter aus.

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

  7. Filtern Sie nach systemseitig zugewiesenen verwalteten Identitäten oder benutzerseitig zugewiesenen verwalteten Identitäten. Sie sollten die verwaltete Identität sehen, die Sie zuvor für Ihren Suchdienst erstellt haben. Wenn Sie keinen haben, lesen Sie Konfigurieren der Suche, um eine verwaltete Identität zu verwenden. Wenn Sie bereits eine Identität eingerichtet haben, aber diese nicht verfügbar ist, warten Sie ein paar Minuten.

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

Weitere Informationen finden Sie unter Verwenden der rollenbasierten Zugriffssteuerung auf Steuerungsebene mit Azure Cosmos DB for NoSQL.

Konfigurieren von Rollenzuweisungen auf Datenebene

Der verwalteten Identität muss eine Rolle zugewiesen sein, damit sie auf der Datenebene des Cosmos DB-Kontos lesen kann. Die Objekt-ID (Prinzipal-ID) für die system-/benutzerseitig 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.

Legen Sie Variablen fest:

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

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

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

Weitere Informationen finden Sie unter Verwenden der rollenbasierten Zugriffssteuerung auf Datenebene mit Azure Cosmos DB for NoSQL.

Konfigurieren der Datenquellendefinition

Nachdem Sie Rollenzuweisungen sowohl auf Steuerungsebene als auch auf Datenebene im Azure Cosmos DB for NoSQL-Konto konfiguriert haben, können Sie eine Verbindung einrichten, die unter dieser Rolle ausgeführt wird.

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

Tipp

Sie können eine Datenquellenverbindung mit CosmosDB im Azure-Portal erstellen, entweder eine vom System oder eine vom Benutzer zugewiesene verwaltete Identität angeben und dann die JSON-Definition anzeigen, um zu sehen, wie die Verbindungszeichenfolge formuliert ist.

Die Verwendung einer systemseitig oder benutzerseitig zugewiesenen verwalteten Identität wird von der REST-API, dem Azure-Portal und dem .NET SDK unterstützt.

Herstellen einer Verbindung über die systemseitig zugewiesene Identität

Wenn Sie eine Verbindung mit einer systemseitig zugewiesenen verwalteten Identität herstellen, besteht die einzige Änderung an der Datenquellendefinition im Format der Eigenschaft „credentials“. Geben Sie einen Datenbanknamen und eine ResourceId an, die weder über einen Kontoschlüssel noch über ein Kennwort verfügt, an. Die ResourceId muss die Abonnement-ID von Azure Cosmos DB, die Ressourcengruppe und den Namen des Azure Cosmos DB-Kontos enthalten.

Im Folgenden finden Sie ein Beispiel mit der REST-API Datenquelle erstellen, die den modernen Ansatz verwendet.

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

Hinweis

Wenn die IdentityAuthType-Eigenschaft nicht Teil der Verbindungszeichenfolge ist, verwendet Azure KI-Suche standardmäßig den Legacy-Ansatz, um die Abwärtskompatibilität zu gewährleisten.

Herstellen einer Verbindung über die benutzerseitig 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 benutzerseitig zugewiesenen Identität über den modernen Ansatz.

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

Herstellen einer Verbindung mit Azure Cosmos DB for Gremlin/MongoDB (Vorschau)

In diesem Abschnitt werden die Schritte zum Konfigurieren der Verbindung mit Azure Cosmos DB for Gremlin/Mongo über den Legacy-Ansatz beschrieben.

Konfigurieren von Rollenzuweisungen auf Steuerungsebene

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

Festlegen der Verbindungszeichenfolge

  • Bei MongoDB-Sammlungen fügen Sie der Verbindungszeichenfolge „ApiKind=MongoDb“ hinzu und verwenden eine Vorschau-REST-API.
  • Fügen Sie für Gremlin-Graphs der Verbindungszeichenfolge "ApiKind=Gremlin" 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 systemseitig zugewiesenen Identität über die 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
}

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

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

Ausführen des Indexers zum Überprüfen von Berechtigungen

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

Behandeln von Verbindungsproblemen

  • Überprüfen Sie für Azure Cosmos DB for NoSQL, ob das Konto seinen Zugriff auf ausgewählte Netzwerke beschränkt hat. Sie können Firewallprobleme ausschließen, indem Sie versuchen, die Verbindung ohne Einschränkungen herzustellen. Weitere Informationen dazu finden Sie unter Indexerzugriff auf mit Azure-Netzwerksicherheit geschützten Inhalt.

  • Wenn der Indexer aufgrund von Authentifizierungsproblemen fehlschlägt, stellen Sie für Azure Cosmos DB for NoSQL sicher, dass die Rollenzuweisungen sowohl auf der Steuerungsebene als auch auf der Datenebene des Cosmos DB-Kontos durchgeführt wurden.

  • 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.

Weitere Informationen