Partager via

Inscrire et mettre à jour le schéma pour la connexion Graph Microsoft

  • Article

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 String ✔️ ✔️ ✔️ titre
createdBy String ✔️ ✔️ createdBy Créateur
assignedTo String ✔️ ✔️
lastEditedDate Date/heure ✔️ ✔️ ✔️ lastModifiedDateTime editedDate
lastEditedBy String ✔️ ✔️ ✔️ lastModifiedBy modifié
workItemType String ✔️ ✔️ ticketType
priorité Int64 ✔️
étiquettes StringCollection ✔️ ✔️ ✔️ ✔️
status String ✔️ ✔️
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 des correspondances par rapport au titre et au contenu de la propriété.

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 de suffixe n’est pas prise en charge.

Une recherche pour « *rechercher ba* » affichant les résultats qui correspondent à ce préfixe.

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 le « design » figure dans la propriété des balises

Une recherche pour « tags:design » permet de réduire les résultats aux articles dont où « design » figure dans la tagsproprié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 rendues par conséquent.

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.

Affinez les résultats par balises, une propriété pouvant être affinée.

Affiner les résultats par tags, une propriété utilisable dans une recherche approfondie

Correspondance exacte requise

Si isExactMatchRequired est true pour 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 retourne n’importe tags:contoso quel élément avec la balise contoso.
  • L’interrogation tags:contoso ne retourne pas les éléments avec le ticket contoso de balise.

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 est tokenisée en fonction des règles de tokenisation de la langue du contenu de l’élément.

  • L’interrogation title:Contoso Title retourne tout élément qui contient 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 cela 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 la valeur par défaut à très élevée dans le portail d’administration de la 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 :

  1. Accédez à l’onglet Recherche et intelligence dans le portail d’administration.
  2. SélectionnezParamétrage de la pertinencede la personnalisation>.

Capture d’écran de l’onglet Recherche et intelligence avec le réglage de la pertinence mis en évidence

  1. Pour afficher la liste des connexions qui peuvent être paramétrées, choisissez Afficher les détails>Configurer les indicateurs de classement.

Capture d’écran de l’onglet Paramétrage de la pertinence avec l’option Configurer les indicateurs de classement mise en évidence

  1. Modifiez les pondérations d’importance sur les propriétés sources disponibles.

Capture d’écran de l’onglet Paramétrage de la pertinence montrant les pondérations d’importance pour une propriété sélectionnée

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.

Type de résultat par défaut avec titre et extrait de résultat.

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 est 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 gardez à l’esprit 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 refinisables comme fonctionnalités de 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é refinable qui a été automatiquement créé 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.

Étapes suivantes