Mit Universal-Aktionen für adaptive Karten arbeiten

  • Artikel

Universelle Aktionen für adaptive Karten bieten eine Möglichkeit, auf adaptiven Karten basierende Szenarien sowohl für Teams als auch für Outlook zu implementieren. Dieses Dokument behandelt die folgenden Themen:

Schnellstarthandbuch zur Nutzung von Universal-Aktionen für adaptive Karten in Teams

  1. Ersetzen Sie alle Instanzen von Action.Submit durch Action.Execute, um ein vorhandenes Szenario in Teams zu aktualisieren.

  2. Fügen Sie Ihrer adaptiven Karte eine refresh-Klausel hinzu, wenn Sie das Modell für die automatische Aktualisierung nutzen möchten oder wenn Ihr Szenario benutzerspezifische Ansichten erfordert.

    Hinweis

    Geben Sie die userIds -Eigenschaft an, um zu identifizieren, welche Benutzer automatische Updates erhalten.

  3. Verarbeiten Sie adaptiveCard/action Aufrufanforderungen in Ihrem Bot.

  4. Verwenden Sie den Kontext der Aufrufanforderung, um mit Karten zu antworten, die für einen Benutzer erstellt wurden.

    Hinweis

    Wenn Ihr Bot als Ergebnis der Verarbeitung eines Action.Execute eine neue Karte zurückgibt, muss die Antwort dem Antwortformat entsprechen.

Schema für Universal-Aktionen für adaptive Karten

Universelle Aktionen für adaptive Karten werden in der Schemaversion 1.5 für adaptive Karten eingeführt. Um adaptive Karten effektiv verwenden zu können, muss die version -Eigenschaft Ihrer adaptiven Karte auf 1,5 festgelegt werden.

Hinweis

Wenn Sie die version Eigenschaft auf 1.5 festlegen, ist Ihre adaptive Karte nicht kompatibel mit älteren Clients der Plattformen oder Anwendungen, z. B. Outlook und Teams, da sie die universellen Aktionen für adaptive Karten nicht unterstützen.

Wenn Sie die Karte Version auf weniger als 1.5 festlegen und eine oder beides verwenden, refresh die Eigenschaft und Action.Execute, geschieht Folgendes:

Client Verhalten
Microsoft Teams Ihre Karte funktioniert nicht mehr. Die Karte wird nicht aktualisiert und Action.Execute wird abhängig von der Version des Teams-Clients nicht gerendert. Um maximale Kompatibilität in Teams sicherzustellen, definieren Sie Action.Execute mit einem Action.Submit in der Fallbackeigenschaft.

Weitere Informationen zur Unterstützung älterer Clients finden Sie unter Abwärtskompatibilität.

Action.Execute

Ersetzen Sie beim Erstellen von adaptive Karten Action.Submit und Action.Http durch Action.Execute. Das Schema für Action.Execute ähnelt dem von Action.Submit.

Weitere Informationen finden Sie unter Action.Execute-Schema und -Eigenschaften.

Jetzt können Sie das Aktualisierungsmodell verwenden, damit Adaptive Karten automatisch aktualisiert werden können.

Aktualisierungsmodell

Um Ihre adaptive Karte automatisch zu aktualisieren, definieren Sie ihre refresh-Eigenschaft, die eine Aktion vom Typ Action.Execute und ein userIds-Array einbettet.

Weitere Informationen finden Sie unter Aktualisieren von Schemas und Eigenschaften.

Benutzer-IDs, die aktualisiert werden

Im Folgenden sind die Features von UserIds aufgeführt, die aktualisiert werden:

  • UserIds ist ein Array von Benutzer-MRIs, das Teil der refresh-Eigenschaft in „Adaptive Karten“ ist.

  • Wenn die userIds list-Eigenschaft im Aktualisierungsabschnitt des Karte als userIds: [] angegeben wird, wird die Karte nicht automatisch aktualisiert. Stattdessen wird dem Benutzer die Option Karte aktualisieren im Menü mit drei Punkten im Teams-Webclient oder -Desktop und im Kontextmenü für langes Drücken in Teams Mobile angezeigt, d. h. Android oder iOS, um die Karte manuell zu aktualisieren. Alternativ können userIds Sie die Aktualisierungseigenschaft auch überspringen, falls das Szenario =60 Mitglieder in Teams-Gruppenchats oder -Kanälen umfasst <. Der Teams-Client ruft automatisch Aktualisierungsaufrufe für alle Benutzer auf, wenn die Gruppe oder der Kanal =60 Benutzer enthält <.

  • Die UserIds-Eigenschaft wird hinzugefügt, da Kanäle in Teams eine große Anzahl von Mitgliedern enthalten können. Wenn alle Mitglieder den Kanal gleichzeitig anzeigen, führt eine bedingungslose automatische Aktualisierung zu vielen gleichzeitigen Aufrufen des Bots. Die userIds-Eigenschaft muss immer eingeschlossen werden, um zu identifizieren, welche Benutzer eine automatische Aktualisierung erhalten müssen. Dabei gilt ein Limit von maximal 60 (sechzig) Benutzer-MRIs.

  • Sie können die Benutzer-MRIs des Teams-Konversationsmitglieds abrufen. Weitere Informationen zum Hinzufügen der UserIds-Liste im Aktualisierungsabschnitt der adaptiven Karte finden Sie unter Abrufen der Liste oder des Benutzerprofils.

Sie können die Benutzer-MRI für einen Kanal, Gruppenchat oder 1:1-Chat mithilfe des folgenden Beispiels abrufen:

  1. Verwenden von TurnContext

    userMRI= turnContext.Activity.From.Id

  2. Verwenden der GetMemberAsync-Methode

    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);var userMRI = member.Id;

  • MRI des Teams-Beispielbenutzers ist 29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk

Hinweis

Die userIds-Eigenschaft wird in Outlook ignoriert, und die refresh-Eigenschaft wird immer automatisch aktiviert. Es gibt kein Skalierungsproblem in Outlook, da Benutzer die Karte zu unterschiedlichen Zeiten anzeigen.

Der nächste Schritt besteht darin, die adaptiveCard/action-Aufrufaktivität zu verwenden, um zu verstehen, welche Anforderung ausgeführt werden muss, nachdem Action.Execute ausgeführt wurde.

adaptiveCard/action Aufrufaktivität

Wenn Action.Execute im Client ausgeführt wird, wird ein neuer Typ von Aufrufaktivität adaptiveCard/action für Ihren Bot erstellt.

Weitere Informationen finden Sie unter Anforderungsformat und -eigenschaften für eine typische adaptiveCard/action-Aufrufaktivität.

Weitere Informationen finden Sie unter Antwortformat und -eigenschaften für eine typische adaptiveCard/action-Aufrufaktivität mit unterstützten Antworttypen.

Als Nächstes können Sie Abwärtskompatibilität auf ältere Clients auf verschiedenen Plattformen anwenden und Ihre adaptive Karte kompatibel machen.

Abwärtskompatibilität

Mit Universal-Aktionen für adaptive Karten können Sie Eigenschaften festlegen, die Abwärtskompatibilität mit älteren Versionen von Outlook und Teams ermöglichen.

Teams

Um die Abwärtskompatibilität Ihrer adaptiven Karten mit älteren Versionen von Teams sicherzustellen, müssen Sie die fallback-Eigenschaft einschließen und ihren Wert auf Action.Submitfestlegen. Außerdem muss Ihr Botcode sowohl Action.Execute als auch Action.Submitverarbeiten.

Weitere Informationen finden Sie unter Abwärtskompatibilität in Teams.

Codebeispiele

Beispielname Beschreibung .NET Node.js Manifest
Teams-Catering-Bot Dieses Beispiel zeigt einen Bot, der Lebensmittelbestellungen mit adaptiven Karten akzeptiert. View – –
Adaptive Karten für sequenzielle Workflows In diesem Beispiel wird die Implementierung von sequenziellen Workflows, benutzerspezifischen Ansichten und aktuellen adaptiven Karten in Bots veranschaulicht. View View Anzeigen

Siehe auch