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.

Voraussetzungen

Begrenzungen

Die Indexerunterstützung für Azure Cosmos DB für Gremlin- und MongoDB-Sammlungen befindet sich derzeit in der Vorschau. Zu diesem Zeitpunkt gilt eine Einschränkung für die Vorschauversion, die erfordert, dass Azure KI-Suche zum Herstellen einer Verbindung Schlüssel verwendet. Sie können zwar eine verwaltete Identität und Rollenzuweisung einrichten, Azure KI Search verwendet jedoch nur die Rollenzuweisung, um Schlüssel für die Verbindung abzurufen. Diese Einschränkung bedeutet, dass Sie keinen rollenbasierten Ansatz konfigurieren können, wenn Ihre Indexer eine Verbindung mit Gremlin oder MongoDB herstellen.

Erstellen einer Rollenzuweisung in Azure Cosmos DB

  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 Konfigurieren der rollenbasierten Zugriffssteuerung mit Microsoft Entra ID für Ihr Azure Cosmos DB-Konto.

Geben Sie eine verwaltete Identität in einer Verbindungszeichenfolge an

Sobald Sie über eine Rollenzuweisung verfügen, können Sie eine Verbindung mit Azure Cosmos DB for NoSQL 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 ein System oder eine vom Benutzer zugewiesene verwaltete Identität angeben, und dann die JSON-Definition anzeigen, um zu sehen, wie die Verbindungszeichenfolge formuliert ist.

Systemseitig zugewiesene verwaltete Identität

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

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.

  • Bei SQL-Sammlungen muss „ApiKind“ nicht in der Verbindungszeichenfolge enthalten sein.
  • Fügen Sie für SQL-Sammlungen „IdentityAuthType=AccessToken“ hinzu, wenn rollenbasierter Zugriff als einzige Authentifizierungsmethode erzwungen wird. Dies gilt nicht für MongoDB- und Gremlin-Sammlungen.
  • 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.

Hier finden Sie ein Beispiel für das Erstellen einer Datenquelle zum Indizieren von Daten aus einem Cosmos DB-Konto mithilfe der REST-API zum Erstellen von Datenquellen und einer Verbindungszeichenfolge für verwaltete Identitäten. Das Format der Verbindungszeichenfolge für verwaltete Identitäten ist für die REST-API, das .NET SDK und das Azure-Portal identisch.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Benutzerseitig zugewiesene verwaltete Identität

Wenn Sie eine Verbindung mit einer benutzerseitig zugewiesenen verwalteten Identität herstellen, erfolgen zwei Änderungen an der Datenquellendefinition:

  • Erstens ist das Format der Eigenschaft „credentials“ (Anmeldeinformationen) der Datenbankname und eine RessourceId ohne Kontoschlüssel oder Kennwort. Die ResourceId muss die Abonnement-ID von Azure Cosmos DB, die Ressourcengruppe und den Namen des Azure Cosmos DB-Kontos enthalten.

    • Bei SQL-Sammlungen muss „ApiKind“ nicht in der Verbindungszeichenfolge enthalten sein.
    • Fügen Sie für SQL-Sammlungen „IdentityAuthType=AccessToken“ hinzu, wenn rollenbasierter Zugriff als einzige Authentifizierungsmethode erzwungen wird. Dies gilt nicht für MongoDB- und Gremlin-Sammlungen.
    • Bei MongoDB-Sammlungen fügen Sie der Verbindungszeichenfolge „ApiKind=MongoDb“ hinzu.
    • Fügen Sie für Gremlin-Graphs der Verbindungszeichenfolge "ApiKind=Gremlin" hinzu.

  • Zweitens fügen Sie eine „identity“-Eigenschaft hinzu, die die Sammlung der benutzerseitig zugewiesenen verwalteten Identitäten enthält. Beim Erstellen der Datenquelle sollte nur eine benutzerseitig zugewiesene verwaltete Identität bereitgestellt werden. Legen Sie sie auf den Typ „userAssignedIdentities“ fest.

Beispiel für die Erstellung eines Indexer-Datenquellenobjekts mithilfe der REST-API.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

Verbindungsinformationen und -berechtigungen für den Remotedienst werden während der Indizierungsausführung bei der 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, Skills oder Dokumenten.

Problembehandlung

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

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