Erstellen von Registerkarten mit adaptiven Karten

Artikel
12/28/2023

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:

Screenshot: Beispiel für die adaptive Karte, die in Registerkarten gerendert wird

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.yourwebsite.com",
    "privacyUrl": "https://contoso.yourwebsite.com/privacy.html",
    "termsOfUseUrl": "https://contoso.yourwebsite.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.yourwebsite.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/fetchAnforderung

// 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/fetchAntwort

// 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-200Tab-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/submitAnforderung

// 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/submitAntwort

//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/fetchAnforderung

// 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/fetchAntwort

// 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/submitAnforderung

// 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/submitTab-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/fetchAufrufen 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 der title-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.

Screenshot: Beispiel für den Authentifizierungsflow für adaptive Kartenregisterkarten

-tab/fetchAuthentifizierungsantwort

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.

Nächster Schritt

Entpacken von Registerkartenlinks und Stageview

Erstellen von Registerkarten mit adaptiven Karten

Voraussetzungen

Änderungen am App-Manifest

Aufrufaktivitäten

Abrufen einer adaptiven Karte zum Rendern auf einer Registerkarte

Behandeln von Übermittlungen von adaptiven Karte

Grundlegendes zum Dialogworkflow

`task/fetch`-Aufruf

`task/submit`-Aufruf

Authentifizierung

`tab/fetch`-Authentifizierungsdatenfluss

Beispiel

Codebeispiel

Schrittweise Anleitung

Nächster Schritt

Siehe auch

Feedback

Zusätzliche Ressourcen

Erstellen von Registerkarten mit adaptiven Karten

Voraussetzungen

Änderungen am App-Manifest

Aufrufaktivitäten

Abrufen einer adaptiven Karte zum Rendern auf einer Registerkarte

Behandeln von Übermittlungen von adaptiven Karte

Grundlegendes zum Dialogworkflow

task/fetch-Aufruf

task/submit-Aufruf

Authentifizierung

tab/fetch-Authentifizierungsdatenfluss

Beispiel

Codebeispiel

Schrittweise Anleitung

Nächster Schritt

Siehe auch

Feedback

Zusätzliche Ressourcen

`task/fetch`-Aufruf

`task/submit`-Aufruf

`tab/fetch`-Authentifizierungsdatenfluss