Inscrire et mettre à jour le schéma pour la connexion Graph Microsoft
Le schéma de connexion détermine la façon dont votre contenu est utilisé dans différentes expériences Microsoft Graph. Le schéma est une liste plate de toutes les propriétés que vous envisagez d’ajouter à la connexion, ainsi que les attributs, les étiquettes et les alias. Vous devez inscrire le schéma avant d’ajouter des éléments à la connexion.
Exemple de schéma
Le tableau suivant représente un exemple de schéma possible pour un connecteur système de ticket de travail.
Propriété | Type | Utilisable dans une recherche | Utilisable dans une requête | Affichable dans les résultats d’une recherche | Utilisable dans une recherche approfondie | Correspondance exacte requise | Étiquettes | Alias |
---|---|---|---|---|---|---|---|---|
ticketId | String | ✔️ | ✔️ | ID | ||||
title | Chaîne | ✔️ | ✔️ | ✔️ | titre | |||
createdBy | String | ✔️ | ✔️ | createdBy | Créateur | |||
assignedTo | Chaîne | ✔️ | ✔️ | |||||
lastEditedDate | Date/heure | ✔️ | ✔️ | ✔️ | lastModifiedDateTime | editedDate | ||
lastEditedBy | String | ✔️ | ✔️ | ✔️ | lastModifiedBy | modifié | ||
workItemType | String | ✔️ | ✔️ | ticketType | ||||
priorité | Int64 | ✔️ | ||||||
étiquettes | StringCollection | ✔️ | ✔️ | ✔️ | ✔️ | |||
status | Chaîne | ✔️ | ✔️ | |||||
url | Chaîne | url | ||||||
résolu | Booléen | ✔️ | ✔️ |
Attributs de propriété
Utilisable dans une recherche
Si une propriété peut faire l’objet d’une recherche, sa valeur est ajoutée à l’index de texte complet. Lorsqu’un utilisateur effectue une recherche, nous renvoyons les résultats s’il y a une correspondance de recherche dans l’un des champs pouvant faire l’objet d’une recherche ou son contenu.
Recherche de « conception » affichant les résultats pour les résultats par rapport à la propriété ( title
) et au contenu.
Utilisable dans une requête
Si vous interrogez une propriété, vous pouvez effectuer une requête sur celle-ci à l’aide du langage de requête de connaissances (KQL). KQL se compose d’un ou de plusieurs mots clés de texte libre (mots ou expressions) ou de restrictions de propriété. Le nom de la propriété doit être inclus dans la requête, c'est-à-dire soit être précisé dans la requête même, soit être intégré par programme dans la requête. Vous pouvez utiliser la correspondance des préfixes avec l’opérateur générique (*).
Remarque
La correspondance des suffixes n’est pas prise en charge.
Recherche de « search ba* » affichant les résultats correspondant à ce préfixe.
Une recherche pour « tags:design » permet de réduire les résultats aux articles dont où « design » figure dans la tags
propriété.
Affichable dans les résultats d’une recherche
Si une propriété est récupérable, sa valeur peut être renvoyée dans les résultats de la recherche. Les propriétés que vous souhaitez ajouter dans le modèle d’affichage ou qui doivent être renvoyées à partir de la requête et être pertinentes dans les résultats de la recherche doivent pouvoir être récupérées. Le marquage de propriétés volumineuses ou trop nombreuses comme récupérables augmente la latence de recherche. Soyez sélectif et choisissez les propriétés appropriées.
Ensemble de propriétés récupérables (title
et lastEditedBy
) rendues par conséquent.
Utilisable dans une recherche approfondie
Si une propriété est utilisable dans une recherche approfondie, un administrateur peut la configurer comme filtre personnalisé dans la page résultats de la recherche Microsoft. Une refinable
propriété ne peut pas être searchable
.
Affiner les résultats par tags
, une propriété utilisable dans une recherche approfondie
Correspondance exacte requise
Si isExactMatchRequired concerne true
une propriété, la valeur de chaîne complète est indexée.
isExactMatchRequired peut uniquement être défini sur true
pour les propriétés ne pouvant pas faire l’objet d’une recherche.
Par exemple, la propriété ticketId est à la fois interrogeable et spécifie la correspondance exacte.
- L’interrogation
ticketId:CTS-ce913b61
retourne l’élément avec une propriété d’ID de ticket CTS-ce913b61. - L’interrogation
ticketId:CTS
ne retourne PAS l’élément avec l’ID de ticket CTS-ce913b61.
De même, la propriété tags spécifie également la correspondance exacte.
- L’interrogation
tags:contoso
renvoie n’importe quel élément avec la balise contoso. - L’interrogation
tags:contoso
ne retourne PAS les éléments avec la balise contoso ticket.
Par exemple, il peut y avoir un scénario où la propriété d’élément est une chaîne au format GUID. Si cette propriété doit être mise en correspondance exactement pour les requêtes d’élément, spécifiez que isExactMatchRequired est true
.
La propriété title ne spécifie pas de correspondance exacte. Si rien n’est spécifié, isExactMatchRequired a la valeurfalse
. La propriété title sera tokenisée en fonction des règles de tokenisation de la langue du contenu de l’élément.
- L’interrogation
title:Contoso Title
renvoie tout élément contenant « Contoso » ou « Title » dans la propriété title .
Étiquettes sémantiques
Une étiquette sémantique est une balise connue publiée par Microsoft que vous pouvez ajouter par rapport à une propriété dans votre schéma. L’ajout d’une étiquette sémantique permet à différents produits Microsoft de comprendre la propriété et de fournir une meilleure expérience.
Les étiquettes sémantiques fournissent une approche indépendante du domaine pour affecter des propriétés de différents domaines de contenu à un ensemble de classes connues. Ils recherchent des applications dans de nombreuses expériences de contenu différentes et fournissent une prise en charge automatisée des tâches telles que :
- Intégration des données dans les expériences hetérogenes
- Création de graphiques de connaissances courants (par exemple, Viva Topics)
- Modèles par défaut pour les expériences utilisateur
Vous pouvez affecter des étiquettes sémantiques à vos propriétés source dans la page Attribuer des étiquettes de propriétés. Les étiquettes fournissent une signification sémantique et vous permettent d’intégrer vos données de connecteur dans Microsoft 365 expériences.
Étiquette | Description |
---|---|
title | Le titre de l’élément que vous souhaitez voir dans la recherche et d’autres expériences. |
url | L’URL cible de l’élément dans la source de données. |
createdBy | Nom de la personne qui a créé l’élément dans la source de données. |
lastModifiedBy | Nom de la personne qui a récemment modifié l’élément dans la source de données. |
authors | Nom de toutes les personnes qui ont participé/collaboré à l’élément de la source de données. |
createdDateTime | Date et heure à laquelle l’élément a été créé dans la source de données. |
lastModifiedDateTime | Date et heure de la dernière modification de l’élément dans la source de données. |
fileName | Dans le cas d'un fichier, le nom du fichier dans la source de données. |
fileExtension | Dans le cas d’un fichier, l’extension du fichier dans la source de données. |
iconUrl | L’URL d’une icône. |
containerName | Nom du conteneur. |
containerUrl | L’URL du conteneur. |
Par exemple, la propriété de connexion lastEditedBy a la même signification que l’étiquette Microsoft lastModifiedBy.
Ajoutez autant d’étiquettes que possible, mais assurez-vous qu’elles sont correctement mappées aux propriétés. N’ajoutez pas d’étiquette à une propriété si elle n’a pas de sens. Des mappages incorrects dégradent l’expérience.
Importante
Toutes les propriétés que vous mappez aux étiquettes doivent pouvoir être récupérées.
Le titre de l’étiquette est l’étiquette la plus importante. Veillez à affecter une propriété à cette étiquette pour permettre à votre connexion de participer à l’expérience de cluster de résultats. Un mappage incorrect des étiquettes dégrade l’expérience de recherche. Il est possible que certaines étiquettes ne soient pas affectées à une propriété.
Importance
En appliquant autant d’étiquettes correctement mappées que possible, vous pouvez également améliorer la découverte de votre contenu via la recherche. Nous vous recommandons vivement de définir autant d’étiquettes que possible, répertoriées par impact potentiel sur la découverte dans l’ordre décroissant :
- titre
- lastModifiedDateTime
- lastModifiedBy
- url
- fileName
- fileExtension
Pour la découverte (scénarios de recherche), notez les points suivants :
- Assurez-vous que vos mappages sont exacts.
- Lorsque vous utilisez une propriété en tant qu’étiquette qui contient du contenu volumineux, vous pouvez augmenter la latence de recherche et attendre plus longtemps que la recherche retourne des résultats.
- En particulier dans le scénario où vous configurez une verticale personnalisée qui permet la recherche sur plusieurs connexions, les résultats de la recherche tirent considérablement parti de la création d’autant d’étiquettes que possible.
Indicateurs de classement
Les indicateurs de classement peuvent être appliqués aux propriétés textuelles qui ne sont pas mappées à des étiquettes sémantiques et qui sont définies comme pouvant faire l’objet d’une recherche. Ils peuvent être définis dans une plage allant de par défaut à très élevé dans le portail d’administration Recherche. Les indicateurs sont consommés avec d’autres attributs de chaque élément, afin de retourner les éléments les plus pertinents pour une requête donnée.
Procédez comme suit pour définir des indicateurs de classement :
- Sous l’onglet Recherche et intelligence du portail d’administration, accédez àParamétrage de la pertinencede la personnalisation>.
- Pour afficher la liste des connexions qui peuvent être paramétrées, choisissez Afficher les détails>Configurer les indicateurs de classement.
- Modifiez les pondérations d’importance sur les propriétés sources disponibles.
Types de résultats par défaut
Les étiquettes affectent également la façon dont les types de résultats par défaut sont générés. L’ajout des étiquettes de titre et de contenu au minimum garantit qu’un type de résultat est créé pour votre connexion.
Un type de résultat par défaut avec title
et un extrait de résultats.
Votre type de résultat par défaut offre une meilleure expérience lorsque vous définissez ces étiquettes, le cas échéant, répertoriées par ordre croissant :
- titre
- url
- lastModifiedBy
- lastModifiedDateTime
- fileName
- fileExtension
Enfin, lorsque vous assignez des étiquettes, vérifiez les points suivants :
- Les propriétés que vous sélectionnez pour fonctionner comme étiquettes doivent être marquées comme pouvant être récupérées.
- Les propriétés et les étiquettes qui leur sont attribuées doivent avoir le même type de données.
- Vous pouvez mapper exactement une étiquette à exactement une propriété.
Alias
Les alias sont des noms conviviaux pour les propriétés que vous attribuez. Ils sont utilisés dans les requêtes et les sélections dans les filtres de propriétés pouvant être affinés.
Fonctionnalités de mise à jour du schéma
Cette section contient des informations sur les fonctionnalités de mise à jour de l’API de schéma.
Remarque
Nous vous recommandons de reingérer les éléments après une mise à jour pour les mettre au schéma le plus récent. Sans réingestion, le comportement des éléments sera incohérent.
Ajouter une propriété
Vous pouvez ajouter une propriété à votre schéma ; cela ne nécessite pas de réingestion, mais nous le recommandons.
Lorsque vous ajoutez une propriété, vous pouvez inclure tous les attributs de recherche dont vous avez besoin.
Ajout/suppression d’une fonctionnalité de recherche
Vous pouvez ajouter des attributs de recherche spécifiques à une propriété, mais n’oubliez pas que vous ne pouvez pas ajouter un attribut de recherche d’affinement en tant que modification de schéma. En outre, il n’est pas possible d’utiliser des attributs pouvant à nouveau être affinés en tant que fonctionnalités pouvant faire l’objet d’une recherche.
L’ajout d’une fonctionnalité de recherche nécessite une réingestion.
Ajouter/supprimer un alias
Vous pouvez ajouter ou supprimer des alias et les utiliser pour vos requêtes de recherche.
Considérez que vous ne pouvez pas supprimer l’alias d’origine d’une propriété pouvant être affinée qui a été autocréée par le système.
Ajouter/supprimer une étiquette sémantique
L’ajout d’une étiquette sémantique peut affecter des expériences telles que pertinence et Viva Topics.