Indexer des données dans Azure Cosmos DB for MongoDB pour les requêtes dans la Recherche Azure AI

Article
02/28/2024

Important

La prise en charge de l’API MongoDB est actuellement en préversion publique dans le cadre de conditions d’utilisation supplémentaires. Il n’existe actuellement aucune prise en charge du Kit de développement logiciel (SDK).

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu à partir d’Azure Cosmos DB for MongoDB et le rend utilisable dans une requête Recherche Azure AI.

Cet article est un complément de Créer un indexeur avec des informations propres à Cosmos DB. Il utilise les API REST pour illustrer un workflow en trois parties commun à tous les indexeurs : créer une source de données, créer un index, créer un indexeur. L’extraction de données se produit quand vous envoyez la demande de création d’un indexeur.

Étant donné que la terminologie peut être déroutante, il est important de noter que l’indexation Azure Cosmos DB et l’indexation Recherche Azure AI sont des opérations différentes. L’indexation dans la recherche Azure AI crée et charge un index de recherche sur votre service de recherche.

Prérequis

Inscrivez-vous à la préversion pour donner votre avis sur le scénario. Vous pouvez accéder automatiquement à la fonctionnalité après l’envoi du formulaire.
Un compte, une base de données, une collection et des documents Azure Cosmos DB. Utilisez la même région pour Recherche Azure AI et Azure Cosmos DB afin de réduire la latence et d’éviter les frais de bande passante.
Une stratégie d’indexation automatique sur la collection Azure Cosmos DB, définie sur Cohérente. Il s’agit de la configuration par défaut. L’indexation différée n’est pas recommandée et peut entraîner des données manquantes.
Autorisations de lecture. Une chaîne de connexion « accès total » comprend une clé qui accorde l’accès au contenu, mais si vous utilisez des rôles Azure, vérifiez que l’identité managée du service de recherche a les autorisations du rôle Lecteur de compte Azure Cosmos DB.
Un client REST pour créer la source de données, l’index et l’indexeur.

Limites

Voici les limitations de cette fonctionnalité :

Les requêtes personnalisées ne sont pas prises en charge pour spécifier le jeu de données.
Le nom de colonne _ts est un mot réservé. Si vous avez besoin de ce champ, envisagez d’autres solutions pour remplir un index.
L’attribut MongoDB $ref est un mot réservé. Si vous en avez besoin dans votre collection MongoDB, envisagez d’autres solutions pour remplir un index.

En guise d’alternative à ce connecteur, si votre scénario présente l’une de ces exigences, vous pouvez utiliser l’API/SDK Push, ou Azure Data Factory avec un index Recherche Azure AI comme récepteur.

Définir la source de données

La définition de la source de données spécifie les données à indexer, les informations d’identification et les stratégies permettant d’identifier les changements de données. Une source de données est définie comme une ressource indépendante de manière à pouvoir être utilisée par plusieurs indexeurs.

Pour cet appel, spécifiez une préversion de l’API REST (2020-06-30-Preview ou 2021-04-30-Preview) pour créer une source de données qui se connecte avec l’API MongoDB.

Créez ou mettez à jour une source de données pour régler sa définition :

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-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
}

Définissez « type » sur "cosmosdb" (obligatoire).
Définissez « credentials » sur une chaîne de connexion. La section suivante décrit les formats pris en charge.
Définissez « container » sur la collection. La propriété « name » est obligatoire et spécifie l’ID de la collection de bases de données à indexer. Pour Azure Cosmos DB pour MongoDB, la « requête » n’est pas prise en charge.
Définissez « dataChangeDetectionPolicy » si les données sont volatiles et que vous voulez que l’indexeur récupère uniquement les éléments nouveaux et mis à jour pendant les exécutions suivantes.
Définissez « dataDeletionDetectionPolicy » si vous souhaitez supprimer les documents de recherche d’un index de recherche lorsque l’élément source est supprimé.

Informations d’identification et chaînes de connexion prises en charge

Les indexeurs peuvent se connecter à une collection à l’aide des connexions suivantes. Pour les connexions qui ciblent l’API MongoDB, ajoutez « ApiKind » dans la chaîne de connexion.

Évitez les numéros de port dans l’URL du point de terminaison. Si vous ajoutez le numéro de port, la connexion échoue.

Chaîne de connexion d’accès complet
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }`
Vous pouvez obtenir la clé d’authentification Azure Cosmos DB à partir de la page du compte Cosmos DB dans le portail Azure en sélectionnant Chaîne de connexion dans le volet de navigation de gauche. Veillez à copier le mot de passe principal et à remplacer la valeur de clé d’authentification Cosmos DB par celle-ci.

Chaîne de connexion d’identité managée

Chaîne de connexion d’identité managée
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }`
Cette chaîne de connexion ne nécessite pas de clé de compte, mais vous devez avoir préalablement configuré un service de recherche pour vous connecter en utilisant une identité managée et créé une attribution de rôle qui accorde les autorisations du rôle Lecteur de compte Cosmos DB. Consultez Configuration d’une connexion d’indexeur à une base de données Azure Cosmos DB avec une identité managée pour plus d’informations.

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

Cette chaîne de connexion ne nécessite pas de clé de compte, mais vous devez avoir préalablement configuré un service de recherche pour vous connecter en utilisant une identité managée et créé une attribution de rôle qui accorde les autorisations du rôle Lecteur de compte Cosmos DB. Consultez Configuration d’une connexion d’indexeur à une base de données Azure Cosmos DB avec une identité managée pour plus d’informations.

Ajouter des champs de recherche à un index

Dans un index de recherche, ajoutez des champs pour accepter les documents JSON source ou la sortie de votre projection de requête personnalisée. Vérifiez que le schéma d’index de recherche est compatible avec vos données sources. Pour le contenu dans Azure Cosmos DB, votre schéma d’index de recherche doit correspondre aux éléments Azure Cosmos DB de votre source de données.

Créez ou mettez à jour un index pour définir les champs de recherche qui stockeront les données :

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
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
    }]
}

Créez un champ de clé de document ("key": true). Pour un index de recherche basé sur une collection MongoDB, la clé de document peut être « doc_id », « rid » ou un autre champ de chaîne qui contient des valeurs uniques. Tant que les noms de champs et les types de données sont identiques des deux côtés, aucun mappage de champs n’est requis.
- « doc_id » représente « _id » pour l’identificateur d’objet. Si vous spécifiez un champ « doc_id » dans l’index, l’indexeur le remplit avec les valeurs de l’identificateur d’objet.
- « rid » est une propriété système dans Azure Cosmos DB. Si vous spécifiez un champ « rid » dans l’index, l’indexeur le remplit avec la valeur codée en base64 de la propriété « rid ».
- Pour tout autre champ, votre champ de recherche doit avoir le même nom que celui défini dans la collection.
Créez des champs supplémentaires pour obtenir plus de contenu pouvant faire l’objet de recherche. Pour plus d’informations, consultez Créer un index.

Mappage des types de données

Type de données JSON	Types de champs Recherche Azure AI
Bool	Edm.Boolean, Edm.String
Nombres qui ressemblent à des nombres entiers	Edm.Int32, Edm.Int64, Edm.String
Nombres qui ressemblent à des nombres avec points flottants	Edm.Double, Edm.String
Chaîne	Edm.String
Tableaux de types primitifs, par exemple ["a", "b", "c"]	Collection(Edm.String)
Chaînes qui ressemblent à des dates	Edm.DateTimeOffset, Edm.String
Objets GeoJSON, par exemple { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
Autres objets JSON	S/O

Configurer et exécuter l’indexeur Azure Cosmos DB for MongoDB

Une fois l’index et la source de données créés, vous êtes prêt à créer l’indexeur. La configuration de l’indexeur spécifie les entrées, les paramètres et les propriétés qui contrôlent les comportements d’exécution.

Créez ou mettez à jour un indexeur en lui attribuant un nom, et en référençant la source de données et l’index cible :

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
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
}

Spécifiez les mappages de champs s’il existe des différences dans le nom ou le type du champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.
Pour plus d’informations sur les autres propriétés, consultez Créer un indexeur.

Un indexeur s’exécute automatiquement quand il est créé. Vous pouvez l’éviter en définissant « disabled » sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le dans une planification.

Vérifier l’état de l’indexeur

Pour monitorer l’état de l’indexeur et l’historique d’exécution, envoyez une demande Obtenir l’état de l’indexeur :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

La réponse comprend l’état et le nombre d’éléments traités. Le résultat doit ressembler à l’exemple suivant :

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

L’historique d’exécution contient jusqu’à 50 exécutions les plus récentes, classées par ordre chronologique inversé, la dernière exécution apparaissant en premier.

Indexation des documents nouveaux et modifiés

Dès qu’un indexeur a entièrement rempli un index de recherche, vous pouvez définir que les exécutions suivantes de l’indexeur indexent de manière incrémentielle uniquement les documents nouveaux et modifiés dans votre base de données.

Pour activer l’indexation incrémentielle, définissez la propriété « dataChangeDetectionPolicy » dans la définition de votre source de données. Cette propriété indique à l’indexeur le mécanisme de suivi des changements utilisé sur vos données.

Pour les indexeurs Azure Cosmos DB, la seule stratégie prise en charge est HighWaterMarkChangeDetectionPolicy utilisant la propriété _ts (horodateur) fournie par Azure Cosmos DB.

L’exemple suivant montre une définition de source de données avec une stratégie de détection des changements :

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

Indexation des documents supprimés

Lorsque des lignes sont supprimées de la collection, vous devez normalement supprimer ces lignes de l'index de recherche. L'objectif d'une stratégie de détection des suppressions de données est d'identifier efficacement les données supprimées. La seule stratégie actuellement prise en charge est la stratégie Soft Delete (où la suppression est signalée par un indicateur quelconque), spécifiée dans la définition de source de données de la façon suivante :

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

Si vous utilisez une requête personnalisée, vérifiez que la propriété référencée par softDeleteColumnName est projetée par la requête.

L'exemple suivant crée une source de données avec des conseils pour une stratégie de suppression en douceur :

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
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"
    }
}

Étapes suivantes

Vous pouvez maintenant contrôler comment exécuter l’indexeur, monitorer l’état ou planifier l’exécution de l’indexeur. Les articles suivants s’appliquent aux indexeurs qui tirent du contenu d’Azure Cosmos DB :

Share via