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 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 (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.

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.

Étapes suivantes

• Ajouter des éléments à la connexion
• Examiner la référence sur les API connecteurs Microsoft Graph
• Rechercher dans les types personnalisés (externalItem)
• Créer votre premier connecteur Microsoft Graph personnalisé