Kartenaktionen

Karten, die von Bots und Messagingerweiterungen in Teams verwendet werden, unterstützen die folgenden Aktivitätstypen CardAction:

Hinweis

Die CardAction-Aktionen unterscheiden sich von potentialActions für Office 365-Connectorkarten, wenn sie von Connectors verwendet werden.

Typ Aktion
openUrl Öffnet eine URL im Standardbrowser.
messageBack Sendet eine Nachricht und Nutzlast vom Benutzer, der die Schaltfläche ausgewählt oder auf die Karte getippt hat, an den Bot. Sendet eine separate Nachricht an den Chatstream.
imBack Sendet eine Nachricht vom Benutzer, der die Schaltfläche ausgewählt oder auf die Karte getippt hat, an den Bot. Diese Nachricht vom Benutzer zum Bot ist für alle Unterhaltungsteilnehmer sichtbar.
invoke Sendet eine Nachricht und Nutzlast vom Benutzer, der die Schaltfläche ausgewählt oder auf die Karte getippt hat, an den Bot. Diese Nachricht ist nicht sichtbar.
signin Initiiert den OAuth-Fluss, sodass Bots eine Verbindung mit sicheren Diensten herstellen können.

Hinweis

  • Teams unterstützt keine CardAction-Typen, die in der vorherigen Tabelle nicht aufgeführt sind.
  • Teams unterstützt die potentialActions-Eigenschaft nicht.
  • Kartenaktionen unterscheiden sich von vorgeschlagenen Aktionen in Bot-Framework oder Azure Bot Service. Vorgeschlagene Aktionen werden in Microsoft Teams nicht unterstützt. Wenn Schaltflächen in einer Teams-Botnachricht angezeigt werden sollen, verwenden Sie eine Karte.
  • Wenn Sie eine Kartenaktion als Teil einer Messagingerweiterung verwenden, funktionieren die Aktionen erst, wenn die Karte an den Kanal übermittelt wird. Die Aktionen funktionieren nicht, während sich die Karte im Feld "Nachricht verfassen" befindet.

openUrl-Aktionstyp

Der openUrl-Aktionstyp gibt eine URL an, die im Standardbrowser gestartet werden soll.

Hinweis

Ihr Bot erhält keine Benachrichtigung darüber, welche Schaltfläche ausgewählt wurde.

Mit openUrl können Sie eine Aktion mit den folgenden Eigenschaften erstellen:

Eigenschaft Beschreibung
title Wird als Schaltflächenbeschriftung angezeigt.
value Dieses Feld muss eine vollständige und ordnungsgemäß formatierte URL enthalten.

Der folgende Code zeigt ein Beispiel für openUrl-Aktionstyp in JSON:

{
    "type": "openUrl",
    "title": "Tabs in Teams",
    "value": "https://msdn.microsoft.com/microsoft-teams/tabs"
}

messageBack-Aktionstyp

Mit messageBack können Sie eine vollständig angepasste Aktion mit den folgenden Eigenschaften erstellen:

Eigenschaft Beschreibung
title Wird als Schaltflächenbeschriftung angezeigt.
displayText Optional. Wird vom Benutzer im Chatstream verwendet, wenn die Aktion ausgeführt wird. Dieser Text wird nicht an Ihren Bot gesendet.
value Wird an Ihren Bot gesendet, wenn die Aktion ausgeführt wird. Sie können den Kontext für die Aktion codieren, z. B. eindeutige Bezeichner oder ein JSON-Objekt.
text Wird an Ihren Bot gesendet, wenn die Aktion ausgeführt wird. Verwenden Sie diese Eigenschaft, um die Botentwicklung zu vereinfachen. Ihr Code kann eine einzelne Eigenschaft der obersten Ebene überprüfen, um Botlogik zu verteilen.

Die Flexibilität von "messageBack" bedeutet, dass Ihr Code keine sichtbare Benutzernachricht im Verlauf hinterlassen kann, indem er einfach nicht "displayText" verwendet.

Der folgende Code zeigt ein Beispiel für messageBack-Aktionstyp in JSON:

{
  "buttons": [
    {
    "type": "messageBack",
    "title": "My MessageBack button",
    "displayText": "I clicked this button",
    "text": "User just clicked the MessageBack button",
    "value": "{\"property\": \"propertyValue\" }"
    }
  ]
}

Die value-Eigenschaft kann entweder eine serialisierte JSON-Zeichenfolge oder ein JSON-Objekt sein.

Beispiel für eingehende Nachrichten

replyToId enthält die ID der Nachricht, von der die Kartenaktion stammt. Verwenden Sie sie, wenn Sie die Nachricht aktualisieren möchten.

Der folgende Code zeigt ein Beispiel für eingehende Nachrichten:

{
   "text":"User just clicked the MessageBack button",
   "value":{
      "property":"propertyValue"
   },
   "type":"message",
   "timestamp":"2017-06-22T22:38:47.407Z",
   "id":"f:5261769396935243054",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/amer-client-ss.msg/",
   "from":{
      "id":"29:102jd210jd010icsoaeclaejcoa9ue09u",
      "name":"John Smith"
   },
   "conversation":{
      "id":"19:malejcou081i20ojmlcau0@thread.skype;messageid=1498171086622"
   },
   "recipient":{
      "id":"28:76096e45-119f-4736-859c-6dfff54395f7",
      "name":"MyBot"
   },
   "entities":[
      {
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo" 
      }
   ],
   "channelData":{
      "channel":{
         "id":"19:malejcou081i20ojmlcau0@thread.skype"
      },
      "team":{
         "id":"19:12d021jdoijsaeoaue0u@thread.skype"
      },
      "tenant":{
         "id":"bec8e231-67ad-484e-87f4-3e5438390a77"
      }
   },
        "replyToId": "1575667808184",
}

imBack-Aktionstyp

Die imBack-Aktion löst eine Rückgabenachricht an Ihren Bot aus, als ob der Benutzer sie in einer normalen Chatnachricht eingegeben hätte. Ihr Benutzer und alle anderen Benutzer in einem Kanal können die Schaltflächenantwort sehen.

Mit imBack können Sie eine Aktion mit den folgenden Eigenschaften erstellen:

Eigenschaft Beschreibung
title Wird als Schaltflächenbeschriftung angezeigt.
value Dieses Feld muss die Textzeichenfolge enthalten, die im Chat verwendet und daher an den Bot zurückgesendet wird. Dies ist der Nachrichtentext, den Sie in Ihrem Bot verarbeiten, um die gewünschte Logik auszuführen.

Hinweis

Das value-Feld ist eine einfache Zeichenfolge. Formatierung oder ausgeblendete Zeichen werden nicht unterstützt.

Der folgende Code zeigt ein Beispiel für imBack-Aktionstyp in JSON:

{
    "type": "imBack",
    "title": "More",
    "value": "Show me more"
}

invoke-Aktionstyp

Die invoke-Aktion wird zum Aufrufen von Aufgabenmodule verwendet.

Die invoke-Aktion enthält drei Eigenschaften: type, title und value.

Mit invoke können Sie eine Aktion mit den folgenden Eigenschaften erstellen:

Eigenschaft Beschreibung
title Wird als Schaltflächenbeschriftung angezeigt.
value Diese Eigenschaft kann eine Zeichenfolge, ein JSON-Objekt mit Zeichenfolgen oder ein JSON-Objekt enthalten.

Der folgende Code zeigt ein Beispiel für invoke-Aktionstyp in JSON:

{
    "type": "invoke",
    "title": "Option 1",
    "value": {
        "option": "opt1"
    }
}

Wenn ein Benutzer die Schaltfläche auswählt, empfängt Ihr Bot das value-Objekt mit einigen zusätzlichen Informationen.

Hinweis

Der Aktivitätstyp ist "invoke" anstatt "message", der "activity.Type == "invoke"" ist.

Beispiel für eingehende Aufrufnachricht

Die replyToId-Eigenschaft der obersten Ebene enthält die ID der Nachricht, von der die Kartenaktion stammt. Verwenden Sie sie, wenn Sie die Nachricht aktualisieren möchten.

Der folgende Code zeigt ein Beispiel für eingehende Aufrufnachrichten:

{
    "type": "invoke",
    "value": {
        "option": "opt1"
    },
    "timestamp": "2017-02-10T04:11:19.614Z",
    "localTimestamp": "2017-02-09T21:11:19.614-07:00",
    "id": "f:6894910862892785420",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1Eniglq0-uVL83xNB9GU6w_G5a4SZF0gcJLprZzhtEbel21G_5h-
    NgoprRw45mP0AXUIZVeqrsIHSYV4ntgfVJQ",
        "name": "John Doe"
    },
    "conversation": {
        "id": "19:97b1ec61-45bf-453c-9059-6e8984e0cef4_8d88f59b-ae61-4300-bec0-caace7d28446@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:8d88f59b-ae61-4300-bec0-caace7d28446",
        "name": "MyBot"
    },
    "entities": [
        {
            "locale": "en-US",
            "country": "US",
            "platform": "Web",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "channel": {
            "id": "19:dc5ba12695be4eb7bf457cad6b4709eb@thread.skype"
        },
        "team": {
            "id": "19:712c61d0ef384e5fa681ba90ca943398@thread.skype"
        },
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "replyToId": "1575667808184"
}

signin-Aktionstyp

Der signin-Aktionstyp initiiert einen OAuth-Fluss, der Bots das Herstellen einer Verbindung mit sicheren Diensten ermöglicht. Weitere Informationen finden Sie unter Authentifizierungsfluss in Bots.

Teams unterstützt auch Aktionen für adaptive Karten, die nur von adaptiven Karten verwendet werden.

Der folgende Code zeigt ein Beispiel für signin-Aktionstyp in JSON:

{
"type": "signin",
"title": "Click me for signin",
"value": "https://signin.com"
}

Aktionen für adaptive Karten

Adaptive Karten unterstützen vier Aktionstypen:

Sie können auch die Nutzlast der adaptiven Karte "Action.Submit" ändern, um vorhandene Bot-Framework-Aktionen mithilfe einer msteams-Eigenschaft im data-Objekt von "Action.Submit" zu unterstützen. Der nächste Abschnitt enthält Details zur Verwendung vorhandener Bot-Framework-Aktionen mit adaptiven Karten.

Hinweis

Das Hinzufügen von "msteams" zu Daten mit einer Bot-Framework-Aktion funktioniert nicht mit einem Aufgabenmodul für adaptive Karten.

Adaptive Karten mit messageBack-Aktion

Um eine messageBack-Aktion mit einer adaptiven Karte einzuschließen, fügen Sie die folgenden Details in das msteams-Objekt ein:

Hinweis

Sie können ggf. zusätzliche ausgeblendete Eigenschaften in das data-Objekt einschließen.

Eigenschaft Beschreibung
type Auf messageBack festlegen.
displayText Optional. Wird vom Benutzer im Chatstream verwendet, wenn die Aktion ausgeführt wird. Dieser Text wird nicht an Ihren Bot gesendet.
value Wird an Ihren Bot gesendet, wenn die Aktion ausgeführt wird. Sie können den Kontext für die Aktion codieren, z. B. eindeutige Bezeichner oder ein JSON-Objekt.
text Wird an Ihren Bot gesendet, wenn die Aktion ausgeführt wird. Verwenden Sie diese Eigenschaft, um die Botentwicklung zu vereinfachen. Ihr Code kann eine einzelne Eigenschaft der obersten Ebene überprüfen, um Botlogik zu verteilen.

Der folgende Code zeigt ein Beispiel für adaptive Karten mit messageBack-Aktion:

{
  "type": "Action.Submit",
  "title": "Click me for messageBack",
  "data": {
    "msteams": {
        "type": "messageBack",
        "displayText": "I clicked this button",
        "text": "text to bots",
        "value": "{\"bfKey\": \"bfVal\", \"conflictKey\": \"from value\"}"
    }
  }
}

Adaptive Karten mit imBack-Aktion

Um eine imBack-Aktion mit einer adaptiven Karte einzuschließen, fügen Sie die folgenden Details in das msteams-Objekt ein:

Hinweis

Sie können ggf. zusätzliche ausgeblendete Eigenschaften in das data-Objekt einschließen.

Eigenschaft Beschreibung
type Auf imBack festlegen.
value Zeichenfolge, die im Chat zurückgegeben werden muss.

Der folgende Code zeigt ein Beispiel für adaptive Karten mit imBack-Aktion:

{
  "type": "Action.Submit",
  "title": "Click me for imBack",
  "data": {
    "msteams": {
        "type": "imBack",
        "value": "Text to reply in chat"
    }
  }
}

Adaptive Karten mit signin-Aktion

Um eine signin-Aktion mit einer adaptiven Karte einzuschließen, fügen Sie die folgenden Details in das msteams-Objekt ein:

Hinweis

Sie können ggf. zusätzliche ausgeblendete Eigenschaften in das data-Objekt einschließen.

Eigenschaft Beschreibung
type Auf signin festlegen.
value Legen Sie die URL fest, an die Sie umleiten möchten.

Der folgende Code zeigt ein Beispiel für adaptive Karten mit signin-Aktion:

{
  "type": "Action.Submit",
  "title": "Click me for signin",
  "data": {
    "msteams": {
        "type": "signin",
        "value": "https://signin.com"
    }
  }
}

Adaptive Karten mit invoke-Aktion

Um eine invoke-Aktion mit einer adaptiven Karte einzuschließen, fügen Sie die folgenden Details in das msteams-Objekt ein:

Hinweis

Sie können ggf. zusätzliche ausgeblendete Eigenschaften in das data-Objekt einschließen.

Eigenschaft Beschreibung
type Auf task/fetch festlegen.
data Festlegen des Werts.

Der folgende Code zeigt ein Beispiel für adaptive Karten mit invoke-Aktion:

{
  "type": "Action.Submit",
  "title": "submit",
  "data": {
    "msteams": {
        "type": "task/fetch"
    }
  }
}

Der folgende Code zeigt ein Beispiel für adaptive Karten mit invoke-Aktion mit zusätzlichen Nutzlastdaten:

{
  "type": "Action.Submit",
  "title": "submit"
  "data": {
    "msteams": {
        "type": "task/fetch"
    },
    "Value1": "some value"
  }
}

Nächster Schritt

Siehe auch