Indexer des données à partir d’Azure Cosmos DB for Apache Gremlin pour les requêtes dans Recherche Azure AI
Important
L’indexeur Azure Cosmos DB for Apache Gremlin 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 Apache Gremlin et le rend accessible dans 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, un conteneur et des éléments Azure Cosmos DB. Utilisez la même région pour la Recherche Azure AI et Azure Cosmos DB pour réduire la latence et é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.
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 version d’API REST en préversion pour créer une source de données qui se connecte via Azure Cosmos DB for Apache Gremlin. Vous pouvez utiliser la version 2021-04-01-preview ou ultérieure. Nous vous recommandons l’API dans la préversion la plus récente.
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=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "[my-cosmosdb-gremlin-ds]", "type": "cosmosdb", "credentials": { "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;" }, "container": { "name": "[cosmos-db-collection]", "query": "g.V()" }, "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 du graphique.
La propriété « query » est facultative. Par défaut, l’indexeur Recherche Azure AI pour Azure Cosmos DB for Apache Gremlin rend chaque vertex de votre graphique un document dans l’index. Les arêtes seront ignorées. La valeur par défaut de la requête est
g.V()
. Vous pouvez également définir la requête pour qu’elle indexe uniquement les arêtes. Pour indexer les arêtes, définissez la requête surg.E()
.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. La progression incrémentielle est activée par défaut en utilisant
_ts
comme colonne de limite supérieure.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 Azure Cosmos DB for Apache Gremlin, veillez à inclure « 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 chaîne de connexion à partir de la page du compte Azure Cosmos DB dans le portail Azure en sélectionnant Clés dans le volet de navigation de gauche. Veillez à sélectionner une chaîne de connexion complète et pas seulement une clé. |
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. |
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. Assurez-vous que le schéma d’index de recherche est compatible avec votre graphique. 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=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "mysearchindex", "fields": [ { "name": "rid", "type": "Edm.String", "facetable": false, "filterable": false, "key": true, "retrievable": true, "searchable": true, "sortable": false, "analyzer": "standard.lucene", "indexAnalyzer": null, "searchAnalyzer": null, "synonymMaps": [], "fields": [] },{ }, { "name": "label", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": false, "facetable": false, "key": false, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": "standard.lucene", "synonymMaps": [] }] }
Créez un champ de clé de document ("key": true). Pour les collections partitionnées, la clé de document par défaut est la propriété d’
_rid
Azure Cosmos DB, que la recherche Azure AI renomme automatiquement enrid
, car les noms de champs ne peuvent pas commencer par un trait de soulignement. En outre, les valeurs_rid
Azure Cosmos DB contiennent des caractères non valides dans les clés de recherche Azure AI. Par conséquent, les valeurs_rid
sont codées en Base64.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 | N/A |
Configurer et exécuter l’indexeur Azure Cosmos DB
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=2024-05-01-preview Content-Type: application/json api-key: [search service admin key] { "name" : "[my-cosmosdb-indexer]", "dataSourceName" : "[my-cosmosdb-gremlin-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=2024-05-01-preview
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 les données d’un graphique sont supprimées, vous pouvez également supprimer le document correspondant de l’index de recherche. L’objectif d’une stratégie de détection de la suppression des données est d’identifier efficacement les éléments de données supprimés et de supprimer le document complet de l’index. La stratégie de détection de la suppression des données n’est pas destinée à supprimer des documents partiels. 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"
}
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=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
"name": "[my-cosmosdb-gremlin-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
},
"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"
}
}
Même si vous activez la stratégie de détection de suppression, la suppression de champs complexes (Edm.ComplexType
) de l’index n’est pas prise en charge. Cette stratégie exige que la colonne « active » dans la base de données Gremlin soit de type entier, chaîne ou booléen.
Mappage de données de graphique à des champs dans un index de recherche
L’indexeur Azure Cosmos DB for Apache Gremlin mappe automatiquement quelques éléments de données de graphique pour vous :
L’indexeur mappera
_rid
à un champrid
dans l’index, s’il existe, et l’encodera en Base64.L’indexeur mappera
_id
à un champid
dans l’index, s’il existe.Lorsque vous interrogez votre base de données Azure Cosmos DB à l’aide d’Azure Cosmos DB for Apache Gremlin, vous pouvez remarquer que la sortie JSON de chaque propriété comporte un
id
et unevalue
. L’indexeur mappe automatiquement les propriétésvalue
dans un champ de votre index de recherche portant le même nom que la propriété, le cas échéant. Dans l’exemple suivant, 450 est mappé à un champpages
dans l’index de recherche.
{
"id": "Cookbook",
"label": "book",
"type": "vertex",
"properties": {
"pages": [
{
"id": "48cf6285-a145-42c8-a0aa-d39079277b71",
"value": "450"
}
]
}
}
Il se peut que vous deviez utiliser des mappages de champs de sortie afin de mapper la sortie de votre requête aux champs de votre index. Vous souhaiterez probablement utiliser des mappages de champs de sortie plutôt que des mappages de champs, car la requête personnalisée contiendra probablement des données complexes.
Par exemple, supposons que votre requête génère la sortie suivante :
[
{
"vertex": {
"id": "Cookbook",
"label": "book",
"type": "vertex",
"properties": {
"pages": [
{
"id": "48cf6085-a211-42d8-a8ea-d38642987a71",
"value": "450"
}
],
}
},
"written_by": [
{
"yearStarted": "2017"
}
]
}
]
Si vous souhaitez mapper la valeur de pages
dans le JSON ci-dessus à un champ totalpages
de votre index, vous pouvez ajouter le mappage de champs de sortie suivant à votre définition d’indexeur :
... // rest of indexer definition
"outputFieldMappings": [
{
"sourceFieldName": "/document/vertex/pages",
"targetFieldName": "totalpages"
}
]
Notez que le mappage de champs de sortie commence par /document
et n’inclut pas de référence à la clé de propriété dans le JSON. Cela s’explique par le fait que l’indexeur place chaque document sous le nœud /document
lors de l’ingestion des données du graphique. L’indexeur vous permet également de référencer automatiquement la valeur de pages
en référençant simplement pages
au lieu de devoir référencer le premier objet dans le tableau de pages
.
Étapes suivantes
Pour en savoir plus sur Azure Cosmos DB for Apache Gremlin, consultez la Présentation d’Azure Cosmos DB : Azure Cosmos DB for Apache Gremlin.
Pour plus d’informations sur les scénarios et les tarifs de la Recherche Azure AI, consultez la page du service recherche sur azure.microsoft.com.
Pour en savoir plus sur la configuration du réseau pour les indexeurs, consultez Accès de l’indexeur au contenu protégé par les fonctionnalités de sécurité réseau Azure.
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de l’année 2024, nous abandonnerons progressivement le mécanisme de retour d’information GitHub Issues pour le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez :Soumettre et afficher des commentaires pour