Erstellen von Registerkarten mit adaptiven Karten
Warnung
Registerkarten für adaptive Karten sind im neuen Teams-Client nicht verfügbar. Der klassische Teams-Client wird voraussichtlich bis zum 31. März 2024 veraltet sein. Wenn Ihre App Registerkarten mit adaptiven Karten verwendet, wird empfohlen, die Registerkarte als webbasierte Registerkarte neu zu erstellen. Weitere Informationen finden Sie unter Erstellen von Registerkarten für Teams.
Bei der Entwicklung einer Registerkarte mithilfe der herkömmlichen Methode können die folgenden Probleme auftreten:
- Überlegungen zu HTML und CSS
- Langsame Ladezeiten
- iFrame-Einschränkungen
- Serverwartung und -kosten
Sie können Registerkarten für adaptive Karten in Teams erstellen. Anstatt Webinhalte in einen iFrame einzubetten, können Sie adaptive Karten auf einer Registerkarte rendern. Während das Front-End mit adaptiven Karten gerendert wird, wird das Back-End von einem Bot unterstützt. Der Bot ist dafür verantwortlich, Anforderungen zu akzeptieren und mit der gerenderten adaptiven Karte angemessen zu reagieren.
Sie können Ihre Registerkarten mit den systemeigenen vorgefertigten Benutzeroberflächenbausteinen von Desktops, des Internets und von Mobilgeräte erstellen. In diesem Artikel erfahren Sie, welche Änderungen am App-Manifest vorgenommen werden müssen. In diesem Artikel wird auch beschrieben, wie die Aufrufaktivität Informationen auf der Registerkarte mit adaptiven Karten anfordert und sendet, und wie sich dies auf den Workflow des modalen Dialogs (in TeamsJS v1.x als Aufgabenmodul bezeichnet) auswirkt.
Die folgende Abbildung zeigt das Erstellen von Registerkarten mit adaptiven Karten auf Desktop- und Mobilgeräten:
Voraussetzungen
Bevor Sie beginnen, adaptive Karten zum Erstellen von Registerkarten zu verwenden, müssen Sie die folgenden Voraussetzungen erfüllen:
- Machen Sie sich mit der Botentwicklung, adaptiven Karten und modalen Dialogen in Teams vertraut.
- Führen Sie in Teams einen Bot für Ihre Entwicklung aus.
Änderungen am App-Manifest
Persönliche Apps, die Registerkarten rendern, müssen ein staticTabs
-Array in ihr App-Manifest einschließen. Registerkarten mit adaptiven Karten werden gerendert, wenn die contentBotId
-Eigenschaft in der staticTab
-Definition bereitgestellt wird. Statische Registerkartendefinitionen müssen entweder eine contentBotId
für die Spezifikation einer Registerkarte mit adaptiven Karten oder eine contentUrl
für die Spezifikation einer typischen gehosteten Webinhaltsregisterkarte enthalten.
Hinweis
Die contentBotId
-Eigenschaft ist in Manifestversion 1.9 oder höher verfügbar.
Geben Sie die contentBotId
-Eigenschaft mit dem botId
an, mit dem die Registerkarte mit adaptiven Karten kommunizieren muss. Die für die Registerkarte mit adaptiven Karten konfigurierte entityId
wird im tabContext
-Parameter jeder Aufrufanforderung gesendet und kann verwendet werden, um Registerkarten mit adaptiven Karten zu unterscheiden, die von demselben Bot unterstützt werden. Weitere Informationen zu anderen statischen Registerkartendefinitionsfeldern finden Sie unter Manifestschema.
Es folgt ein Beispielmanifest für ein Manifest einer Registerkarte mit adaptiven Karten:
{
"$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json",
"manifestVersion": "1.9",
"id": "00000000-0000-0000-0000-000000000000",
"version": "0.0.1",
"developer": {
"name": "Contoso",
"websiteUrl": "https://contoso.example.com",
"privacyUrl": "https://contoso.example.com/privacy.html",
"termsOfUseUrl": "https://contoso.example.com/terms.html"
},
"name": {
"short": "Contoso",
"full": "Contoso Home"
},
"description": {
"short": "Add short description here",
"full": "Add full description here"
},
"icons": {
"outline": "icon-outline.png",
"color": "icon-color.png"
},
"accentColor": "#D85028",
"configurableTabs": [],
"staticTabs": [
{
"entityId": "homeTab",
"name": "Home",
"contentBotId": "00000000-0000-0000-0000-000000000000",
"scopes": ["personal"]
},
{
"entityId": "moreTab",
"name": "More",
"contentBotId": "00000000-0000-0000-0000-000000000000",
"scopes": ["personal"]
}
],
"connectors": [],
"composeExtensions": [],
"permissions": ["identity", "messageTeamMembers"],
"validDomains": [
"contoso.example.com",
"token.botframework.com"
]
}
Aufrufaktivitäten
Die Kommunikation zwischen Ihrer Registerkarte mit adaptiven Karten und Ihrem Bot erfolgt über invoke
-Aktivitäten. Jede invoke
-Aktivität besitzt einen entsprechenden Namen. Verwenden Sie den Namen jeder Aktivität, um die einzelnen Anforderungen zu unterscheiden. In diesem Abschnitt werden die Aktivitäten tab/fetch
und tab/submit
behandelt.
Hinweis
- Bots müssen alle Antworten an die Dienst-URL senden. Die Dienst-URL wird als Teil der eingehenden
activity
-Nutzlast empfangen. - Die Größe der Aufrufnutzlast wurde auf 80 KB erhöht.
Abrufen einer adaptiven Karte zum Rendern auf einer Registerkarte
tab/fetch
ist die erste Aufrufanforderung, die Ihr Bot empfängt, wenn ein Benutzer eine Registerkarte mit adaptiven Karten öffnet. Wenn Ihr Bot die Anforderung empfängt, sendet er entweder eine Tab-Fortsetzungsantwort oder eine Tab-Authentifizierungsantwort.
Die Fortsetzungsantwort enthält ein Array für Karten, das vertikal auf der Registerkarte in der Reihenfolge des Arrays gerendert wird.
Hinweis
Weitere Informationen zur Authentifizierungsantwort finden Sie unter Authentifizierung.
Der folgende Code enthält Beispiele für die tab/fetch
-Anforderung und -Antwort:
-tab/fetch
Anforderung
// tab/fetch POST request: agents/{botId}/invoke
{
"name": "tab/fetch",
"value: {
"tabContext": {
"tabEntityId": "{tab_entity_id}"
},
"context": {
"theme": "default"
}
},
"conversation": {
"id": "{generated_conversation_id}"
},
"imdisplayname": "{user_display_name}"
}
-tab/fetch
Antwort
// tab/fetch **continue** POST response:
{
"tab": {
"type": "continue",
"value": {
"cards": [
{
"card": adaptiveCard1,
},
{
"card": adaptiveCard2,
},
{
"card": adaptiveCard3
}
]
},
},
"responseType": "tab"
}
Behandeln von Übermittlungen von adaptiven Karte
Nachdem eine adaptive Karte auf der Registerkarte gerendert wurde, kann sie auf Benutzerinteraktionen reagieren. Diese Antwort wird von der tab/submit
-Aufrufanforderung verarbeitet.
Wenn ein Benutzer eine Schaltfläche auf der Registerkarte mit adaptiven Karten auswählt, wird die tab/submit
-Anforderung über die Action.Submit
-Funktion der adaptiven Karte an Ihren Bot mit den entsprechenden Daten ausgelöst. Die Daten der adaptiven Karte sind über die Dateneigenschaft der tab/submit
-Anforderung verfügbar. Sie erhalten eine der folgenden Antworten auf Ihre Anforderung:
- Eine HTTP-Statuscode-
200
-Antwort ohne Textkörper. Eine leere 200-Antwort führt dazu, dass der Client keine Aktion ausführt. - Die Standard-
200
Tab-Fortsetzungsantwort, wie in Abrufen der adaptiven Karte erläutert. Eine Tab-Fortsetzungsantwort löst den Client aus, um die gerenderte Registerkarte mit adaptiven Karten mit den adaptiven Karten, die im Kartenarray der Fortsetzungsantwort bereitgestellt werden, zu aktualisieren.
Der folgende Code enthält Beispiele für die tab/submit
-Anforderung und -Antwort:
-tab/submit
Anforderung
// tab/submit POST request: agents/{botId}/invoke:
{
"name": "tab/submit",
"value": {
"data": {
"type": "tab/submit",
//...<data properties>
},
"context": {
"theme": "default"
},
"tabContext": {
"tabEntityId": "{tab_entity_id}"
},
},
"conversation": {
"id": "{generated_conversation_id}"
},
"imdisplayname": "{user_display_name}"
}
-tab/submit
Antwort
//tab/fetch **continue** POST response:
{
"tab": {
"type": "continue",
"value": {
"cards": [
{
"card": adaptiveCard1,
},
{
"card": adaptiveCard2,
}
]
},
},
"responseType": "tab"
}
Grundlegendes zum Dialogworkflow
Modale Dialoge verwenden auch adaptive Karten zum Aufrufen task/fetch
von Anforderungen und task/submit
Antworten. Weitere Informationen finden Sie unter Verwenden von Dialogfeldern in Microsoft Teams-Bots.
Mit der Einführung der Registerkarte mit adaptiven Karten verändert sich die Art und Weise, wie der Bot auf eine task/submit
-Anforderung antwortet. Wenn Sie eine Registerkarte mit adaptiver Karte verwenden, antwortet der Bot auf die task/submit
Aufrufanforderung mit der Standardregisterkarte continue response und schließt das Dialogfeld. Die Registerkarte mit adaptiven Karten wird aktualisiert, indem die neue Liste der Karten gerendert wird, die im Antworttext der Registerkarte Fortsetzungsantwort bereitgestellt wird.
task/fetch
-Aufruf
Der folgende Code enthält Beispiele für die task/fetch
-Anforderung und -Antwort:
-task/fetch
Anforderung
// task/fetch POST request: agents/{botId}/invoke
{
"name": "task/fetch",
"value": {
"data": {
"type": "task/fetch"
},
"context": {
"theme": "default",
},
"tabContext": {
"tabEntityId": "{tab_entity_id}"
}
},
"imdisplayname": "{user_display_name}",
"conversation": {
"id": "{generated_conversation_id}"
}
}
-task/fetch
Antwort
// task/fetch POST response: agents/{botId}/invoke
{
"task": {
"value": {
"title": "Ninja Cat",
"height": "small",
"width": "small",
"card": {
"contentType": "application/vnd.microsoft.card.adaptive",
"content": adaptiveCard,
}
},
"type": "continue"
},
"responseType": "task"
}
task/submit
-Aufruf
Der folgende Code enthält Beispiele für die task/submit
-Anforderung und -Antwort:
-task/submit
Anforderung
// task/submit POST request: agent/{botId}/invoke:
{
"name": "task/submit",
"value": {
"data": {serialized_data_object},
"context": {
"theme": "default"
},
"tabContext": {
"tabEntityId": "{tab_entity_id}"
},
},
"conversation": {
"id": "{generated_conversation_id}"
},
"imdisplayname": "{user_display_name}",
}
-task/submit
Tab-Antworttyp
// tab/fetch **continue** POST response:
{
"task":{
"value": {
"tab": {
"type": "continue",
"value": {
"cards": [
{
"card": adaptiveCard1
},
{
"card": adaptiveCard2
}
]
}
}
},
"type": "continue"
},
"responseType": "task"
}
Authentifizierung
In den vorherigen Abschnitten haben Sie gesehen, dass die meisten Entwicklungsparadigma von den Dialoganforderungen und -antworten auf Registerkartenanforderungen und -antworten erweitert werden können. Bei der Behandlung der Authentifizierung folgt der Workflow für die Registerkarte mit adaptiven Karten dem Authentifizierungsmuster für Nachrichtenerweiterungen. Weitere Informationen finden Sie unter Hinzufügen einer Authentifizierung.
tab/fetch
-Anforderungen können entweder eine Fortsetzungs- oder eine Authentifizierungsantwort erhalten. Wenn eine tab/fetch
-Anforderung ausgelöst und eine Tab-Authentifizierungsantwort empfangen wird, wird dem Benutzer die Anmeldeseite angezeigt.
So rufen Sie einen Authentifizierungscode durch tab/fetch
Aufrufen ab
Öffnen Sie Ihre App. Die Anmeldeseite wird angezeigt.
Hinweis
Das App-Logo wird über die im App-Manifest definierte
icon
-Eigenschaft bereitgestellt. Der Titel, der angezeigt wird, nachdem das Logo in dertitle
-Eigenschaft definiert wurde, die im Text der Tab-Authentifizierungsantwort zurückgegeben wird.Wählen Sie Anmelden aus. Sie werden zu der Authentifizierungs-URL umgeleitet, die in der
value
-Eigenschaft des Textes der Authentifizierungsantwort bereitgestellt wird.Ein Popupfenster wird geöffnet. In diesem Popupfenster wird Ihre Webseite mithilfe der Authentifizierungs-URL gehostet.
Nachdem Sie sich angemeldet haben, schließen Sie das Fenster. Ein Authentifizierungscode wird an den Teams-Client gesendet.
Der Teams-Client stellt dann erneut die
tab/fetch
-Anforderung an Ihren Dienst aus, die den von Ihrer gehosteten Webseite bereitgestellten Authentifizierungscode enthält.
tab/fetch
-Authentifizierungsdatenfluss
Die folgende Abbildung bietet eine Übersicht über die Funktionsweise des Authentifizierungsdatenflusses für einen tab/fetch
-Aufruf.
-tab/fetch
Authentifizierungsantwort
Der folgende Code enthält ein Beispiel für eine tab/fetch
-Authentifizierungsantwort:
// tab/auth POST response (openURL)
{
"tab": {
"type": "auth",
"suggestedActions":{
"actions":[
{
"type": "openUrl",
"value": "https://example.com/auth",
"title": "Sign in to this app"
}
]
}
}
}
Beispiel
Der folgende Code zeigt ein Beispiel für eine erneute Anforderung:
{
"name": "tab/fetch",
"type": "invoke",
"timestamp": "2021-01-15T00:10:12.253Z",
"channelId": "msteams",
"serviceUrl": "https://smba.trafficmanager.net/amer/",
"from": {
"id": "{id}",
"name": "John Smith",
"aadObjectId": "00000000-0000-0000-0000-000000000000"
},
"conversation": {
"tenantId": "{tenantId}",
"id": "tab:{guid}"
},
"recipients": {
"id": "28:00000000-0000-0000-0000-000000000000",
"name": "ContosoApp"
},
"entities": [
{
"locale": "en-us",
"country": "US",
"platform": "Windows",
"timezone": "America/Los_Angeles",
"type": "clientInfo"
}
],
"channelData": {
"tenant": { "id": "00000000-0000-0000-0000-000000000000" },
"source": { "name": "message" }
},
"value": {
"tabContext": { "tabEntityId": "homeTab" },
"state": "0.43195668034524815"
},
"locale": "en-US",
"localTimeZone": "America/Los_Angeles"
}
Codebeispiel
Beispielname | Beschreibung | .NET | Node.js | Manifest |
---|---|---|---|---|
Anzeigen adaptiver Karten auf einer Teams-Registerkarte | Microsoft Teams-Beispielcode für die Registerkarte, der veranschaulicht, wie adaptive Karten in Teams angezeigt werden. | View | View | View |
Schrittweise Anleitung
Befolgen Sie die Schritt-für-Schritt-Anleitung zum Erstellen der Registerkarte mit adaptiven Karten.