Richtlinien zum Erstellen oder Aktualisieren eines Nachrichtenerweiterungs-Plug-Ins für Copilot für Microsoft 365
Wichtig
- Plug-Ins für Microsoft Copilot für Microsoft 365 befinden sich in der Vorschauphase und funktionieren nur in Microsoft 365 Chat in Microsoft Teams.
- Stellen Sie sicher, dass Copilot für Microsoft 365 für Ihre organization verfügbar ist. Sie haben zwei Möglichkeiten, eine Entwicklerumgebung für Copilot zu erhalten:
- Ein Sandbox-Microsoft 365-Mandant mit Copilot (verfügbar in der eingeschränkten Vorschau über die TAP-Mitgliedschaft).
- Eine Unternehmenskunden-Produktionsumgebung mit Microsoft Copilot für Microsoft 365 Lizenzen.
Microsoft 365-Plug-Ins ermöglichen die Integration in verschiedene Microsoft 365-Produkte wie Teams und Outlook. Die Integration hilft Benutzern, Inhalte in externen Systemen zu suchen oder zu erstellen. Nachrichtenerweiterungs-Plug-Ins ermöglichen Microsoft Copilot für Microsoft 365 die Interaktion mit APIs anderer Software und Dienste über einen Bot. Mit Copilot für Microsoft 365 haben Sie folgende Möglichkeiten:
- Search nach den neuesten Informationen oder Datensätzen. Beispielsweise das neueste Incidentticket oder die Umfrageergebnisse.
- Zusammenfassen von Informationen basierend auf mehreren Datensätzen Fassen Sie beispielsweise alle Incidenttickets im Zusammenhang mit dem Projekt Northwind zusammen.
Es wird empfohlen, dass Sie Ihre vorhandenen Nachrichtenerweiterungen erstellen oder aktualisieren, um deren Nützlichkeit und Benutzerfreundlichkeit in Copilot für Microsoft 365 zu maximieren. Nachrichtenerweiterungen müssen mindestens einen Suchbefehl unterstützen, da Copilot für Microsoft 365 sie als Fähigkeiten erkennt, die sie im Namen des Benutzers ausführen können. Darüber hinaus müssen Ihre Erweiterungen die in diesem Artikel beschriebenen Standards für Compliance, Leistung, Sicherheit und Benutzerfreundlichkeit erfüllen.
Obligatorische Anforderungen
Zu den Anforderungen für das Erstellen von Nachrichtenerweiterungs-Plug-Ins für Copilot für Microsoft 365 gehören:
Definieren von Beschreibungen
Eine gute Beschreibung bietet eine klare und präzise Zusammenfassung der Features der App und ermöglicht es Copilot für Microsoft 365, Suchvorgänge effizient zu ermitteln und auszuführen. Wenn ein Benutzer den App-Namen zusammen mit einem Verb eingibt, z. B. "Contoso-Tickets suchen", muss das Nachrichtenerweiterungs-Plug-In über Copilot für Microsoft 365 (M365 Chat) aufgerufen werden.
Stellen Sie sicher, dass Sie die in der folgenden Tabelle aufgeführten Beschreibungsrichtlinien einhalten:
| Aktion | Grund |
|---|---|
|
Anti-Compete: Vermeiden Sie die Verwendung des Namens eines anderen Plug-Ins in kurzen und langen Beschreibungen. |
|
|
Verantwortungsvolle KI: Vermeiden Sie unangemessene oder anstößige Schlüsselwörter. |
|
|
Eingabeaufforderungsinjektionen: Stellen Sie sicher, dass die Beschreibungen Copilot nicht anleiten, Aktionen zu ergreifen, die die normale Funktion der Anwendung umgehen. Darüber hinaus darf die Beschreibung keine Symbole oder Text enthalten, die angeben, dass sie als Code für die Eingabeaufforderung verwendet werden kann. Vermeiden Sie die Verwendung von Ausdrücken, Funktionen und Code, die eine App wiederholt aufrufen. |
App-Beschreibung
Lange und kurze App-Beschreibungen müssen klar sein und den App-Bereich definieren. Um eine App als Plug-In in Copilot für Microsoft 365 zu rendern, ändern Sie die App-Beschreibung so, dass sie den folgenden Plug-In-Anforderungen entspricht:
- Eine lange Beschreibung muss die Funktionalität und Verwendung des Nachrichtenerweiterungs-Plug-Ins in Copilot für Microsoft 365 klar erklären. Verwenden Sie beispielsweise contoso cloud in Copilot für Microsoft 365, um Ihre Aufgaben zu durchsuchen und zusammenzufassen.
- Eine kurze Beschreibung muss die Funktionalität der App in einer natürlichen Sprache kurz beschreiben und kann den Namen der App enthalten.
Die folgende Tabelle enthält die kurzen Beschreibungsbeispiele für jede Kategorie:
Beschreibung: Erstellen, Suchen, Anzeigen von Tickets, Fehlern und Projekten.
Beispiel für eine App-Beschreibung:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
"version": "1.0.0",
"manifestVersion": "1.13",
"id": "2bxxxxc5-5xxx-4xxx-aXXX-94xxxx8919e5",
"name": {
"short": "Tasks",
"full": "Contoso Tasks"
},
"description": {
"short": "Create, search, view tickets, bugs, and projects",
"full": "Contoso Tasks makes it easy to stay organized. Create, assign, and track tasks individually or collaboratively with your team, and see everything come together in one place."
},
beschreibung des befehls Search
Die Befehlsbeschreibung ordnet die Benutzerabsicht und -äußerung dem Suchbefehl innerhalb eines Plug-Ins zu und muss auf der Grundlage der Analyse der Benutzerabsicht und der Schlüsselwörter erstellt werden. Search Befehlsbeschreibungen müssen:
- Konzentrieren Sie sich darauf, was und wie der Befehl sucht (detaillierte Liste) in natürlicher Sprache.
- Schließen Sie ggf. Verben und Synonyme ein.
- Konzentrieren Sie sich auf Schlüsselwörter, die wahrscheinlich in der Suchfunktion Ihrer nativen Apps verwendet werden.
Semantische Beschreibung
Die semanticDescription-Eigenschaft wird verwendet, um eine detaillierte Beschreibung eines Befehls für Copilot für Microsoft 365 bereitzustellen. Die semantische Beschreibung für Befehle unterstützt bis zu 5.000 Zeichen und wird nicht auf der Benutzeroberfläche angezeigt. Wenn die semanticDescription Eigenschaft leer bleibt, verwendet Copilot für Microsoft 365 die Informationen im description Feld. Beim Schreiben eines semanticDescriptionmüssen Sie Informationen zu den erwarteten Werten, Grenzwerten und Bereichen für den Befehl angeben.
Die semanticDescription -Eigenschaft ist kein Pflichtfeld. Wenn Sie jedoch im App-Manifest hinzufügen semanticDescription , gelten die vorhandenen Validierungsprüfungen für Kurz-, Parameter- und Befehlsbeschreibungen auch für semantische Beschreibungen.
Es wird empfohlen, die folgenden Richtlinien für die semantische Beschreibung zu lesen, um die Wahrscheinlichkeit zu erhöhen, dass Ihre App den Microsoft Teams Store-Übermittlungsprozess besteht:
- Vermeiden Sie Anweisungsausdrücke wie "wenn der Benutzer X sagt", "ignorieren", "löschen", "zurücksetzen", "neue Anweisungen", "Antwort fett" oder "Drucken Sie nichts". [Obligatorische Korrektur]
- Vermeiden Sie URLs, Emojis oder ausgeblendete Zeichen wie hexadezimale, binäre oder unkonventionelle Symbole. [Obligatorische Korrektur]
- Vermeiden Sie Grammatik- und Interpunktionsfehler. [Obligatorische Korrektur]
- Vermeiden Sie eine zu ausführliche, blumige oder Marketingsprache. [Vorgeschlagene Korrektur]
- Vermeiden Sie Ansprüche der Superlative wie "#1", "amazing" oder "best". [Vorgeschlagene Korrektur]
In der folgenden Tabelle sind die Beispiele für Befehle und semantische Beschreibungen für jede Kategorie aufgeführt:
Beschreibung: Search für Aufgaben mit hoher Priorität im Zusammenhang mit Northwind, die morgen fällig sind.
Beispiel für eine Befehlsbeschreibung:
"commands": [
{
"id": "Search",
"type": "query",
"title": "Tasks",
"description": "Search for high priority tasks related to Northwind that are due tomorrow.",
"SemanticDescription": "Search for issues, epics, stories, tasks, sub tasks, bugs + additional details."
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
Parameterbeschreibung
Jeder unterstützte Nachrichtenerweiterungsbefehl verfügt über eine entsprechende "parameters"-Eigenschaft, die bis zu fünf Parameter unterstützt, und der erste Parameter muss in der Suchleiste der Nachrichtenerweiterung angezeigt werden. Ein Parameter muss über eine gute Beschreibung verfügen, die eine Kombination aus zulässigen Parametern, Enumerationen, Akronymen und Ausgabeformat enthalten muss.
Die semanticDescription-Eigenschaft wird verwendet, um eine detaillierte Beschreibung eines Befehls für Microsoft Copilot bereitzustellen. Die semantische Beschreibung für Parameter unterstützt bis zu 2.000 Zeichen und wird nicht auf der Benutzeroberfläche angezeigt. Wenn die semanticDescription Eigenschaft leer bleibt, verwendet Copilot die Informationen im description Feld. Beim Schreiben eines semanticDescriptionmüssen Sie Informationen zu den erwarteten Werten, Grenzwerten und Bereichen für den Befehl angeben.
Eine gute Parameterbeschreibung erläutert die Anforderungen des Systems in einer natürlichen Sprache mit Ausgabeformat. Im Folgenden finden Sie einige Beispiele für einfache und erweiterte Suchanforderungen für jede Kategorie:
Einfache Suche: Search für Aufgaben im Zusammenhang mit Northwind.Erweiterte Suche: Search für Aufgaben mit hoher Priorität im Zusammenhang mit Northwind, die morgen fällig sind.
Beispiel für eine Parameterbeschreibung:
"parameters": [
{
"name": "Name",
"title": "Project or Task Name",
"description": "Project name or task name as keyword.",
"inputType": "text"
},
{
"name": "Time",
"title": "Time",
"description": "Date or number of days for which you need tasks for.",
"semanticDescription": "Date or number of days for which you need tasks for. Output: Number",
"inputType": "text"
},
{
"name": "Priority",
"title": "Priority",
"description": "Priority of tasks.",
"semanticDescription": "Priority of tasks. Acceptable values are high, medium, low, NA",
"inputType": "text"
}]
Zusammengesetzte Äußerungen
Hinweis
Search über das Dialogfeld (in TeamsJS v1.x als Aufgabenmodul bezeichnet) wird in M365 Chat nicht unterstützt.
Für M365 Chat muss eine suchbasierte Nachrichtenerweiterung mehr als drei eindeutige zusammengesetzte Äußerungen unterstützen, um ein umfassendes Abrufen genauer Informationen durchzuführen. Um zusammengesetzte Äußerungen zu aktivieren, müssen Sie den Suchbereich erweitern, um drei oder mehr Suchparameter zu behandeln, indem Sie das App-Manifest (zuvor als Teams-App-Manifest bezeichnet) aktualisieren und Folgendes sicherstellen:
Aktualisieren Sie Ihren Webdienst, um die Suche basierend auf mehreren Parametern zu unterstützen. Weitere Informationen zum Reagieren auf Benutzeranforderungen finden Sie unter Antwort auf suchbefehl.
Copilot für Microsoft 365 möglicherweise eine leere Zeichenfolge oder einen NULL-Wert für Parameter übergeben, die nicht Teil der Benutzeräußerung sind, aktualisieren Sie Ihren Webdienst, um die Parameter zu behandeln.
Eine Nachrichtenerweiterung unterstützt bis zu 10 Befehle (9 verwendbar), und jeder Befehl verfügt über eine entsprechende
parametersEigenschaft, die bis zu 5 Parameter unterstützt.
Der folgende Code ist ein Beispiel für mehrere Parameter, die im App-Manifest definiert sind:
"commands": [
{
"id": "inventorySearch",
"context": [
"compose",
"commandBox"
],
"description": "Search products by name, category, inventory status, supplier location, stock level",
"title": "Product inventory",
"type": "query",
"parameters": [
{
"name": "productName",
"title": "Product name",
"description": "Enter a product name here",
"inputType": "text"
},
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category of the product",
"inputType": "text"
},
{
"name": "inventoryStatus",
"title": "Inventory status",
"description": "Enter what status of the product inventory. Possible values are 'in stock', 'low stock', 'on order', or 'out of stock'",
"inputType": "text"
},
{
"name": "supplierCity",
"title": "Supplier city",
"description": "Enter the supplier city of product",
"inputType": "text"
},
{
"name": "stockQuery",
"title": "Stock level",
"description": "Enter a range of integers such as 0-42 or 100- (for >100 items). Only use if you need an exact numeric range.",
"inputType": "text"
}
]
},
{
"id": "discountSearch",
"context": [
"compose",
"commandBox"
],
"description": "Search for discounted products by category",
"title": "Discounts",
"type": "query",
"parameters": [
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category to find discounted products",
"inputType": "text"
}
]
},
{
"id": "revenueSearch",
"context": [
"compose",
"commandBox"
],
"description": "Find products based on their revenue/period",
"title": "Revenue",
"type": "query",
"parameters": [
{
"name": "revenueRange",
"title": "Revenue range",
"description": "Enter 'high' or 'low' or enter a range of integers such as 0-10000 or 5000- using this exact format",
"inputType": "text"
}
]
}
]
Die Suchparameter müssen über gute Beschreibungen mit zulässigen Parametern, Enumerationen, Akronymen und Ausgabeformat verfügen. Weitere Informationen und Beispiele finden Sie unter Parameterbeschreibung.
Beispieleingabeaufforderungen
Die samplePrompts -Eigenschaft führt Benutzer zur Verwendung der verschiedenen Plug-Ins in Copilot. Copilot verwendet die Beispieleingabeaufforderungen, um die Eingabeaufforderungen für den Benutzer anzuzeigen. Die Eingabeaufforderungen müssen an verschiedene Gebietsschemas angepasst und über verschiedene Befehle hinweg klar sein. Beispieleingabeaufforderungen sind in den folgenden Bereichen in Copilot für Microsoft 365 verfügbar:
- First Run Experience (FRE): Wenn ein Benutzer ein Plug-In zum ersten Mal installiert oder aktiviert.
- Eingabeaufforderungsbibliothek oder Copilot Lab: Wenn ein Benutzer Hilfe bei Eingabeaufforderungen sucht.
- Plug-In-Vorschläge: Um Benutzer zu besseren Äußerungen zu führen.
Hinweis
- Wenn das App-Manifest die
samplePrompts-Eigenschaft nicht angibt, werden die Eingabeaufforderungen nicht angezeigt. - Die
samplePrompts-Eigenschaft ist für die App-Überprüfung während des App-Übermittlungsprozesses obligatorisch. - Wenn Sie mehrere Befehle für Ihre App definieren, werden dem Benutzer maximal drei Eingabeaufforderungen (eine von jedem der drei obersten Befehle) angezeigt. Die Eingabeaufforderungen werden rotiert, um dem Benutzer verschiedene Eingabeaufforderungen für verschiedene Befehle zur Verfügung zu stellen.
Es wird empfohlen, diese Richtlinien zu befolgen, um die Wahrscheinlichkeit zu erhöhen, dass Ihre App den Microsoft Teams Store-Übermittlungsprozess besteht:
- Ein Plug-In muss mindestens drei Eingabeaufforderungen und maximal fünf Eingabeaufforderungen für jeden Befehl haben.
- Jede Eingabeaufforderung darf 128 Zeichen nicht überschreiten.
- Zwei Befehle innerhalb desselben Plug-Ins dürfen nicht über identische Eingabeaufforderungen verfügen.
- Beispieleingabeaufforderungen müssen generisch sein und dürfen keine benutzerdefinierten Verweise enthalten. Beispiel: Projektnamen und Vorgangsname.
- Alle Beispielaufforderungen müssen funktionsfähig sein und Antworten zurückgeben.
- Die Eingabeaufforderung muss für die Befehle relevant sein.
Der folgende Code ist ein Beispiel für die samplePrompts -Eigenschaft im App-Manifest:
"composeExtensions": [
{
"canUpdateConfiguration": true,
"botId": "bxxxxxx5-xxxx-xxxx-xxxx-4xxxxxx16599",
"commands": [
{
"id": "orders",
"title": "Orders",
"context": [
"Commandbox",
"Compose"
],
"description": "Search for orders",
"semanticDescription": "Search for orders",
"samplePrompts": [
{
"text": "Search for all orders"
},
{
"text": "Search for orders related to Contoso"
},
{
"text": "Search for all pending orders"
},
{
"text": "Search for all completed ordered for Fabrikam"
}
]
}
]
}
]
Antwort für adaptive Karten
Nachrichtenerweiterungen reagieren auf eine Benutzereingabe mit einer adaptiven Karte. Eine adaptive Karte für ein Nachrichtenerweiterungs-Plug-In muss effektiv funktionieren, reich sein und die folgenden Anforderungen erfüllen:
Die Antwort für adaptive Karten muss Inhalte für adaptive Karten enthalten und eine Vorschau Karte Informationen als Teil derselben Vorlage enthalten. [Obligatorisch]
Beispiel für eine Antwortvorlage für adaptive Karten
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "${companyName}", "size": "Medium", "wrap": true, "style": "heading" }, { "type": "TextBlock", "text": "${stockExchange} ${stockSymbol}", "isSubtle": true, "spacing": "None", "wrap": true }, { "type": "TextBlock", "text": "${formattedDate} ${formattedTime}", "wrap": true } ] }, { "type": "Container", "spacing": "None", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "width": "stretch", "items": [ { "type": "TextBlock", "text": "${currentPrice} ", "size": "ExtraLarge", "wrap": true }, { "type": "TextBlock", "text": "${priceChange} ${percentChange}", "color": "${changeColor}", "spacing": "None", "wrap": true } ] }, { "type": "Column", "width": "auto", "items": [ { "type": "FactSet", "facts": [ { "title": "Open", "value": "${openPrice} " }, { "title": "High", "value": "${highPrice} " }, { "title": "Low", "value": "${lowPrice} " } ] } ] } ] } ] } ], "previewCard": { "contentType": "application/vnd.microsoft.card.hero", "content": { "title": "${companyName}", "text": "${stockSymbol}" } } }Neben dem App-Logo, dem Titel, der Miniaturansicht und dem Titel der Informationen müssen die Daten in der adaptiven Karte mindestens zwei Informationen darstellen. Sie können die Felder anhand der am häufigsten durchsuchten Attribute identifizieren, z. B. geänderte Daten, Autor, status und Flags. [Obligatorisch]
Adaptive Karten müssen in Desktop, Web und Mobilgeräten (iOS und Android) vorzeigbar sein. [Obligatorisch]
Eine adaptive Karte muss mindestens eine Aktionsschaltfläche, aber nicht mehr als vier Aktionsschaltflächen enthalten. [Obligatorisch]
Hinweis
Aktionstypen
imBackmessageBackwerden in einem Datenobjekt nicht unterstützt.Folgende Aktionstypen werden empfohlen:
Action.OpenUrl: Öffnet eine angegebene URL aus der Karte.Action.ToggleVisibility: Zeigt ein oder mehrere Elemente im Karte an oder blendet es aus.Action.Execute: Erfasst die Eingabefelder und sendet sie als Anforderung an Ihren Botdienst.Action.Submit: Öffnet ein Dialogfeld oder eine Stageview mit Typaufruf im Datenobjekt.
Wenn ein Benutzer Informationen auf dem Karte über das Dialogfeld, die Stageview oder direkt aus dem Karte ändern kann, empfehlen wir die adaptive Karte, um universelle Aktionen und automatische Aktualisierungen zu unterstützen. [Empfohlen]
Adaptive Karten müssen eine URL als Teil der Metadaten enthalten, sodass Karten problemlos von einem Hub zu einem anderen kopiert werden können. [Empfohlen]
Abgesehen von Miniaturansichten muss jedes Bild in einer adaptiven Karte einen Alternativtext aufweisen. [Empfohlen]
Technische Anforderungen
Damit ein Plug-In überprüft, aufgerufen und nahtlos funktioniert, stellen Sie sicher, dass es die folgenden Kriterien erfüllt:
| Kriterien | Erfüllung |
|---|---|
| Manifestversion | Die App-Manifestversion muss 1.13 oder höher sein. [Obligatorisch] |
| Microsoft 365-Kanal | Damit Benutzer mit Ihrer Nachrichtenerweiterung aus Outlook interagieren können, müssen Sie Ihrem Bot den Microsoft 365-Kanal hinzufügen. Weitere Informationen finden Sie unter Hinzufügen eines Microsoft 365-Kanals. [Obligatorisch] |
| Antwortzeit | Die Antwortzeit darf 99 Prozent, 5 Sekunden für 75 Prozent und 2 Sekunden für 50 Prozent nicht überschreiten. [Obligatorisch] |
| Zuverlässigkeit | Apps müssen eine Verfügbarkeit von 99,9 % beibehalten. Wenn Microsoft 365 Chat instance ein Plug-In 1.000-mal aufruft, muss es 999-mal eine sinnvolle Antwort geben. [Obligatorisch] |
| NullRegressionen | Wenn Sie Ihre App zur Überprüfung erneut übermitteln müssen, darf die vorhandene Nachrichtenerweiterungsfunktion, die zuvor funktionierte, nicht unterbrochen werden. Diese Anforderung gilt nur für IsV-Apps (Independent Software Vendor) und nicht für Apps, die für Ihre organization erstellt wurden. [Obligatorisch] |
| Einmaliges Anmelden (Single Sign-On, SSO) | Aktualisieren Sie ggf. Ihre Microsoft Entra ID App-Registrierung für einmaliges Anmelden. [Empfohlen] |
| Inhaltssicherheitsrichtlinie | Ändern Sie ggf. die Header ihrer Inhaltssicherheitsrichtlinie. [Empfohlen] |
Wichtig
Aktualisieren Sie ggf. die Header ihrer Inhaltssicherheitsrichtlinie und X-Frame-Options entsprechend den Headern für Die Inhaltssicherheitsrichtlinie konfigurieren.
Codebeispiele
| Beispielname | Beschreibung | TypeScript |
|---|---|---|
| Northwind-Bestandsnachrichtenerweiterung | In diesem Beispiel wird veranschaulicht, wie Sie eine Teams-Nachrichtenerweiterung als Plug-In in Microsoft Copilot für Microsoft 365 verwenden. | Anzeigen |
Siehe auch
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für