Indizieren von Daten aus Azure Cosmos DB für MongoDB für Abfragen in der Azure KI-Suche

Artikel
09/03/2024

Wichtig

Die Unterstützung für MongoDB-APIs befindet sich derzeit in der öffentlichen Vorschauphase, und es gelten die zusätzlichen Nutzungsbedingungen. Derzeit gibt es keine SDK-Unterstützung.

In diesem Artikel erfahren Sie, wie Sie einen Indexer konfigurieren, der Inhalte aus Azure Cosmos DB für MongoDB importiert und sie in Azure AI Search durchsuchbar macht.

Dieser Artikel ergänzt den Artikel Erstellen von Indexern mit Informationen, die Cosmos DB-spezifisch sind. Er verwendet die REST-APIs, um einen dreiteiligen Workflow zu veranschaulichen, der allen Indexern gemeinsam ist: Erstellen einer Datenquelle, Erstellen eines Indexes und Erstellen eines Indexers. Die Datenextraktion erfolgt, wenn Sie die Anforderung für die Indexererstellung übermitteln.

Da die Terminologie verwirrend sein kann, sei darauf hingewiesen, dass Azure Cosmos DB-Indizierung und Azure AI Search-Indizierung unterschiedliche Vorgänge sind. Die Indexierung in Azure AI Search erstellt und lädt einen Suchindex auf Ihren Suchdienst.

Voraussetzungen

Registrieren Sie sich für die Preview, um Feedback zum Szenario zu geben. Sie können das Feature automatisch nach dem Absenden des Formulars aufrufen.
Ein Azure Cosmos DB-Konto, eine Datenbank, eine Sammlung und Dokumente. Verwenden Sie dieselbe Region für Azure AI Search und Azure Cosmos DB, um die Latenz zu verringern und Bandbreitengebühren zu vermeiden.
Eine auf Konsistent festgelegte automatische Indizierungsrichtlinie für die Azure Cosmos DB-Sammlung. Dies ist die Standardkonfiguration. Verzögerte Indizierung wird nicht empfohlen und kann zu fehlenden Daten führen.
Leseberechtigungen. Eine Vollzugriff-Verbindungszeichenfolge enthält einen Schlüssel, der Zugriff auf den Inhalt gewährt. Wenn Sie jedoch Azure-Rollen verwenden, stellen Sie sicher, dass die verwaltete Identität des Suchdiensts über die Berechtigungen der Cosmos DB-Rolle „Kontoleser“ verfügt.
Ein REST-Client, um die Datenquelle, den Index und den Indexer zu erstellen.

Begrenzungen

Im Folgenden finden Sie Einschränkungen für dieses Feature:

Benutzerdefinierte Abfragen werden nicht unterstützt, um das Dataset anzugeben.
In diesem Feature ist der Spaltenname _ts ein reserviertes Wort. Wenn Sie dieses Feld benötigen, sollten Sie alternative Lösungen zum Auffüllen eines Indexes berücksichtigen.
Das MongoDB-Attribut $ref ist ein reserviertes Wort. Wenn Sie dies in Ihrer MongoDB-Sammlung benötigen, sollten Sie alternative Lösungen für das Auffüllen eines Index in Betracht ziehen.

Als Alternative zu diesem Konnektor könnten Sie, wenn Ihr Szenario eine dieser Anforderungen erfüllt, die Push API/SDK verwenden oder Azure Data Factory mit einem Azure AI Search Index als Senke in Betracht ziehen.

Definieren der Datenquelle

Die Datenquellendefinition gibt die zu indizierenden Daten, die Anmeldeinformationen und die Richtlinien für die Identifizierung von Datenänderungen an. Eine Datenquelle wird als unabhängige Ressource definiert, sodass sie von mehreren Indexern verwendet werden kann.

Geben Sie für diesen Aufruf eine Vorschau-REST-API-Version an. Sie können 2020-06-30-preview oder höher verwenden, um eine Datenquelle zu erstellen, die eine Verbindung über die MongoDB-API herstellt. Wir empfehlen die neueste Vorschau-REST-API.

Erstellen oder aktualisieren Sie eine Datenquelle, um ihre Definition festzulegen:

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
  "name": "[my-cosmosdb-mongodb-ds]",
  "type": "cosmosdb",
  "credentials": {
    "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
  },
  "container": {
    "name": "[cosmos-db-collection]",
    "query": null
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null,
  "identity": null
}

Legen Sie "type" auf "cosmosdb" fest (erforderlich).
Legen Sie „credentials“ auf eine Verbindungszeichenfolge fest. Im nächsten Abschnitt werden die unterstützten Formate beschrieben.
Legen Sie „container“ auf die Auflistung fest. Die Eigenschaft „name“ ist erforderlich und gibt die ID der zu indizierenden Datenbanksammlung an. Für Azure Cosmos DB for MongoDB wird „query“ nicht unterstützt.
Legen Sie „dataChangeDetectionPolicy“ fest, wenn Daten flüchtig sind und der Indexer bei nachfolgenden Läufen immer nur die neuen und aktualisierten Elemente erfassen soll.
Legen Sie „dataDeletionDetectionPolicy“ fest, wenn Sie Suchdokumente aus einem Suchindex entfernen möchten, wenn das Quellelement gelöscht wird.

Unterstützte Anmeldeinformationen und Verbindungszeichenfolgen

Indexer können mithilfe der folgenden Verbindungen eine Verbindung mit einer Sammlung herstellen. Für Verbindungen, die auf die MongoDB-API abzielen, müssen Sie „ApiKind“ in die Verbindungszeichenfolge einschließen.

Vermeiden Sie Portnummern in der Endpunkt-URL. Wenn Sie die Portnummer einschließen, tritt beim Herstellen der Verbindung ein Fehler auf.

„Vollzugriff“-Verbindungszeichenfolge
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }`
Sie können den Cosmos DB-Authentifizierungsschlüssel von der Azure Cosmos DB-Kontoseite im Azure-Portal abrufen, indem Sie im linken Navigationsbereich die Option Verbindungszeichenfolge auswählen. Stellen Sie sicher, dass Sie das primäre Kennwort kopieren und den Wert Cosmos DB-Authentifizierungsschlüssel dadurch ersetzen.

Verbindungszeichenfolge für verwaltete Identitäten

Verbindungszeichenfolge für verwaltete Identitäten
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }`
Diese Verbindungszeichenfolge erfordert keinen Kontoschlüssel, aber Sie müssen zuvor einen Suchdienst für die Verbindungsherstellung mithilfe einer verwalteten Identität konfiguriert und eine Rollenzuweisung erstellt haben, die Berechtigungen der Cosmos DB-Rolle „Kontoleser“ gewährt. Weitere Informationen finden Sie unter Einrichten einer Indexerverbindung mit einer Azure Cosmos DB-Datenbank mithilfe einer verwalteten Identität.

{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }

Diese Verbindungszeichenfolge erfordert keinen Kontoschlüssel, aber Sie müssen zuvor einen Suchdienst für die Verbindungsherstellung mithilfe einer verwalteten Identität konfiguriert und eine Rollenzuweisung erstellt haben, die Berechtigungen der Cosmos DB-Rolle „Kontoleser“ gewährt. Weitere Informationen finden Sie unter Einrichten einer Indexerverbindung mit einer Azure Cosmos DB-Datenbank mithilfe einer verwalteten Identität.

Hinzufügen von Suchfeldern zu einem Index

Fügen Sie in einem Suchindex Felder hinzu, um die JSON-Quelldokumente oder die Ausgabe Ihrer benutzerdefinierten Abfrageprojektion zu akzeptieren. Stellen Sie sicher, dass das Suchindexschema mit den Quelldaten kompatibel ist. Für Inhalte in Azure Cosmos DB muss Ihr Suchindexschema den Azure Cosmos DB-Elementen in Ihrer Datenquelle entsprechen.

Erstellen oder aktualisieren Sie einen Index, um Suchfelder zu definieren, in denen Daten gespeichert werden:

POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "mysearchindex",
    "fields": [{
        "name": "doc_id",
        "type": "Edm.String",
        "key": true,
        "retrievable": true,
        "searchable": false
    }, {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }]
}

Erstellen Sie ein Dokumentschlüsselfeld („key“: true). Bei einem Suchindex basierend auf einer MongoDB-Auflistung kann der Dokumentschlüssel „doc_id“, „rid“ oder ein anderes Zeichenfolgenfeld sein, das eindeutige Werte enthält. Solange Feldnamen und Datentypen auf beiden Seiten identisch sind, sind keine Feldzuordnungen erforderlich.
- „doc_id“ stellt „_id“ für den Objektbezeichner dar. Wenn Sie ein Feld „doc_id“ im Index angeben, füllt der Indexer es mit den Werten des Objektbezeichners auf.
- „rid“ ist eine Systemeigenschaft in Azure Cosmos DB. Wenn Sie ein Feld „rid“ im Index angeben, füllt der Indexer es mit dem base64-codierten Wert der „rid“-Eigenschaft auf.
- Für jedes andere Feld sollte Ihr Suchfeld denselben Namen wie in der Auflistung definiert haben.
Erstellen Sie zusätzliche Felder für mehr durchsuchbare Inhalte. Weitere Informationen finden Sie unter Erstellen eines Suchindex in Azure Cognitive Search.

Abbildung von Datentypen

JSON-Datentyp	Azure AI Search Feldtypen
Bool	Edm.Boolean, Edm.String
Zahlen, die wie Ganzzahlen aussehen	Edm.Int32, Edm.Int64, Edm.String
Zahlen, die wie Gleitkommas aussehen	Edm.Double, Edm.String
String	Edm.String
Arrays primitiver Typen, z. B ["a", "b", "c"]	Collection(Edm.String)
Zeichenfolgen, die wie Datumsangaben aussehen	Edm.DateTimeOffset, Edm.String
GeoJSON-Objekte z. B. { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
Andere JSON-Objekte	N/V

Konfigurieren und Ausführen des Azure Cosmos DB for MongoDB-Indexers

Nach der Erstellung von Index und Datenquelle können Sie den Indexer erstellen. Die Indexerkonfiguration gibt die Eingaben, Parameter und Eigenschaften an, die das Laufzeitverhalten steuern.

Erstellen oder aktualisieren Sie den Indexer, indem Sie ihm einen Namen geben und einen Verweis auf die Datenquelle und den Zielindex hinzufügen:

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-mongodb-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

Geben Sie Feldzuordnungen an, wenn es Unterschiede beim Feldnamen oder -typ gibt, oder wenn Sie mehrere Versionen eines Quellfelds im Suchindex benötigen.
Weitere Informationen zu anderen Eigenschaften finden Sie unter Erstellen von Indexern in Azure Cognitive Search.

Ein Indexer wird automatisch ausgeführt, wenn er erstellt wird. Sie können dies verhindern, indem Sie „disabled“ (Deaktiviert) auf „true“ festlegen. Um die Ausführung des Indexers zu steuern, führen Sie einen Indexer nach Bedarf aus, oder legen Sie für ihn einen Zeitplan fest.

Überprüfen des Indexerstatus

Um den Indexerstatus und den Ausführungsverlauf zu überwachen, senden Sie eine Anforderung zum Abrufen des Indexerstatus:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

Die Antwort enthält den Status und die Anzahl der verarbeiteten Elemente. Sie sollte in etwa wie das folgende Beispiel aussehen:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Der Ausführungsverlauf enthält bis zu 50 der zuletzt abgeschlossenen Ausführungen. Diese sind in umgekehrter chronologischer Reihenfolge sortiert, sodass die neueste Ausführung als Erstes aufgelistet wird.

Indizieren neuer und geänderter Dokumente

Wenn ein Indexer einen Suchindex vollständig aufgefüllt hat, sollen bei nachfolgenden Indexerausführungen möglicherweise nur die neuen und geänderten Dokumente in Ihrer Datenbank inkrementell indiziert werden.

Um die inkrementelle Indizierung zu aktivieren, legen Sie die Eigenschaft „dataChangeDetectionPolicy“ in Ihrer Datenquellendefinition fest. Diese Eigenschaft teilt dem Indexer mit, welcher Mechanismus für die Änderungsnachverfolgung für Ihre Daten verwendet wird.

Für Azure Cosmos DB-Indexer wird nur die Richtlinie HighWaterMarkChangeDetectionPolicy unterstützt, bei der die von Azure Cosmos DB bereitgestellte Eigenschaft _ts (Zeitstempel) verwendet wird.

Das folgende Beispiel zeigt eine Datenquellendefinition mit einer Änderungserkennungsrichtlinie:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Indizieren von gelöschten Dokumenten

Wenn Zeilen aus der Quelltabelle gelöscht werden, möchten Sie diese Zeilen in der Regel auch aus dem Suchindex löschen. Die Richtlinie zum Erkennen von Datenlöschungen dient einer effizienten Identifizierung gelöschter Datenelemente. Zurzeit ist Soft Delete die einzige unterstützte Richtlinie (die Löschung wird durch ein bestimmtes Kennzeichen markiert), die in der Datenquellendefinition folgendermaßen festgelegt wird:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Wenn Sie eine benutzerdefinierte Abfrage verwenden, stellen Sie sicher, dass die Eigenschaft, auf die softDeleteColumnName verweist, von der Abfrage projiziert wird.

Im folgenden Beispiel wird eine Datenquelle mit einer Richtlinie zum vorläufigen Löschen erstellt:

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": ["my-cosmosdb-mongodb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Nächste Schritte

Sie können nun kontrollieren, wie Sie den Indexer ausführen, den Status überwachen oder die Ausführung des Indexers planen. Die folgenden Artikel gelten für Indexer, die Inhalte mithilfe von Pull Requests aus Azure Cosmos DB übertragen:

Freigeben über