Gazdag kártyamellékletek hozzáadása az üzenetekhez a Bot Connector API-val
Egyes csatornák lehetővé teszik, hogy a robot gazdag kártyákat küldjön a felhasználóknak. A gazdag kártya olyan melléklet, amely interaktív elemeket tartalmaz, például gombokat, szöveget, képeket, hangot, videót stb.
Ez a cikk azt ismerteti, hogyan hozhat létre gazdag kártyákat, amelyeket csatolhat egy üzenethez. Megtudhatja, hogyan adhat hozzá médiamellékleteket az üzenetekhez , ha konkrét útmutatást szeretne adni a mellékletek üzenethez való hozzáadásához.
A gazdag kártyák típusai
A gazdag kártya egy címet, leírást, hivatkozást és képeket tartalmaz. Az üzenetek több gazdag kártyát tartalmazhatnak, amelyek lista vagy körhinta formátumban jelennek meg. A Bot Framework jelenleg nyolcféle gazdag kártyát támogat:
| Kártya típusa | Leírás |
|---|---|
| AdaptiveCard | Testre szabható kártya, amely szöveg, beszéd, képek, gombok és beviteli mezők bármilyen kombinációját tartalmazhatja. Lásd: csatornánkénti támogatás. |
| AnimationCard | Animált GIF-eket vagy rövid videókat lejátszani képes kártya. |
| AudioCard | Hangfájl lejátszására képes kártya. |
| HeroCard | Általában egyetlen nagyméretű képet, egy vagy több gombot és szöveget tartalmazó kártya. |
| ThumbnailCard | Általában egy miniatűrt, egy vagy több gombot és szöveget tartalmazó kártya. |
| ReceiptCard | Egy kártya, amely lehetővé teszi, hogy a robot nyugtát adjon a felhasználónak. Általában tartalmazza a nyugta, az adó- és a végösszegadatok, valamint egyéb szöveg elemeinek listáját. |
| SignInCard | Egy kártya, amely lehetővé teszi a robot számára, hogy felhasználói bejelentkezést kérjen. Általában szöveget és egy vagy több gombot tartalmaz, amelyekre a felhasználó rákattinthat a bejelentkezési folyamat elindításához. |
| VideoCard | Egy kártya, amely képes videókat lejátszani. |
Tipp.
Az egyes csatornákon támogatott funkciókkal kapcsolatos további információkért tekintse meg a csatornák referenciacikkét.
Események feldolgozása gazdag kártyákon belül
A gazdag kártyákon belüli események feldolgozásához a CardAction objektumokkal megadhatja, hogy mi történjen, ha a felhasználó rákattint egy gombra, vagy koppintson a kártya egy szakaszára. Minden CardAction objektum a következő tulajdonságokat tartalmazza:
| Tulajdonság | Típus | Leírás |
|---|---|---|
| channelData | húr | a művelethez társított csatornaspecifikus adatok |
| displayText | húr | tesztelje, hogy megjelenjen-e a csevegőcsatornában, ha a gombra kattint |
| text | húr | szöveg a művelethez |
| típus | húr | művelet típusa (az alábbi táblázatban megadott értékek egyike) |
| cím | húr | a gomb címe |
| rendszerkép | húr | a gomb képÉNEK URL-címe |
| Érték | húr | a megadott művelettípus végrehajtásához szükséges érték |
Feljegyzés
Az Adaptív kártyákon belüli gombok nem objektumok használatával CardAction jönnek létre, hanem az Adaptív kártyák által definiált sémát használják.
Lásd: Adaptív kártya hozzáadása egy üzenethez egy példa, amely bemutatja, hogyan adhat hozzá gombokat egy adaptív kártyához.
A helyes működéshez rendeljen hozzá egy művelettípust egy főkártya minden kattintható eleméhez. Ez a táblázat felsorolja és ismerteti a rendelkezésre álló művelettípusokat, valamint a társított érték tulajdonságban szereplő értékeket.
A messageBack kártyaműveletnek általánosabb jelentése van, mint a többi kártyaműveletnek. A tevékenységséma Kártyaművelet szakaszában további információt talál az messageBack egyéb kártyaművelet-típusokról.
| Típus | Leírás | Érték |
|---|---|---|
| hív | Telefonhívást kezdeményez. | A telefonhívás célhelye ebben a formátumban: tel:123123123123. |
| downloadFile | Letölt egy fájlt. | A letölteni kívánt fájl URL-címe. |
| imBack | Üzenetet küld a robotnak, és látható választ jelenít meg a csevegésben. | A küldendő üzenet szövege. |
| messageBack | A csevegőrendszeren keresztül küldendő szöveges választ jelöli. | Nem kötelező programozott érték, amely belefoglalható a létrehozott üzenetekbe. |
| openUrl | Megnyitja az URL-címet a beépített böngészőben. | A megnyitni kívánt URL-cím. |
| playAudio | Hang lejátszása. | A lejátszandó hang URL-címe. |
| playVideo | Videó lejátszása. | A lejátszandó videó URL-címe. |
| postBack | Üzenetet küld a robotnak, és előfordulhat, hogy nem küld látható választ a csevegésben. | A küldendő üzenet szövege. |
| showImage | Kép megjelenítése. | A megjelenítendő kép URL-címe. |
| bejelentkezés | OAuth-bejelentkezési folyamatot kezdeményez. | A kezdeményezni kívánt OAuth-folyamat URL-címe. |
Fő képkártya hozzáadása üzenethez
Gazdag kártyamelléklet hozzáadása egy üzenethez:
- Hozzon létre egy objektumot, amely azt a kártyatípust jelöli, amelyet hozzá szeretne adni az üzenethez.
- Mellékletobjektum létrehozása:
- Állítsa be a tulajdonságát
contentTypea kártya médiatípusára. - Állítsa a tulajdonságát
contentarra az objektumra, amelyet a kártya ábrázolásához hozott létre.
- Állítsa be a tulajdonságát
- Adja hozzá az
Attachmentobjektumot azattachmentsüzenet tömbjének.
Tipp.
A gazdag kártyamellékleteket tartalmazó üzenetek általában nem adhatók meg text.
Egyes csatornák lehetővé teszik, hogy több gazdag kártyát adjon hozzá a attachments tömbhöz egy üzeneten belül. Ez a funkció olyan helyzetekben lehet hasznos, amikor több lehetőséget szeretne biztosítani a felhasználónak. Ha például a robot lehetővé teszi, hogy a felhasználók szállodai szobákat foglaljanak le, az megjelenítheti a felhasználót a rendelkezésre álló szobák típusait megjelenítő gazdag kártyák listájával. Minden kártya tartalmazhatja a szobatípusnak megfelelő képet és felszereltséglistát, a felhasználó pedig kiválaszthat egy szobatípust egy kártyára koppintva vagy egy gombra kattintva.
Tipp.
Ha több rich kártyát szeretne megjeleníteni listaformátumban, állítsa a Tevékenység objektum tulajdonságát attachmentLayout "listára".
Ha több gazdag kártyát szeretne megjeleníteni körhinta formátumban, állítsa az Activity objektum tulajdonságát attachmentLayout "körhinta" értékre.
Ha a csatorna nem támogatja a körhinta formátumot, akkor a gazdag kártyák listaformátumban jelennek meg, még akkor is, ha a attachmentLayout tulajdonság a "körhinta" értéket adja meg.
Az alábbi példa egy teljes üzenetet mutat be, amely egyetlen hero kártyamellékletet tartalmaz. Ebben a példában a kérelem az alap URI-t jelöli, https://smba.trafficmanager.net/teams az alap URI-t azon kérések esetében, amelyek esetében a robot problémái eltérőek lehetnek. Az alap URI beállításával kapcsolatos részletekért tekintse meg az API-referencia című témakört.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "sender's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "1234abcd",
"name": "recipient's name"
},
"attachments": [
{
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "title goes here",
"subtitle": "subtitle goes here",
"text": "descriptive text goes here",
"images": [
{
"url": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"alt": "picture of a duck",
"tap": {
"type": "playAudio",
"value": "url to an audio track of a duck call goes here"
}
}
],
"buttons": [
{
"type": "playAudio",
"title": "Duck Call",
"value": "url to an audio track of a duck call goes here"
},
{
"type": "openUrl",
"title": "Watch Video",
"image": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"value": "url goes here of the duck in flight"
}
]
}
}
],
"replyToId": "5d5cdc723"
}
Adaptív kártya hozzáadása üzenethez
Az adaptív kártya szöveg, beszéd, képek, gombok és beviteli mezők bármilyen kombinációját tartalmazhatja. Az adaptív kártyák az Adaptív kártyákban megadott JSON-formátum használatával jönnek létre, amely teljes körű vezérlést biztosít a kártyatartalmak és -formátumok felett.
Az Adaptív kártyák webhelyen található információk segítségével megismerheti az Adaptív kártya sémáját, megismerheti az Adaptív kártya elemeit, és megtekintheti a JSON-mintákat, amelyek különböző összetételű és összetettségű kártyák létrehozásához használhatók. Emellett az Interaktív vizualizációval adaptív kártya hasznos adatait és az előnézeti kártya kimenetét is megtervezheti.
Az alábbi példa egyetlen adaptív kártya mellékletobjektumot mutat be, amely egy munkahelyi hozzárendelést jelöl. Ha ezt el szeretné küldeni egy felhasználónak, hozzá kell adnia mellékletként egy üzenetben.
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Publish Adaptive Card schema",
"weight": "bolder",
"size": "medium"
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
"size": "small",
"style": "person"
}
]
},
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Matt Hidinger",
"weight": "bolder",
"wrap": true
},
{
"type": "TextBlock",
"spacing": "none",
"text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
"isSubtle": true,
"wrap": true
}
]
}
]
}
]
},
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
"wrap": true
},
{
"type": "FactSet",
"facts": [
{
"title": "Board:",
"value": "Adaptive Card"
},
{
"title": "List:",
"value": "Backlog"
},
{
"title": "Assigned to:",
"value": "Matt Hidinger"
},
{
"title": "Due date:",
"value": "Not set"
}
]
}
]
}
],
"actions": [
{
"type": "Action.ShowCard",
"title": "Comment",
"card": {
"type": "AdaptiveCard",
"body": [
{
"type": "Input.Text",
"id": "comment",
"isMultiline": true,
"placeholder": "Enter your comment"
}
],
"actions": [
{
"type": "Action.Submit",
"title": "OK"
}
]
}
},
{
"type": "Action.OpenUrl",
"title": "View",
"url": "https://adaptivecards.io"
}
]
}
Az eredményként kapott kártya tartalmaz egy címet, információt arról, hogy ki hozta létre a kártyát (a nevét és az avatarját), a kártya létrehozásakor, a munkafeladatok leírását, valamint a feladattal kapcsolatos információkat. Vannak olyan gombok is, amelyekre kattintva megjegyzést fűzhet a munkahelyi feladathoz, vagy megtekintheti azt:
