Inscrire et gérer le schéma pour les connecteurs Microsoft 365 Copilot

Ce guide fournit des conseils sur la définition de schémas et les meilleures pratiques pour les connecteurs Microsoft 365 Copilot.

Le schéma de connexion définit la façon dont votre contenu est utilisé dans Microsoft 365 Copilot expériences. Un schéma est une liste plate de toutes les propriétés que vous envisagez d’ajouter à la connexion. Chaque propriété inclut des attributs, des étiquettes et des alias. Vous devez inscrire le schéma avant d’ajouter des éléments à la connexion.

Le tableau suivant présente un exemple de schéma pour un connecteur de 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		✔️	✔️

Pour obtenir des informations de référence sur l’objet de schéma et l’API, consultez la section schéma dans la référence de l’API Copilot Connector.

Attributs de schéma

Cette section décrit chaque attribut de schéma et fournit les meilleures pratiques pour leur utilisation.

Propriété

Cet attribut fait référence au nom de la propriété.

Meilleures pratiques :

• Utiliser des noms clairs et uniques : assurez-vous que les noms de propriétés sont faciles à comprendre et à distinguer. Évitez les noms ambigus comme orgName, brOrgNameou tpOrgName. Utilisez plutôt des noms descriptifs tels que parentOrganizationName ou departmentName pour aider Copilot à interpréter correctement la propriété.
• Évitez les noms trop techniques ou cryptiques : remplacez les noms tels que dataBlob ou ftxInvIsLead par des alternatives significatives comme incidentRootCause ou qualifiedSalesLead pour améliorer la lisibilité et la pertinence des requêtes utilisateur.
• Ajouter des descriptions de propriétés : les descriptions aident Copilot à mieux comprendre et à faire correspondre les propriétés aux requêtes utilisateur.

Remarque

La prise en charge de l’ajout de descriptions de propriétés aux connecteurs personnalisés est attendue au 4e trimestre 2025.
Lorsque vous utilisez des agents déclaratifs (DA), incluez des descriptions de propriétés dans le jeu d’instructions DA.

Utilisable dans une recherche

Lorsqu’une propriété est marquée comme pouvant faire l’objet d’une recherche, sa valeur est ajoutée à l’index de recherche en texte intégral. Cela permet à Copilot de retourner des résultats lorsque la requête d’un utilisateur correspond à la propriété ou à son contenu.

Marquer une propriété comme pouvant faire l’objet d’une recherche si :

• Il contient des données textuelles que les utilisateurs sont susceptibles de rechercher.
• Il est pertinent pour les requêtes de recherche (par exemple, les titres, les descriptions, les balises).
• Vous souhaitez qu’il contribue aux résultats de recherche et à la génération d’extraits de code.

Exemples courants :title , description, tags, createdBy, assignedTo.

Meilleures pratiques :

• Évitez de marquer des champs binaires volumineux comme pouvant faire l’objet d’une recherche.
• Ne marquez pas les champs refinisables comme pouvant faire l’objet d’une recherche. Ces attributs s’excluent mutuellement.
• Marquez uniquement les propriétés comme pouvant faire l’objet d’une recherche si elles sont essentielles pour la pertinence de la recherche.

Une recherche pour design affiche les résultats des accès à la propriété (title) et au contenu.

Utilisable dans une requête

Marquez une propriété comme pouvant être interrogeable si les utilisateurs doivent filtrer leurs résultats de recherche en fonction de valeurs spécifiques. Par exemple, des propriétés telles que ticketId, teamNameou created peuvent être interrogeables. Lorsqu’un utilisateur interroge quelque chose comme tickets created by William, Copilot peut filtrer et retourner uniquement les tickets appropriés. La correspondance de préfixe avec des opérateurs génériques (*) peut améliorer davantage la flexibilité de la recherche.

Marquez une propriété comme pouvant être interrogeable si :

• Il est utilisé pour filtrer ou affiner les résultats de recherche.
• Il représente des données catégorielles ou structurées (par exemple, status, priorité, utilisateur affecté).
• Vous souhaitez prendre en charge les expériences de recherche personnalisées ou la navigation à facettes.

Exemples courants :

status (par exemple, ouvert, fermé), assignedTo (par exemple, userEmail ou ID), priority (par exemple, élevé, moyen, faible), categoryou type.

Meilleures pratiques :

• Évitez de marquer des champs de texte volumineux (comme des descriptions) comme pouvant être interrogés.
• Combinez Queryable: true avec Retrievable: true pour que la propriété puisse être utilisée et affichée dans les résultats.
• Utilisez Refinable: true si vous souhaitez que la propriété apparaisse en tant que filtre dans l’interface utilisateur.

Dans cet exemple, tags est marqué comme interrogeable :

Recherche de tags:design l’étendue des résultats sur les éléments avec design dans la tags propriété .

Si une propriété est interrogeable, vous pouvez l’interroger à l’aide de KQL (Keyword Query Language). KQL prend en charge les mots clés de texte libre et les restrictions de propriété. Le nom de la propriété doit être inclus dans la requête, explicitement ou par programme. La correspondance de préfixe avec l’opérateur générique (*) est prise en charge.

Remarque

La correspondance des suffixes n’est pas prise en charge.

Recherche d’affichage search ba\* des résultats qui correspondent à ce préfixe.

Affichable dans les résultats d’une recherche

Marquez une propriété comme récupérable si sa valeur doit être retournée dans les résultats de la recherche. Toute propriété qui apparaît dans le modèle d’affichage ou qui est retournée à partir d’une requête doit être récupérable. Soyez sélectif : le fait de marquer des propriétés trop nombreuses ou volumineuses comme récupérables peut augmenter la latence de la recherche.

Ensemble de propriétés récupérables (title et lastEditedBy ) rendues par conséquent.

Marquer une propriété comme récupérable si :

• Vous souhaitez qu’elle soit visible dans les résultats de la recherche.
• Il fournit des informations contextuelles (par exemple, titre, status, utilisateur affecté).

Exemples courants :
title, summary, description, status, assignedTo, createdDateTime.

Meilleures pratiques :

• Évitez de marquer des champs sensibles ou non pertinents comme récupérables.
• Utilisez Retrievable: true pour les champs affichés dans les cartes de recherche, les invites Copilot ou l’interfaceutilisateur personnalisée.

Utilisable dans une recherche approfondie

Marquez une propriété comme pouvant être définie si vous souhaitez qu’elle soit utilisée comme filtre dans les expériences de Recherche Microsoft. Les propriétés refinisables peuvent être configurées par les administrateurs pour qu’elles apparaissent en tant que filtres personnalisés sur la page des résultats de la recherche.

Lorsqu’une propriété est refinable :

• Il peut être utilisé pour affiner les résultats de la recherche.
• Il apparaît sous la forme d’un contrôle d’affinement (par exemple, liste déroulante ou case à cocher) dans l’interface utilisateur.
• Il prend en charge l’agrégation dans les requêtes de recherche.

Marquez une propriété comme pouvant être définie si :

• Il représente des données catégorielles ou structurées.
• Vous souhaitez que les utilisateurs filtrent ou regroupent les résultats en fonction de ces valeurs.

Exemples courants :
tags (par exemple, finance, RH, ingénierie), status (par exemple, ouvert, fermé, en cours), priority (par exemple, élevé, moyen, faible), category, type.

Meilleures pratiques :

• Les éléments refinables et interrogeables s’excluent mutuellement : une propriété ne peut pas être les deux.
• Seuls les types chaîne ou numériques peuvent être redéfinissables.
• Le marquage d’un trop grand nombre de propriétés comme pouvant être définies peut avoir un impact sur les performances.

Affinez les résultats par tags, une propriété pouvant être définie.

Correspondance exacte requise

Si isExactMatchRequired est défini sur true pour une propriété, la valeur de chaîne complète est indexée. Ce paramètre ne peut être appliqué qu’aux propriétés qui ne peuvent pas faire l’objet d’une recherche.

Par exemple, la propriété est à la ticketId fois interrogeable et nécessite une correspondance exacte :

• L’interrogation ticketId:CTS-ce913b61 retourne l’élément avec l’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é utilise également la tags correspondance exacte :

• L’interrogation tags:contoso retourne des éléments avec la balise contoso.
• L’interrogation tags:contoso ne retourne pas les éléments avec la balise contoso ticket.

Cela est particulièrement utile lorsque la propriété contient des valeurs telles que des GUID ou d’autres identificateurs qui doivent être mis en correspondance exactement. Dans ce cas, définissez sur isExactMatchRequiredtrue.

Si isExactMatchRequired n’est pas spécifié, la valeur par défaut falseest . Par exemple, la title propriété ne nécessite pas de correspondance exacte. Il est tokenisé en fonction des règles de langage du contenu de l’élément :

• L’interrogation title: Contoso Title retourne les éléments qui contiennent Contoso ou Title dans le titre.

Étiquettes sémantiques

Une étiquette sémantique est une étiquette connue publiée par Microsoft que vous pouvez affecter à une propriété dans votre schéma. Lors de la création d’un connecteur Copilot personnalisé à l’aide du API Graph Microsoft, l’application d’étiquettes sémantiques est essentielle. Ces étiquettes aident Microsoft 365 Copilot et Recherche Microsoft à comprendre la signification et le rôle de chaque propriété, ce qui améliore la recherche, le résumé et l’expérience utilisateur globale.

Vous pouvez attribuer des étiquettes sémantiques à l’aide de la API Graph ou à partir de la page Attribuer des étiquettes de propriétés lors de l’utilisation du Kit de développement logiciel (SDK). Les étiquettes fournissent une signification sémantique et permettent à vos données de connecteur de s’intégrer en toute transparence dans les expériences Microsoft 365.

Par exemple, différents outils de gestion de projet (comme JIRA, Azure DevOps, Asana) peuvent utiliser des termes différents pour l’utilisateur qui a créé un élément de travail, comme owner, ownedByou assignedTo. Si votre propriété a un objectif similaire, vous pouvez attribuer l’étiquette createdBy sémantique.

Vous pouvez attribuer des étiquettes sémantiques à vos propriétés sources à l’aide de l’API de graphe ou de la page Attribuer des étiquettes de propriétés lors de l’utilisation du sdk. Les étiquettes fournissent une signification sémantique et vous permettent d’intégrer vos données de connecteur dans les expériences Microsoft 365.

Étiquette	Description	S’applique aux champs tels que
title	Nom main ou en-tête de l’élément que vous souhaitez afficher dans la recherche et d’autres expériences.	documentTitle, ticketSubject, reportName
url	L’URL cible de l’élément dans la source de données. Lien direct permettant d’ouvrir l’élément dans son système d’origine.	documentLink, ticketUrl, recordUrl
createdBy	Identifie l’utilisateur qui a initialement créé l’élément dans la source de données. Utile pour le filtrage et le contexte.	authorEmail, submittedBy, createdByUser
lastModifiedBy	Nom de l’utilisateur qui a récemment modifié l’élément dans la source de données.	editorEmail, updatedBy, lastChangedBy
authors	Nom de toutes les personnes qui ont participé/collaboré à l’élément de la source de données.	authorName, writer, reportAuthor
createdDateTime	Date et heure à laquelle l’élément a été créé dans la source de données.	createdOn, submissionDate, entryDate
lastModifiedDateTime	Date et heure de la dernière modification de l’élément dans la source de données.	lastUpdated, modifiedOn, changeDate
fileName	Nom du fichier dans la source de données.	projectUrl, folderLink, groupPage
fileExtension	Extension du fichier dans la source de données.	documentType, attachmentType, format
iconUrl	L’URL d’une icône.	thumbnailUrl, logo, previewImage
containerName	Nom du conteneur. Exemple : un projet ou un dossier OneDrive peut être un conteneur.	projectName, folderName, groupName
containerUrl	L’URL du conteneur.	projectUrl, folderLink, groupPage

Meilleures pratiques :

• Ajoutez autant d’étiquettes que possible, mais assurez-vous qu’elles sont mappées avec précision.
• N’affectez pas d’étiquette à une propriété si elle ne correspond pas à son objectif : des mappages incorrects dégradent l’expérience.

Importante

Les propriétés doivent être marquées comme récupérables avant de pouvoir être mappées à des étiquettes.

L’étiquette title est la plus importante. L’attribution d’une propriété à cette étiquette permet à votre connexion de participer à l’expérience de cluster de résultats. Même si toutes les étiquettes ne doivent pas être utilisées, assurez-vous que celles que vous attribuez sont explicites et précises.

Importance

L’application d’étiquettes sémantiques mappées avec précision améliore la détectabilité de votre contenu par le biais de la recherche. Microsoft recommande de définir autant d’étiquettes suivantes que possible, répertoriées dans l’ordre décroissant de leur impact sur la découverte :
title, lastModifiedDateTime, lastModifiedBy, url, fileName et fileExtension.

Assurez-vous que vos mappages d’étiquettes sont exacts. L’attribution d’une étiquette à une propriété qui contient du contenu volumineux peut augmenter la latence de recherche et retarder les résultats.

Indicateurs de classement

Les indicateurs de classement peuvent être appliqués aux propriétés textuelles qui :

• Peuvent faire l’objet d’une recherche
• Ne sont pas mappés à des étiquettes sémantiques

Les indicateurs de classement aident à hiérarchiser certaines propriétés dans les résultats de recherche. Vous pouvez définir leur importance de par défaut à très élevée dans le portail d’administration recherche Microsoft 365. Ces indicateurs sont utilisés avec d’autres attributs d’élément pour retourner les résultats les plus pertinents.

Pour configurer les indicateurs de classement :

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

3. Sous Paramétrage de la pertinence, choisissez Afficher les détails>Configurer les indicateurs de classement.

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

Types de résultats par défaut

Les étiquettes sémantiques influencent également la façon dont les types de résultats par défaut sont générés. Au minimum, l’affectation des title étiquettes et content 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.

Pour améliorer l’expérience des résultats par défaut, définissez les étiquettes suivantes le cas échéant (répertoriées dans l’ordre croissant d’impact) :
title, url, lastModifiedBy, lastModifiedDateTime, fileName et fileExtension.

Liste de contrôle de validation pour l’attribution d’étiquettes :

• Les propriétés affectées aux étiquettes doivent être marquées comme récupérables.
• Le type de données de la propriété doit correspondre au type attendu pour l’étiquette.
• Chaque étiquette doit être mappée à exactement une propriété.

Alias

Les alias sont des noms conviviaux attribués aux propriétés. Ils sont utilisés dans les requêtes et dans les filtres de propriétés refinables pour améliorer la facilité d’utilisation et la flexibilité des requêtes.

Voici quelques exemples concrets :

Propriété	Alias possibles	Cas d’utilisation
createdBy	author, owner, submittedBy	Utilisateurs demandant Who wrote this? ou Who submitted?
title	objet, titre	Utilisateurs demandant What’s the subject of this item?
étiquettes	étiquettes, catégories	Utilisateurs demandant Show items tagged with Finance
nomdefichier	documentName, fileName	Utilisateurs demandant Find file named report.docx
résumé	description, résumé	Utilisateurs demandant Give me a quick overview

Bonnes pratiques pour les alias :

• Utilisez des alias pour les synonymes courants ou lestermes spécifiques au domaine.
• Évitez les alias trop génériques ou ambigus.
• Gardez les alias courts et intuitifs.

Content, propriété

Le schéma du connecteur Microsoft Copilot prend en charge une propriété par défaut appelée content. Vous n’avez pas besoin de le définir dans le schéma comme d’autres propriétés (par exemple, titre, balises, etc.). Au lieu de cela, il est directement inclus dans la charge utile de l’élément lorsque vous ingérer des données.

Le schéma du connecteur Microsoft Copilot comprend une propriété intégréecontent. Contrairement à d’autres propriétés (telles que title ou tags), vous n’avez pas besoin de le définir dans le schéma. Au lieu de cela, il est inclus directement dans la charge utile de l’élément pendant l’ingestion des données.

La content propriété est :

• Indexé sémantiquement pour la recherche de texte.
• Utilisé pour générer des extraits de code dynamiques dans les résultats de recherche.
• Disponible pour Copilot pour le résumé et la compréhension sémantique.

Meilleures pratiques pour l’utilisation de la propriété de contenu :

• Ajoutez toutes les données non structurées à la content propriété pour permettre à Copilot d’effectuer une recherche sémantique et de faire correspondre efficacement les requêtes.
• Pour le contenu non structuré ou de forme libre, incluez des propriétés telles que summary, comment, rootCauseet description dans le content champ .
• Conservez ces propriétés en tant que champs récupérables distincts uniquement si leur valeur complète doit être affichée dans l’interface utilisateur.
• Vous pouvez ajouter plusieurs propriétés (par exemple, summary, description) dans le champ pour enrichir la content compréhension sémantique.

Exemple d’utilisation de la propriété lors de l’ingestion content de données :

{ 
"@odata.type": "microsoft.graph.externalItem", 
"acl": [ 
{ 
"type": "everyone", 
"value": "everyone", 
"accessType": "grant" 
} 
], 

"properties": { 
"title": "Payment Gateway Error", 
"priority": "High", 
"assignee": "john.doe@contoso.com" 
}, 

"content": { 
"value": "Rootcause : Error in payment gateway : MoreDetails about the error.......", 
"type": "text" 
} 
}

Descriptions des agents déclaratifs et des propriétés

Si vous utilisez un agent déclaratif (DA), vous devez inclure les descriptions de propriétés de votre schéma de connecteur Copilot dans le jeu d’instructions fourni à l’agent. Cela permet au da da de comprendre les points suivants :

• Signification sémantique de chaque propriété
• Guide pratique pour référencer et résumer les données
• Comment répondre aux requêtes des utilisateurs à l’aide du contenu indexé

Définissez des descriptions claires et bien formées pour toutes les propriétés. Une bonne description doit expliquer :

• Ce que représente la propriété
• Tous les autres noms ou termes
• Quand et comment il doit être utilisé

Fonctionnalités de mise à jour du schéma

Cette section décrit les fonctionnalités de mise à jour de l’API de schéma .

Remarque

Après avoir mis à jour votre schéma, nous vous recommandons de réindexer les éléments pour les aligner sur le schéma le plus récent. Sans réingestion, le comportement de l’élément peut être incohérent.

Ajouter une propriété

Vous pouvez ajouter une nouvelle propriété à votre schéma. Bien que la réingestion ne soit pas obligatoire, elle est recommandée. Lors de l’ajout d’une propriété, incluez tous les attributs de recherche nécessaires.

Ajouter ou supprimer une fonctionnalité de recherche

Vous pouvez modifier les attributs de recherche d’une propriété. Toutefois:

• Vous ne pouvez pas ajouter un attribut redéfinissable dans le cadre d’une mise à jour de schéma.
• Une propriété ne peut pas faire l’objet d’une recherche ni être redéfinie.

L’ajout ou la suppression d’une fonctionnalité de recherche nécessite une réingestion.

Ajouter ou supprimer un alias

Vous pouvez ajouter ou supprimer des alias à utiliser dans les requêtes de recherche. Toutefois, les alias qui ont été créés automatiquement par le système pour les propriétés refinables ne peuvent pas être supprimés.

Ajouter ou supprimer une étiquette sémantique

Vous pouvez attribuer ou supprimer des étiquettes sémantiques. Ces étiquettes influencent les expériences telles que pertinence et Viva Topics.

Étapes suivantes

• Ajouter des éléments à la connexion
• Passer en revue les informations de référence sur l’API des connecteurs Copilot
• Rechercher dans les types personnalisés (externalItem)