Registrieren und Verwalten des Schemas für die Microsoft 365 Copilot Connectors

Dieser Leitfaden enthält Anleitungen zum Definieren von Schemas und zum Befolgen bewährter Methoden für Microsoft 365 Copilot Connectors.

Das Verbindungsschema definiert, wie Ihre Inhalte in Microsoft 365 Copilot Umgebungen verwendet werden. Ein Schema ist eine flache Liste aller Eigenschaften, die Sie der Verbindung hinzufügen möchten. Jede Eigenschaft enthält Attribute, Bezeichnungen und Aliase. Sie müssen das Schema registrieren, bevor Sie der Verbindung Elemente hinzufügen.

Die folgende Tabelle zeigt ein Beispielschema für einen Arbeitsticketsystemconnector:

Schemaobjekt- und API-Referenz finden Sie im Abschnitt schema in der Referenz zur Copilot Connector-API.

Schemaattribute

In diesem Abschnitt werden die einzelnen Schemaattribute beschrieben und bewährte Methoden für deren Verwendung beschrieben.

Eigenschaft

Dieses Attribut verweist auf den Namen der Eigenschaft.

Bewährte Vorgehensweisen:

• Klare und eindeutige Namen verwenden: Stellen Sie sicher, dass Eigenschaftennamen leicht zu verstehen und zu unterscheiden sind. Vermeiden Sie mehrdeutige Namen wie orgName, brOrgNameoder tpOrgName. Verwenden Sie stattdessen beschreibende Namen wie parentOrganizationName oder departmentName , um Copilot bei der korrekten Interpretation der Eigenschaft zu unterstützen.
• Vermeiden Sie zu technische oder kryptische Namen : Ersetzen Sie Namen wie dataBlob oder ftxInvIsLead durch sinnvolle Alternativen wie incidentRootCause oder qualifiedSalesLead , um die Lesbarkeit und Relevanz für Benutzerabfragen zu verbessern.
• Hinzufügen von Eigenschaftenbeschreibungen : Beschreibungen helfen Copilot dabei, Eigenschaften besser zu verstehen und mit Benutzerabfragen abzugleichen.

Searchable

Wenn eine Eigenschaft als durchsuchbar markiert ist, wird ihr Wert dem Volltextindex hinzugefügt. Dadurch kann Copilot Ergebnisse zurückgeben, wenn die Abfrage eines Benutzers mit der Eigenschaft oder ihrem Inhalt übereinstimmt.

Markieren Sie eine Eigenschaft als durchsuchbar, wenn:

• Sie enthält Textdaten , nach denen Benutzer wahrscheinlich suchen.
• Sie ist für Suchabfragen (z. B. Titel, Beschreibungen, Tags) relevant.
• Sie möchten, dass sie zur Generierung von Suchtreffern und Codeausschnitten beiträgt.

Häufige Beispiele:title , description, tags, createdBy, assignedTo.

Bewährte Vorgehensweisen:

• Vermeiden Sie das Markieren großer binärer Felder als durchsuchbar.
• Markieren Sie nicht einschränkbare Felder als durchsuchbar– diese Attribute schließen sich gegenseitig aus.
• Markieren Sie Nur Eigenschaften als durchsuchbar, wenn sie für die Relevanz der Suche unerlässlich sind.

Eine Suche nach design zeigt Ergebnisse für Treffer gegen die Eigenschaft (title) und den Inhalt an.

Queryable

Markieren Sie eine Eigenschaft als abfragbar , wenn Benutzer ihre Suchergebnisse nach bestimmten Werten filtern müssen. Beispielsweise können Eigenschaften wie ticketId, teamNameoder created abfragbar sein. Wenn ein Benutzer etwas wie tickets created by Williamabfragt, kann Copilot nur die relevanten Tickets filtern und zurückgeben. Der Präfixabgleich mit Wildcardoperatoren (*) kann die Suchflexibilität weiter verbessern.

Markieren Sie eine Eigenschaft als abfragbar, wenn:

• Es wird zum Filtern oder Einschränken von Suchergebnissen verwendet.
• Sie stellt kategorische oder strukturierte Daten dar (z. B. status, Priorität, zugewiesener Benutzer).
• Sie möchten benutzerdefinierte Suchfunktionen oder Facettennavigation unterstützen.

Häufige Beispiele:

status (z. B. offen, geschlossen), assignedTo (z. B. userEmail oder ID), priority (z. B. hoch, mittel, niedrig), categoryoder type.

Bewährte Vorgehensweisen:

• Vermeiden Sie es, große Textfelder (z. B. Beschreibungen) als abfragbar zu markieren.
• Kombinieren Sie Queryable: true mit Retrievable: true , damit die Eigenschaft verwendet und in den Ergebnissen angezeigt werden kann.
• Verwenden Sie Refinable: true , wenn die Eigenschaft als Filter auf der Benutzeroberfläche angezeigt werden soll.

In diesem Beispiel tags ist als abfragbar gekennzeichnet:

Eine Suche nach tags:design bereichsbasierten Ergebnissen auf Elemente mit design in der tags -Eigenschaft.

Wenn eine Eigenschaft abgefragt werden kann, können Sie sie mithilfe von KQL (Keyword Query Language) abfragen. KQL unterstützt Freitext-Schlüsselwörter und Eigenschaftseinschränkungen. Der Eigenschaftenname muss explizit oder programmgesteuert in der Abfrage enthalten sein. Der Präfixabgleich mit dem Wildcardoperator (*) wird unterstützt.

Eine Suche nach search ba\* der Anzeige von Ergebnissen, die diesem Präfix entsprechen.

Retrievable

Markieren Sie eine Eigenschaft als abrufbar , wenn ihr Wert in Suchergebnissen zurückgegeben werden soll. Jede Eigenschaft, die in der Anzeigevorlage angezeigt wird oder von einer Abfrage zurückgegeben wird, muss abrufbar sein. Selektiv sein: Wenn Sie zu viele oder große Eigenschaften als abrufbar markieren, kann dies die Suchlatenz erhöhen.

Eine Reihe abrufbarer Eigenschaften (title und lastEditedBy), die als Ergebnis dargestellt werden.

Markieren Sie eine Eigenschaft als abrufbar, wenn:

• Sie möchten, dass sie in den Suchergebnissen sichtbar ist.
• Sie stellt Kontextinformationen bereit (z. B. Titel, status, zugewiesener Benutzer).

Häufige Beispiele:
title, summary, description, status, assignedTo, createdDateTime.

Bewährte Vorgehensweisen:

• Vermeiden Sie es, sensible oder irrelevante Felder als abrufbar zu markieren.
• Wird Retrievable: true für Felder verwendet, die in Suchkarten, Copilot-Eingabeaufforderungen oder einer benutzerdefinierten Benutzeroberfläche angezeigt werden.

Refinable

Markieren Sie eine Eigenschaft als einschränkbar , wenn sie als Filter in Microsoft Search-Umgebungen verwendet werden soll. Verfeinerungsfähige Eigenschaften können von Administratoren so konfiguriert werden, dass sie als benutzerdefinierte Filter auf der Suchergebnisseite angezeigt werden.

Wenn eine Eigenschaft eingeschränkt werden kann:

• Es kann verwendet werden, um Suchergebnisse einzugrenzen.
• Es wird als Einschränkungssteuerelement (z. B. Dropdown oder Kontrollkästchen) auf der Benutzeroberfläche angezeigt.
• Sie unterstützt die Aggregation in Suchabfragen.

Markieren Sie eine Eigenschaft als verfeinerungsfähig, wenn:

• Sie stellt kategorische oder strukturierte Daten dar.
• Sie möchten, dass Benutzer Ergebnisse nach diesen Werten filtern oder gruppieren .

Häufige Beispiele:
tags (z. B. Finanzen, Personalwesen, Ingenieurwesen), status (z. B. offen, geschlossen, in Bearbeitung), priority (z. B. hoch, mittel, niedrig), category, type.

Bewährte Vorgehensweisen:

• Einschränkbar und durchsuchbar schließen sich gegenseitig aus– eine Eigenschaft kann nicht beides sein.
• Es können nur Zeichenfolgen- oder numerische Typen eingeschränkt werden.
• Das Markieren zu vieler Eigenschaften als verfeinernd kann die Leistung beeinträchtigen.

Optimieren Sie die Ergebnisse nach tags, einer einschränkungsfähigen Eigenschaft.

Exakte Übereinstimmung erforderlich

Wenn isExactMatchRequired für eine Eigenschaft auf true festgelegt ist, wird der vollständige Zeichenfolgenwert indiziert. Diese Einstellung kann nur auf Eigenschaften angewendet werden, die nicht durchsuchbar sind.

Beispielsweise ist die ticketId Eigenschaft sowohl abfragbar als auch erfordert einen genauen Abgleich:

• Die Abfrage ticketId:CTS-ce913b61 gibt das Element mit der Ticket-ID CTS-ce913b61 zurück.
• Die ticketId:CTS Abfrage gibt das Element mit der Ticket-ID CTS-ce913b61 nicht zurück.

Auf ähnliche Weise verwendet die tags -Eigenschaft auch den genauen Abgleich:

• Beim Abfragen werden tags:contoso Elemente mit dem Tag contoso zurückgegeben.
• tags:contoso Abfragen geben keine Elemente mit dem Tag contoso ticket zurück.

Dies ist besonders nützlich, wenn die Eigenschaft Werte wie GUIDs oder andere Bezeichner enthält, die genau übereinstimmen müssen. Legen Sie in solchen Fällen auf fest isExactMatchRequiredtrue.

Wenn isExactMatchRequired nicht angegeben ist, wird standardmäßig verwendet false. Für die title -Eigenschaft ist beispielsweise kein exakter Abgleich erforderlich. Es wird basierend auf den Sprachregeln des Elementinhalts tokenisiert:

• Die title: Contoso Title Abfrage gibt Elemente zurück, die entweder Contoso oder Title im Titel enthalten.

Semantische Bezeichnungen

Eine semantische Bezeichnung ist ein bekanntes Von Microsoft veröffentlichtes Tag, das Sie einer Eigenschaft in Ihrem Schema zuweisen können. Beim Erstellen eines benutzerdefinierten Copilot-Connectors mit dem Microsoft Graph-API ist das Anwenden von semantischen Bezeichnungen unerlässlich. Diese Bezeichnungen helfen Microsoft 365 Copilot und Microsoft Search, die Bedeutung und Rolle der einzelnen Eigenschaften zu verstehen und die Suche, Zusammenfassung und die allgemeine Benutzererfahrung zu verbessern.

Sie können semantische Bezeichnungen mithilfe der Graph-API oder über die Seite Eigenschaftenbezeichnungen zuweisen, wenn Sie das SDK verwenden. Bezeichnungen bieten eine semantische Bedeutung und ermöglichen es Ihren Connectordaten, sich nahtlos in Microsoft 365-Umgebungen zu integrieren.

Beispielsweise können verschiedene Projektverwaltungstools (z. B. JIRA, Azure DevOps, Asana) unterschiedliche Begriffe für den Benutzer verwenden, der ein Arbeitselement erstellt hat, z owner. B. , ownedByoder assignedTo. Wenn Ihre Eigenschaft einen ähnlichen Zweck erfüllt, können Sie die createdBy semantische Bezeichnung zuweisen.

Sie können Ihren Quelleigenschaften mithilfe der Graph-API oder auf der Seite Eigenschaftenbezeichnungen zuweisen , während Sie sdk verwenden, semantische Bezeichnungen zuweisen. Bezeichnungen bieten eine semantische Bedeutung und ermöglichen es Ihnen, Ihre Connectordaten in Microsoft 365-Umgebungen zu integrieren.

Bewährte Vorgehensweisen:

• Fügen Sie so viele Bezeichnungen hinzu, wie relevant sind, aber stellen Sie sicher, dass sie genau zugeordnet sind.
• Weisen Sie einer Eigenschaft keine Bezeichnung zu, wenn sie ihrem Zweck nicht entspricht. Falsche Zuordnungen beeinträchtigen die Erfahrung.

Die title Bezeichnung ist die wichtigste. Wenn Sie dieser Bezeichnung eine Eigenschaft zuweisen, kann Ihre Verbindung an der Ergebnisclusteroberfläche teilnehmen. Auch wenn nicht alle Bezeichnungen verwendet werden müssen, stellen Sie sicher, dass die von Ihnen zugewiesenen Bezeichnungen aussagekräftig und korrekt sind.

Relevanz

Das Anwenden genau zugeordneter semantischer Bezeichnungen verbessert die Auffindbarkeit Ihrer Inhalte durch die Suche. Microsoft empfiehlt, so viele der folgenden Bezeichnungen wie möglich zu definieren, die in absteigender Reihenfolge ihrer Auswirkungen auf die Ermittlung aufgeführt sind:
title, lastModifiedDateTime, lastModifiedBy, url, fileName und fileExtension.

Stellen Sie sicher, dass Ihre Bezeichnungszuordnungen korrekt sind. Das Zuweisen einer Bezeichnung zu einer Eigenschaft, die große Inhalte enthält, kann die Suchlatenz erhöhen und ergebnisse verzögern.

Ranghinweise

Ranghinweise können auf Texteigenschaften angewendet werden, die:

• Sind durchsuchbar
• Sind semantischen Bezeichnungen nicht zugeordnet

Ranghinweise helfen dabei, bestimmte Eigenschaften in Suchergebnissen zu priorisieren. Sie können deren Wichtigkeit im Microsoft 365 Search-Verwaltungsportal von "Standard " auf "Sehr hoch " festlegen. Diese Hinweise werden zusammen mit anderen Elementattributen verwendet, um die relevantesten Ergebnisse zurückzugeben.

So konfigurieren Sie Ranghinweise:

1. Wechseln Sie im Microsoft 365-Verwaltungsportal zur Registerkarte Suche und Intelligenz .
2. Wählen SieAnpassungs-Relevanzoptimierung> aus.

3. Wählen Sie unter Relevanzoptimierungdie Option Details> anzeigenBewertungshinweise konfigurieren aus.

4. Ändern Sie die Wichtigkeitsgewichtungen für verfügbare Quelleigenschaften.

Standardergebnistypen

Semantische Bezeichnungen beeinflussen auch, wie Standardergebnistypen generiert werden. Durch das Zuweisen der title Bezeichnungen und content wird mindestens sichergestellt, dass ein Ergebnistyp für Ihre Verbindung erstellt wird.

Ein Standardergebnistyp mit title und ein Ergebnisausschnitt.

Um die Standardergebniserfahrung zu verbessern, definieren Sie ggf. die folgenden Bezeichnungen (in aufsteigender Reihenfolge der Auswirkung):
title, url, lastModifiedBy, lastModifiedDateTime, fileName und fileExtension.

Überprüfungsprüfliste zum Zuweisen von Bezeichnungen:

• Eigenschaften, die Bezeichnungen zugewiesen sind, müssen als abrufbar gekennzeichnet werden.
• Der Datentyp der Eigenschaft muss mit dem erwarteten Typ für die Bezeichnung übereinstimmen.
• Jede Bezeichnung sollte genau einer Eigenschaft zugeordnet werden.

Aliases

Aliase sind Anzeigenamen, die Eigenschaften zugewiesen sind. Sie werden in Abfragen und in einschränkungsfähigen Eigenschaftenfiltern verwendet, um die Benutzerfreundlichkeit und Abfrageflexibilität zu verbessern.

Hier sind einige Beispiele aus der Praxis:

Bewährte Methoden für Aliase:

• Verwenden Sie Aliase für allgemeine Synonyme oder domänenspezifische Begriffe.
• Vermeiden Sie übermäßig generische oder mehrdeutige Aliase.
• Halten Sie Aliase kurz und intuitiv.

Content-Eigenschaft

Das Microsoft Copilot Connectorschema unterstützt eine Standardeigenschaft namens content. Sie müssen es nicht wie andere Eigenschaften (z. B. Titel, Tags usw.) im Schema definieren. Stattdessen ist es direkt in der Elementnutzlast enthalten , wenn Sie Daten erfassen.

Das Microsoft Copilot Connectorschema enthält eine integrierte content Eigenschaft. Im Gegensatz zu anderen Eigenschaften (z title . B. oder tags) müssen Sie sie nicht im Schema definieren. Stattdessen ist es während der Datenerfassung direkt in der Elementnutzlast enthalten .

Die content -Eigenschaft lautet:

• Semantisch für die Textsuche indiziert.
• Wird verwendet, um dynamische Codeausschnitte in Suchergebnissen zu generieren.
• Verfügbar für Copilot für Zusammenfassung und semantisches Verständnis.

Bewährte Methoden für die Verwendung der Inhaltseigenschaft:

• Fügen Sie der content Eigenschaft alle unstrukturierten Daten hinzu, damit Copilot semantische Suche und Abfragen effektiv abgleichen kann.
• Schließen Sie für unstrukturierte inhalte oder Freiforminhalte Eigenschaften wie summary, comment, rootCauseund description in das content Feld ein.
• Behalten Sie diese Eigenschaften nur dann als separate abrufbare Felder bei , wenn ihr vollständiger Wert auf der Benutzeroberfläche angezeigt werden muss.
• Sie können mehrere Eigenschaften (z. B. , description) an das Feld anfügen, summaryum das content semantische Verständnis zu erweitern.

Ein Beispiel dafür, wie die content Eigenschaft beim Erfassen von Daten verwendet wird:

{ 
"@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" 
} 
}

Deklarative Agents und Eigenschaftenbeschreibungen

Wenn Sie einen deklarativen Agent (DA) verwenden, sollten Sie Eigenschaftenbeschreibungen aus Ihrem Copilot-Connectorschema in den Für den Agent bereitgestellten Anweisungssatz einschließen. Dies hilft dem DA dabei, Folgendes zu verstehen:

• Die semantische Bedeutung jeder Eigenschaft
• Verweisen und Zusammenfassen der Daten
• Reagieren auf Benutzerabfragen mithilfe des indizierten Inhalts

Definieren Sie klare, wohlgeformte Beschreibungen für alle Eigenschaften. Eine gute Beschreibung sollte Folgendes erklären:

• Was die -Eigenschaft darstellt
• Alternative Namen oder Begriffe
• Wann und wie es verwendet werden sollte

Funktionen für die Schemaaktualisierung

In diesem Abschnitt werden die Updatefunktionen der Schema-API beschrieben.

Hinzufügen einer Eigenschaft

Sie können Ihrem Schema eine neue Eigenschaft hinzufügen. Die erneute Erfassung ist zwar nicht erforderlich, wird jedoch empfohlen. Wenn Sie eine Eigenschaft hinzufügen, schließen Sie alle erforderlichen Suchattribute ein.

Hinzufügen oder Entfernen einer Suchfunktion

Sie können Suchattribute für eine Eigenschaft ändern. Aber:

• Sie können keinverfeinerungsfähiges Attribut als Teil einer Schemaaktualisierung hinzufügen.
• Eine Eigenschaft kann nicht sowohl durchsuchbar als auch verfeinernd sein.

Das Hinzufügen oder Entfernen einer Suchfunktion erfordert eine erneute Erfassung.

Hinzufügen oder Entfernen eines Alias

Sie können Aliase für die Verwendung in Suchabfragen hinzufügen oder entfernen. Aliase, die vom System für verfeinerbare Eigenschaften automatisch erstellt wurden, können jedoch nicht entfernt werden.

Hinzufügen oder Entfernen einer semantischen Bezeichnung

Sie können semantische Bezeichnungen zuweisen oder entfernen. Diese Bezeichnungen beeinflussen Erfahrungen wie Relevanz und Viva Topics.

Nächste Schritte

• Hinzufügen von Elementen zur Verbindung
• Lesen Sie die API-Referenz zu Copilot-Connectors.
• Durchsuchen benutzerdefinierter Typen (externalItem)