Indexer les données de Azure Cosmos DB pour MongoDB pour les requêtes dans Recherche Azure AI (préversion)

Le Azure Cosmos DB pour l’indexeur MongoDB (préversion) importe du contenu à partir de Azure Cosmos DB pour MongoDB et le rend accessible à la recherche dans Recherche Azure AI.

Cet article complète la création d’un indexeur avec des informations spécifiques à Cosmos DB. Il utilise les API REST pour illustrer un workflow en trois parties commune à tous les indexeurs : créer une source de données, créer un indexeur, créer un indexeur. L’extraction de données se produit lorsque vous envoyez la demande Create Indexer.

Étant donné que la terminologie peut prêter à confusion, 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 Recherche Azure AI crée et charge un index de recherche sur votre service de recherche.

Conditions préalables

• Remplissez le formulaire d’inscription à l’aperçu de l’indexeur. L’inscription est automatiquement approuvée.

• Un compte Azure Cosmos DB, une base de données, une collection et des documents. Utilisez la même région pour les Recherche Azure AI et les Azure Cosmos DB pour une latence inférieure et pour éviter les frais de bande passante.

• Stratégie d’indexation automatique sur la collection Azure Cosmos DB, définie sur Consistent. Ce paramètre est 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.

Limitations

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 _ts de colonne est un mot réservé. Si vous avez besoin de ce champ, envisagez d’autres solutions pour remplir un index.

• L’attribut $ref MongoDB 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 conditions requises, vous pouvez utiliser l’API Push API/SDK ou envisager 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 pour identifier les modifications apportées aux données. Une source de données est définie comme une ressource indépendante afin qu’elle puisse être utilisée par plusieurs indexeurs.

Pour cet appel, spécifiez une version préliminaire de l’API REST pour créer une source de données qui se connecte via l’API MongoDB. Vous pouvez utiliser 2020-06-30-preview ou une version ultérieure. Nous vous recommandons la dernière API REST en préversion.

1. Créez ou mettez à jour une source de données pour définir sa définition :

   POST https://[service name].search.windows.net/datasources?api-version=2026-08-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]"
     },
     "dataChangeDetectionPolicy": {
       "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "highWaterMarkColumnName": "_ts"
     },
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
   }
   

2. Définissez « type » sur "cosmosdb" (obligatoire).

3. Définissez « credentials » sur un chaîne de connexion. La section suivante décrit les formats pris en charge.

4. Définissez « conteneur » dans la collection. La propriété « name » est requise 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.

5. Définissez « dataChangeDetectionPolicy » si les données sont volatiles et que vous souhaitez que l’indexeur récupère uniquement les éléments nouveaux et mis à jour lors des exécutions suivantes.

6. Définissez « dataDeletionDetectionPolicy » si vous souhaitez supprimer des documents de recherche d’un index de recherche lorsque l’élément source est supprimé.

Identifiants 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, veillez à inclure « ApiKind » dans le 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.

Ajouter des champs de recherche à un index

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

1. Créez ou mettez à jour un index pour définir les champs de recherche dans lesquels sont stockées les données :

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

2. Créez un champ de clé de document (« clé » : 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 sur les deux côtés, aucun mappage de champ 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 de « 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.

3. Créez des champs supplémentaires pour plus de contenu pouvant faire l’objet d’une recherche. Pour plus d’informations, consultez Créer un index .

Types de données de mappage

Configurer et exécuter le Azure Cosmos DB pour l’indexeur 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 de temps d’exécution.

1. Créez ou mettez à jour un indexeur en lui donnant 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=2026-08-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
   }
   

2. Spécifiez des mappages de champs s’il existe des différences dans le nom ou le type de champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.

3. Pour plus d’informations sur d’autres propriétés, consultez Créer un indexeur .

Un indexeur s’exécute automatiquement lors de sa création. Vous pouvez empêcher cela en définissant « désactivé » sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le selon une planification.

Vérifier l’état de l’indexeur

Pour surveiller l'état de l'indexeur et l'historique d'exécution, envoyez une requête Get Indexer Status :

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

La réponse inclut l’état et le nombre d’éléments traités. Il 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 des dernières exécutions terminées, triées dans l’ordre chronologique inverse afin que la dernière exécution soit effectuée en premier.

Indexation de documents nouveaux et modifiés

Une fois qu’un indexeur a rempli entièrement un index de recherche, vous pouvez souhaiter que l’indexeur ultérieur s’exécute de manière incrémentielle pour indexer 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 votre définition de source de données. Cette propriété indique à l’indexeur quel mécanisme de suivi des modifications est utilisé sur vos données.

Pour les indexeurs Azure Cosmos DB, la seule stratégie prise en charge est la HighWaterMarkChangeDetectionPolicy à l’aide de la propriété _ts (timestamp) 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 modifications :

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

Indexation de documents supprimés

Lorsque des lignes sont supprimées de la collection, vous souhaitez normalement supprimer ces lignes de l’index de recherche. L’objectif d’une stratégie de détection de suppression de données consiste à identifier efficacement les éléments de données supprimés. Actuellement, la seule politique prise en charge est la politique Soft Delete (la suppression est marquée par un indicateur quelconque), qui est spécifiée dans la définition de la source de données comme suit :

"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 bien projetée par la requête.

L’exemple suivant crée une source de données avec une stratégie de suppression réversible :

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

Étapes suivantes

Vous pouvez maintenant contrôler la façon dont vous exécutez l’indexeur, surveillez l’état ou planifiez l’exécution de l’indexeur. Les articles suivants s’appliquent aux indexeurs qui extrayent du contenu à partir de Azure Cosmos DB :

• Configurer une connexion d’indexeur à une base de données Azure Cosmos DB à l’aide d’une identité managée
• Indexer des jeux de données volumineux
• Accès de l'indexeur au contenu protégé par les fonctionnalités de sécurité réseau d'Azure