Microsoft Teams
Lorsque vous configurez un canal Microsoft Teams, les utilisateurs peuvent clavarder avec votre assistant numérique (ou une compétence autonome) au moyen de l'interface utilisateur de Microsoft Teams.
Voici le processus de configuration d'un canal :
- Dans le portail des développeurs de Microsoft Teams, créez une application et ajoutez un robot à cette application.
- À l'aide de l'ID application et du mot de passe du robot, créez un canal dans Digital Assistant.
- Copiez l'URL du webhook générée lors de la création du canal et ajoutez-la au robot.
- Testez votre assistant numérique dans Microsoft Teams.
Les compétences et les assistants numériques que vous exposez au moyen des canaux Microsoft Teams peuvent également être inclus dans les clavardages en groupe. Voir Clavardages en groupe.
Étape 1 : Créer un robot
Pour rendre votre assistant numérique (ou une compétence autonome) disponible dans Microsoft Teams, vous devez créer les éléments suivants au moyen du portail des développeurs d'équipes :
- Une application Microsoft Teams. Cette application sert de conteneur au robot que vous créez et permet d'accéder à celui-ci dans Teams.
- Un robot. Il s'agit de l'artefact, au sein de l'application, qui communique avec Oracle Digital Assistant
Le portail des développeurs Teams n'est pas disponible pour certains types de locataires Microsoft, tels que les locataires GCC-High et Department of Defense (DoD). Si vous travaillez avec un tel locataire, vous pouvez utiliser un locataire standard pour créer l'application, télécharger l'application, puis utiliser Microsoft Graph pour charger l'application dans votre nuage national. Pour plus de détails, voir Portail des développeurs pour les équipes et Déploiements en nuage nationaux sur le site de Microsoft.
Voici les étapes :
- Allez à https://dev.teams.microsoft.com/home et connectez-vous à votre compte Microsoft.
- Dans la barre de navigation gauche, cliquez sur Applications.
- Cliquez sur + Nouvelle application.
- Dans la boîte de dialogue Ajouter une application, entrez le nom à utiliser pour l'application tel qu'il apparaîtra dans Microsoft Teams, puis cliquez sur Ajouter.
(Cette application encapsulera le robot que vous créerez plus tard.)
- Dans la page Informations de base, remplissez les champs obligatoires restants à l'exception de l'ID application (client) et cliquez sur Enregistrer.
Note
Ce champ n'est nécessaire que si vous configurez le robot pour l'authentification unique. Voir Configuration de l'authenfication unique pour les canaux Microsoft Teams. - Dans la barre de navigation de gauche de la page, sous la section Configurer, sélectionnez Fonctions d'application.
- Cliquez sur Bot (Bot).
- Cliquez sur le lien Create a new bot (Créer un nouveau robot).
- Dans la page Gestion des robots, cliquez sur + Nouveau robot.
- Dans la boîte de dialogue Ajouter un robot, entrez le nom du robot.
- Dans la section Canaux de la page, cochez la case Microsoft Teams et cliquez sur Enregistrer.
- Dans la section Clés secrètes de client, sélectionnez Ajouter une clé secrète client pour votre robot.
- Copiez la valeur de la clé secrète client générée et enregistrez-la en lieu sûr sur votre système.
- Dans la section Clés secrètes de client de la page, cliquez avec le bouton droit de la souris sur le lien Azure pour ouvrir la page Enregistrements d'application d'Azure Active Directory dans un onglet de navigateur distinct.
- Dans la page App Inscriptions (Inscriptions d'application), sélectionnez la ressource de robot que vous avez créée.
- Dans la barre de gauche, sélectionnez Authentication (authentification).
- Dans la section Types de compte pris en charge de la page, sélectionnez l'option multilocataire (Comptes dans n'importe quel répertoire organisationnel (Tous les locataires Microsoft Entra ID - Multilocataire).
- Si vous voulez pouvoir utiliser des événements externes pour envoyer des messages aux utilisateurs au moyen d'un canal Microsoft Teams, ajoutez des autorisations pour extraire le profil d'utilisateur au moyen de l'API Microsoft Graph. (La fonction d'événements externes utilise les données d'utilisateur mises en cache provenant de conversations antérieures pour générer des avis ou lancer des conversations de manière proactive avec l'utilisateur.) Voici la marche à suivre pour ajouter ces autorisations :
- Dans la navigation de gauche de la page des inscriptions d'application pour le robot, sélectionnez API Permissions (Autorisations d'API).
- Cliquez sur Ajouter une autorisation.
- Dans la boîte de dialogue Demander des autorisations d'API, sélectionnez Microsoft Graph.
- Sélectionnez Application permissions.
- Sélectionnez l'autorisation Directory.Read.All et cliquez sur Ajouter des autorisations.
- Une fois l'autorisation affichée dans la liste Autorisations configurées, sélectionnez-la, cliquez sur Accorder le consentement de l'administrateur pour..., puis cliquez sur Oui dans la boîte de dialogue Confirmer le consentement de l'administrateur.
-
Retournez à l'onglet dans lequel le portail des développeurs est ouvert dans votre navigateur.
-
Dans la barre de navigation de gauche, cliquez sur Applications, puis sélectionnez votre application.
-
Dans la navigation de gauche pour l'application, sélectionnez App features (Fonctions de l'application).
-
Cliquez sur la vignette Bot.
-
Dans la liste déroulante sous Sélectionner un robot existant, sélectionnez le robot que vous venez de créer.
-
Encore une fois, dans la barre de navigation de gauche de l'application, sélectionnez Fonctions de l'application.
-
Dans le titre Bot, copiez l'ID robot et enregistrez-le dans un fichier texte.
Note
Il se peut que vous deviez transcrire manuellement l'ID robot.Vous en aurez besoin lors de la création du canal dans Digital Assistant.
- Dans la section Étendues de la page, sélectionnez Personnel.
(Vous pouvez également sélectionner d'autres étendues, mais l'option Personnel est requise pour que le robot réponde.)
-
Cliquez sur Save (Enregistrer).
-
Facultativement, dans la barre de navigation de gauche de la page, sous la section Configurer, sélectionnez Domaines et ajoutez les domaines d'où pourraient provenir les utilisateurs du robot.
-
Laissez le portail des développeurs ouvert dans votre navigateur.
Vous achèverez ultérieurement l'enregistrement à l'aide d'une URL de webhook obtenue lors de la création du canal dans Digital Assistant.
Étape 2 : Créer un canal dans Digital Assistant
-
Dans une fenêtre ou un onglet différent de navigateur, ouvrez Digital Assistant, cliquez sur Channels (Canaux) dans le menu de gauche et sélectionnez Users (Utilisateurs).
-
Cliquez sur + Channel (Canal) pour ouvrir la boîte de dialogue Create Channel (Créer un canal).
-
Donnez un nom à votre canal.
-
Choisissez le type de canal Microsoft Teams.
-
Dans le champ ID robot Microsoft, indiquez l'ID du robot Microsoft que vous avez créé.
-
Entrez le mot de passe du robot Microsoft (valeur de clé secrète client) avec le mot de passe ou la valeur de clé secrète client (à ne pas confondre avec l'ID clé secrète client) qui a été généré pour le robot.
-
Cliquez sur Create (Créer).
-
Dans la page Channels (Canaux), copiez l'URL du webhook et collez-la à un endroit pratique sur votre système.
-
Cliquez sur
et sélectionnez l'assistant numérique ou la compétence à associer au canal.
-
Activez le commutateur Channel Enabled (Canal activé).
Étape 3 : Configurer l'URL du webhook pour Microsoft Teams
Vous devez maintenant revenir au point de départ et terminez la configuration dans Microsoft Teams.
-
Retournez à l'onglet du navigateur dans lequel le portail Teams Developer Portal est ouvert.
-
Dans la barre de navigation située à l'extrême gauche de la page, sélectionnez l'icône Outils, puis cliquez sur Gestion des robots.
-
Sélectionnez le robot que vous avez créé.
- Dans la page du robot, sélectionnez l'onglet Configurer.
-
Dans le champ Adresse du point d'extrémité du robot, collez l'URL du webhook obtenue lors de la création du canal dans Digital Assistant, puis cliquez sur Enregistrer.
Étape 4 : Activer les applications dans votre client Office 365
Vous devez demander ensuite à l'administrateur d'Office 365 de configurer votre client pour :
- Autoriser les applications externes dans Microsoft Teams.
- Permettre le chargement d'une version de test d'applications externes.
- Activer les nouvelles applications externes par défaut.
Pour les étapes concrètes, voir https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant.
Étape 5 : Tester dans Microsoft Teams
Une fois la configuration du canal et de la messagerie Microsoft Teams terminée, vous pouvez tester votre assistant numérique (ou compétence) dans Microsoft Teams. Pour ce faire :
- Dans la page de l'application que vous avez créée avec le portail des développeurs Microsoft, cliquez sur le bouton Prévisualiser dans les équipes.
Configuration de l'authenfication unique pour les canaux Microsoft Teams
Si vous voulez qu'un assistant numérique ou une compétence exige l'authentification configurée pour Microsoft Teams, vous pouvez leur définir une authentification unique (SSO) au sein de Microsoft Teams.
Une fois cette authentification unique configurée, les utilisateurs pourront se connecter à Teams avec leurs identifiants Azure Active Directory (Azure AD), puis interagir de façon transparente avec l'assistant numérique, sans avoir à se connecter de nouveau.
Les applications dorsales auxquelles vous accédez par l'assistant numérique doivent prendre en charge les jetons d'accès Azure AD directement. Les clients Fusion Cloud Applications (FA) utilisant Teams peuvent également avoir une authentification unique activée entre Azure AD et FA. Cependant, il n'est pas encore possible d'avoir une conversation transparente avec FA à partir d'une session Teams, car le jeton d'accès de sécurité généré à partir de Teams ne peut pas être utilisé directement pour communiquer avec FA. Pour corriger cet écart, vous pouvez mettre en oeuvre une solution personnalisée pour un échange de jetons. Voir ce billet de blogue pour plus de détails.
Voici les étapes générales de configuration de l'authentification unique pour un canal Microsoft Teams :
- (Si vous ne l'avez pas encore fait) créez un canal Microsoft Teams comme décrit dans les rubriques précédentes.
- Créez une application Azure AD dans le portail Azure.
- Mettez à jour l'enregistrement du robot Microsoft avec des détails d'authentification unique.
- Dans Oracle Digital Assistant, enregistrez l'application Azure AD en tant que service d'authentification de la plate-forme d'identités Microsoft.
- Activez l'authentification dans vos compétences grâce au service d'authentification que vous avez enregistré.
Créer une application Azure AD
Pour configurer l'authentification unique pour une compétence ou un assistant numérique dans Microsoft Teams, vous devez créer une application Azure AD. Cette application est en plus de l'application Azure AD que vous avez déjà créée dans le cadre de la configuration du canal Microsoft Teams.
Avant de commencer, assurez-vous que vous disposez des éléments suivants :
- Un compte Azure avec un abonnement actif.
- L'ID application Microsoft pour le robot que vous avez configuré avec votre canal Microsoft Teams.
- L'accès administrateur au portail Azure.
Voici les étapes de création d'une application Azure AD pour l'authentification unique :
- Créer un enregistrement de nouvelle application :
- Naviguez jusqu'à https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade dans le portail Azure.
- Cliquez sur Nouvelle inscription.
- Remplissez le champ Name (Nom).
- Dans la section Supported account types (Types de compte pris en charge), sélectionnez le bouton radio Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) (Comptes dans tout répertoire organisationnel (tout répertoire Azure AD - Multi-client) et comptes Microsoft personnels (par exemple, Skype, Xbox)).
- Cliquez sur Register (Enregistrer).
Une fois l'application créée, vous parvenez à la section Overview (Aperçu). L'ID application (client) et l'ID répertoire (locataire) doivent être créés pour votre application.
- Ajouter une configuration de plate-forme Web :
- Dans la barre de navigation de gauche, sélectionnez Authentication (Authentification).
- Sous Configuration de la plate-forme, cliquez sur Ajouter une plate-forme et sélectionnez Web.
- Ajoutez une URI de redirection au format suivant :
<YOUR_Oracle-Digital-Assistant_URL>/connectors/v2/callback
- Cliquez sur Configure (Configurer).
- Créer une clé secrète client :
- Dans la barre de navigation de gauche, sélectionnez Certificates and secrets (Certificats et clés secrètes).
- Cliquez sur + New client secret (+ Nouvelle clé secrète client), remplissez les champs requis et cliquez sur Add (Ajouter).
- Copiez la valeur de la clé secrète client et conservez-la dans un endroit sécurisé. Vous aurez besoin de cette valeur plus tard.
- Configurer le jeton :
- Dans la barre de navigation de gauche, sélectionnez Token configuration (Configuration de jeton).
- Cliquez sur + Add optional claim (Ajouter une revendication facultative).
- Pour Token Type (Type de jeton), sélectionnez Access (Accès).
- Sélectionnez ces revendications :
- given_name
- upn
- Cliquez sur Add (Ajouter).
- Sélectionnez l'option Turn on the Microsoft Graph email, profile permission (required for claims to appear in token) (Activer le courriel de Microsoft Graph, l'autorisation de profil (requise pour que les revendications apparaissent dans le jeton)) et cliquez sur Add (Ajouter).
- Dans la barre de navigation de gauche, sélectionnez API permissions (Autorisations d'API).
Vous pouvez voir que trois autorisations sont créées.
- Cliquez sur + Add a Permission (Ajouter une autorisation) et ajoutez User.ReadBasic.All.
Vous en aurez besoin pour accéder aux informations de profil.
- Définir l'URI d'ID application :
- Dans la barre de navigation de gauche, sélectionnez Expose an API (Exposer une API).
- Cliquez sur le champ Application ID URI (URI de l'ID application).
- Mettez à jour la valeur au format :
api://botid-<Microsoft_App_ID_for_your_bot>
Note
Il doit s'agir de l'ID application du robot, pas celui de l'API d'authentification unique. - Cliquez sur + Add a scope (Ajouter une étendue).
- Dans le panneau qui s'ouvre :
- Définissez le nom
access_as_user
dans l'option Scope (Étendue).La partie de domaine du nom de l'étendue affichée juste au-dessous du champ de texte doit correspondre automatiquement à l'URI d'ID application définie à l'étape précédente, avec
/access_as_user
ajouté à la fin. - Réglez Who can consent? (Qui peut consentir) à Admins and users (Administrateurs et utilisateurs).
- Définissez le nom
- Remplissez les champs de configuration des invites de consentement pour les administrateurs et les utilisateurs avec des valeurs appropriées à l'étendue
access_as_user
.Voici quelques suggestions :
- Admin consent title (Titre de consentement d'administrateur) : Teams peut accéder au profil de l'utilisateur.
- Admin consent description (Description du consentement d'administrateur) : Permet à Teams d'appeler les API Web de l'application en tant qu'utilisateur actuel.
- User consent title (Titre de consentement d'utilisateur) : Teams peut accéder à votre profil d'utilisateur et faire des demandes en votre nom.
- User consent description (Description du consentement d'utilisateur) : Permet à Teams d'appeler les API de cette application avec les mêmes droits que vous
- Assurez-vous que l'option State (État) est réglée à Enabled (Activé).
- Dans la section Authorized client applications (Applications clientes autorisées), cliquez sur + Add a client application (Ajouter une application cliente).
- Entrez les ID suivants :
1fec8e78-bce4-4aaf-ab1b-5451cc387264
Il s'agit de l'application mobile et de bureau Teams.
5e3ce6c0-2b1f-4285-8d4b-75ee78787346
Il s'agit de l'application Web Teams.
- Mettre à jour le manifeste :
- Dans la barre de navigation de gauche, sélectionnez Manifest (Manifeste).
- Réglez
"acceptMappedClaims"
àtrue
. - Réglez
"accessTokenAcceptedVersion"
à2
. - Cliquez sur Save (Enregistrer).
- Accorder des autorisations d'administrateur de locataire à l'application Azure AD.
- Dans la barre de navigation de gauche, sélectionnez Overview (Aperçu).
- Copiez l'ID application (client), l'ID répertoire (locataire) et l'URI d'ID application et enregistrez-les dans un endroit pratique.
- Dans une fenêtre de navigateur privé, connectez-vous au compte d'administrateur Microsoft.
L'URL a le format suivant :
où vous remplacezhttps://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>
<tenant-id>
par l'ID répertoire (locataire) que vous venez de copier et<client-id>
par l'ID application (client).
- Dans la boîte de dialogue Permissions requested(Autorisations demandées), vérifiez et acceptez les autorisations.
Mettre à jour l'enregistrement du robot avec des détails d'authentification unique
Mettez à jour votre robot Microsoft avec les détails d'authentification unique que vous avez configurés :
- Ouvrez le robot dans le portail des développeurs Teams et ouvrez l'éditeur de manifeste.
- Sélectionnez l'onglet Informations de base.
- Faites défiler l'affichage vers le bas jusqu'au champ ID application (client) et insérez l'ID application (client).
- Sélectionnez l'onglet Connexion unique.
- Dans l'URI de l'ID application, ajoutez l'URI de l'ID application que vous avez copié précédemment.
- Dans le panneau de navigation de gauche, sélectionnez Publier dans l'organisation.
Enregistrer l'application Azure AD en tant que service d'authentification dans l'assistant numérique
Vous allez maintenant enregistrer l'application Azure AD en tant que service d'authentification dans Oracle Digital Assistant.
-
Dans une fenêtre ou un onglet distinct du navigateur, ouvrez Digital Assistant, développez Settings (Paramètres) dans le menu de gauche et sélectionnez Authentication Services (Services d'authentification).
- Cliquez sur + Service.
- Dans la boîte de dialogue New Authentication Service (Nouveau service d'authentification), entrez les valeurs suivantes :
- Fournisseur d'identités : Microsoft Identity Platform
- Name (Nom) : Nom servant à identifier le service d'authentification.
- Token Endpoint URL (URL du point d'extrémité du jeton) : URL du fournisseur d'identités pour les demandes de jetons d'accès. Utilisez :
https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token
- Authorization Endpoint (Point d'extrémité d'autorisation) : URL du fournisseur d'identités pour la page dans laquelle les utilisateurs s'authentifient en entrant leur nom d'utilisateur et leur mot de passe. Utilisez :
https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize
- Client ID and Client Secret (ID client et Clé secrète client) : ID client et clé secrète client de l'application Azure AD (client OAuth) enregistrée. Utilisez l'ID et la clé secrète de l'application.
- Portée :
<Application(client)_ID_for_your_bot>/access_as_user
- Subject Claim (Revendication du sujet) : Revendication du profil de jeton d'accès à utiliser pour identifier l'utilisateur. Utilisez l'adresse de courriel.
Référencer le service d'authentification à partir de vos compétences
Dans les compétences qui nécessitent une authentification unique, incorporez le composant OAuth 2.0 Account Link dans le flux de dialogue pour que le service d'authentification s'en charge. Dans ce composant, assurez-vous de régler la propriété enableSingleSignon
à true
. (Pour les flux de dialogue basés sur YAML, le composant est appelé System.OAuth2AccountLink.)
Conseil :
Si vous ne souhaitez pas coder de façon permanente le nom du service d'authentification dans le composant, vous pouvez créer un paramètre personnalisé que vous transmettez au composant. Voir Paramètres personnalisés.Fonctions prises en charge
Les canaux Microsoft Teams dans Digital Assistant prennent en charge les fonctions suivantes :
- texte (envoi et réception)
- images (envoi et réception)
- fichiers (envoi et réception)
- émojis (envoi et réception)
- liens
- republications
- propriétés personnalisées
- composants de carrousel
- composants de liste
Si vous ciblez votre compétence sur plusieurs canaux avec des capacités de formatage et une syntaxe différentes, vous pouvez utiliser un balisage HTML de base dans vos messages. Si vous le faites, ce balisage sera automatiquement converti au format de balisage de Microsoft Teams lorsque le message sera transmis au canal. Ceci est particulièrement utile si vous ciblez vos compétences sur d'autres canaux en plus de Microsoft Teams. Voir Formatage de texte enrichi dans les canaux.
Contraintes liées aux messages
Dans Digital Assistant, les canaux Microsoft Teams présentent les contraintes suivantes liées aux messages :
- Messages texte
- Longueur maximale de l'étiquette d'action de texte : 1 ligne (50 caractères environ)
- Types d'action de texte autorisés : Republication, Appel, URL
- Cartes horizontales
- Longueur maximale du titre : 2 lignes (80 caractères environ)
- Longueur maximale de la description : 25 000 caractères
- Longueur maximale de l'étiquette d'action de carte : 1 ligne (50 caractères environ)
- Nombre maximal de cartes : 10
- Nombre maximal d'actions de carte : 6. Si le nombre d'actions de carte dépasse 6, la carte est dupliquée pour afficher les actions restantes.
- Nombre minimal d'actions de carte : 0
- Nombre maximal d'actions de liste de cartes : 6
- Au moins une description, image ou action requise? : Non
- Types d'action de carte autorisés : Republication, Appel, URL
- Types d'action de liste de cartes autorisés : Republication, Appel, URL
- Cartes verticales
- Longueur maximale du titre : 2 lignes (80 caractères environ)
- Longueur maximale de la description : 25 000 caractères
- Longueur maximale de l'étiquette d'action de carte : 1 ligne (50 caractères environ)
- Nombre maximal de cartes : 10
- Nombre maximal d'actions de carte : 3.
- Nombre minimal d'actions de carte : 0
- Nombre maximal d'actions de liste de cartes : 6
- Au moins une description, image ou action requise? : Non
- Types d'action de carte autorisés : Republication, Appel, URL
- Types d'action de liste de cartes autorisés : Republication, Appel, URL
- Messages avec fichier joint
- Pris en charge? : Oui
- Types d'action autorisés : Republication, Appel, URL
- Boutons d'action
- Longueur maximale de l'étiquette d'action globale : 1 ligne (50 caractères environ)
- Nombre maximal d'actions globales : 6
- Types d'action globale autorisés : Republication, Appel, URL
Cartes adaptatives dans Microsoft Teams
Pour les compétences que vous exposez au moyen des canaux Microsoft Teams dans Oracle Digital Assistant, vous pouvez utiliser des cartes adaptatives.
Pour ce faire, vous utilisez l'élément channelCustomProperties
dans un composant de réponse commune et réglez la propriété type
à "AdaptiveCard"
.
Vous pouvez utiliser cet élément aux niveaux suivants du groupe de pages :
- Au niveau d'un élément de carte dans un élément de réponse
cards
. Vous pouvez ainsi définir une structure de carte adaptative unique qui sera reproduite plusieurs fois quand une propriétéiteratorVariable
a été spécifiée pour l'élément de carte. - Au niveau d'un élément de réponse textuelle, généralement pour créer une carte adaptative unique. (Plusieurs cartes peuvent être définies, mais la propriété
iteratorVariable
n'est pas prise en charge ici.)
Conseil :
Dans l'éditeur de flux de dialogue (en mode visuel et en mode YAML), il existe un modèle de cartes adaptatives Microsoft qui contient des exemples de métadonnées que vous pouvez adapter à vos besoins.Pour le moment, Microsoft Teams ne prend pas en charge le carrousel avec des cartes adaptatives. En termes de métadonnées du groupe de pages Réponse commune, cela signifie que la disposition de la carte est ignorée. Les cartes sont toujours disposées verticalement car la disposition horizontale (carrousel) n'est tout simplement pas prise en charge.
Gardez également à l'esprit la limite suivante : lorsqu'un utilisateur touche un bouton sur la carte adaptative, l'étiquette de ce bouton n'est pas affichée sous forme de message d'utilisateur dans l'historique de la conversation. En d'autres termes, l'utilisateur ne reçoit pas de confirmation visuelle de la sélection du bouton. Cela peut entraîner une expérience utilisateur incohérente, car l'étiquette du bouton affiché avec des messages texte simples ou avec des cartes de composant de réponse commune standard (à l'aide de la carte Microsoft Hero), n'est pas affichée.
Exemple : Carte adaptative dans un élément de réponse de type carte
Pour créer plusieurs cartes, vous pouvez utiliser la propriété iteratorVariable
avec l'élément card
dans un élément de réponse de type carte. Voici un exemple d'utilisation d'une carte adaptative pour créer plusieurs cartes de pizza :
responseItems:
- type: "cards"
headerText: "Here are our pizzas you can order today:"
cardLayout: "horizontal"
cards:
- title: "${pizzas.name}"
description: "${pizzas.description}"
imageUrl: "${pizzas.image}"
iteratorVariable: "pizzas"
actions:
- label: "Order Now"
type: "postback"
payload:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
type: "AdaptiveCard"
version: "1.0"
fallbackText: "Adaptive card version not supported"
body:
- type: "TextBlock"
text: "${pizzas.name}"
weight: "bolder"
- type: "TextBlock"
text: "${pizzas.description}"
wrap: true
- type: "Image"
url: "${pizzas.image}"
horizontalAlignment: "center"
actions:
- type: "Action.Submit"
title: "Order"
data:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
Exemple : Carte adaptative dans un élément de réponse textuelle
Vous pouvez définir une carte adaptative avec un élément de réponse textuelle comme suit :
responseItems:
- type: "text"
text: "This text is replaced with adaptive card defined in custom property"
footerText: "Is that correct?"
visible:
expression: "${system.channelType=='msteams' && system.entityToResolve.value.name=='Confirmed'}"
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
type: "AdaptiveCard"
version: '1.0'
fallbackText: "Adaptive card version not supported"
body:
- type: TextBlock
text: 'I have all information needed to create your expense. Just to verify my understanding, here is an overview of your expense:'
wrap: true
- type: FactSet
facts:
- title: Expense Type
value: "${expense.value.Type}"
- title: Amount
value: "${expense.value.Amount.totalCurrency}"
- title: Date
value: "${expense.value.Date.date?number_to_date}"
- title: Receipt URL
value: "${expense.value.Receipt?has_content?then(expense.value.Receipt.url,'N/A')}"
actions:
- type: Action.ShowCard
title: Edit
id: edit
card:
type: AdaptiveCard
version: '1.0'
body:
- type: TextBlock
size: Medium
weight: Bolder
text: Edit Expense
- type: TextBlock
text: Expense Type
weight: Bolder
- type: Input.ChoiceSet
choices:
- title: Metro, bus, train
value: Public transport
- title: Taxi
value: Taxi
- title: Breakfast, lunch, dinner
value: dinner
id: Type
value: "${expense.value.Type!''}"
spacing: None
- type: TextBlock
text: Amount
weight: Bolder
- type: Input.Text
id: amount
spacing: None
value: "${expense.value.Amount?has_content?then(expense.value.Amount.totalCurrency,'')}"
- type: TextBlock
text: Date
weight: Bolder
- type: Input.Date
id: Date
value: "${expense.value.Date?has_content?then(expense.value.Date.date?number_to_date,'')}"
spacing: None
actions:
- type: Action.Submit
title: Submit
id: submit
Vous pouvez également définir plusieurs cartes adaptatives dans cette propriété personnalisée. Pour ce faire, ajoutez un trait d'union (-
) devant la propriété type
afin d'indiquer une liste YAML plutôt qu'un mappage :
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
- type: AdaptiveCard
body: ...
- type: AdaptiveCard
body: ...
Cela peut être pratique si vous devez produire plusieurs cartes statiques, mais il est plus courant de créer plusieurs cartes à l'aide de la propriété iteratorVariable
.
Actions de soumission
Les cartes adaptatives contiennent une action de soumission (Action.Submit
), que vous pouvez utiliser pour collecter les entrées de l'utilisateur et les envoyer à la compétence.
Définissez les données utiles de l'action dans la propriété data
de l'action de soumission. Si vous voulez que le composant de réponse commune effectue une transition après la sélection du bouton ou la définition de certaines variables, vous pouvez utiliser les propriétés action
et variables
standard :
actions:
- type: "Action.Submit"
title: "Order"
data:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
Si vous utilisez des champs d'entrée dans votre carte, le nom et la valeur de ceux-ci seront ajoutés sous la forme de paires clé-valeur à l'objet JSON data
. L'exemple ci-dessus avec la carte Edit Expense (Modifier les frais) inclut trois champs pour modifier le type, le montant et la date des frais. Lorsque l'utilisateur touche le bouton Soumettre dans ce cas, un objet JSON semblable au suivant est envoyé :
{
"Type" : "Taxi",
"Amount" : "10.0 dollar"
"Date" : "2019-09-02"
}
Le composant Réponse commune ne sait pas comment traiter ces informations, car elles ne respectent pas la structure commune des données utiles avec les propriétés action
et variables
. Pour résoudre ce problème, vous disposez des options suivantes :
-
Convertissez les données utiles JSON en chaîne pour laquelle une correspondance sera recherchée parmi les entités. Si des correspondances sont trouvées, la variable définie avec le composant est mise à jour avec la ou les valeurs d'entité correspondantes (en cas d'entité composite).
Pour configurer cette option, ajoutez la propriété booléenne
system.convertToString
booléenne à la propriétédata
de l'action de soumission :actions: - type: Action.Submit title: Submit id: submit data: system.convertToString: true
-
Configurez la compétence pour qu'elle mette à jour les variables portant le même nom que les champs d'entrée. Dans l'exemple ci-dessus, les variables
"Type"
,"Amount"
et"Date"
sont mises à jour.Pour configurer cette option, ajoutez la propriété
system.setVariables
booléenne à la propriétédata
de l'action de soumission :actions: - type: Action.Submit title: Submit id: submit data: system.setVariables: true
Si vous ne configurez aucune de ces options, les valeurs soumises sont simplement ignorées.
Lorsque vous utilisez un composant de réponse commune avec une entité composite, vous utilisez généralement la première option, qui alimente toutes les entités mises en correspondance dans l'entité composite en fonction des données utiles JSON transformées en chaîne.
Vous devez régler la propriété
processUserMessage
du composant à true
pour que ces actions de soumission fonctionnent.
Écho de texte du bouton sélectionné dans une carte adaptative
Lorsqu'un utilisateur sélectionne un bouton dans une carte adaptative, la conversation n'est mise à jour pour refléter ce choix que si vous incluez une action messageBack
pour la carte.
Pour configurer une action messageBack
, voir https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.
Désactiver les boutons et les champs des cartes adaptatives
Bien que vous ne puissiez pas désactiver techniquement les boutons et les champs des cartes adaptatives, vous pouvez créer un effet similaire en remplaçant la carte lorsqu'une action de soumission est appelée. Pour ce faire, utilisez la propriété booléenne replaceMessage
propre à Microsoft Teams dans les composants de réponse commune.
Pour permettre le rendu de la carte de cette façon, ajoutez cette propriété dans la section channelCustomProperties
du composant de réponse personnalisé :
...
- type: "text"
text: "This text is replaced with the adaptive card defined in custom property"
channelCustomProperties:
- channel: "msteams"
properties:
replaceMessage: "true"
adaptiveCard:
...
Vous pouvez également utiliser une expression Apache FreeMarker pour définir la valeur de la propriété.
Conseils pour la création des définitions de cartes adaptatives
Le schéma JSON des cartes adaptatives est relativement complexe et prend en charge de nombreuses constructions. En tant que tel, il est source d'erreur lorsque vous essayez de définir le contenu de la carte adaptative à la main directement dans un composant Common Respone. Il vous semblera peut-être plus simple d'utiliser le processus suivant pour créer les cartes adaptatives :
- Grâce aux outils visuels du concepteur de cartes adaptatives Microsoft, créez la définition de la carte adaptative.
- Cliquez sur Copy Card JSON (Copier l'objet JSON de carte) pour obtenir la définition dans le format JSON.
- Utilisez un convertisseur en ligne (par exemple, https://jsonformatter.org/json-to-yaml) pour convertir la définition au format YAML.
- Copiez le résultat dans un éditeur de texte et insérez l'indentation requise à l'emplacement où il doit apparaître dans la définition du flux de dialogue.
- Collez le texte résultant dans le flux de dialogue.
Pour rester à jour sur la version des cartes adaptatives prises en charge par les équipes, voir https://docs.microsoft.com/en-us/adaptive-cards/resources/partners. Vous pouvez visiter https://adaptivecards.io/explorer/ pour obtenir la liste de tous les éléments et propriétés, et la version à laquelle ils ont été ajoutés.
Gardez à l'esprit que le concepteur de cartes adaptatives ne vérifie pas la combinaison d'éléments utilisés ni le numéro de version des cartes adaptatives. Par exemple, l'élément ActionSet
a été introduit dans la version 1.2, mais le concepteur ne vous empêche pas de l'ajouter, même si vous avez spécifié le numéro de version 1.0 dans le concepteur.
Si vous voulez utiliser des actions avec la version 1.0, vous pouvez utiliser la propriété actions
distincte sous la propriété body
. Cet élément actions
ne peut pas être ajouté à l'aide du concepteur visuel. Vous devrez le faire vous-même.
Désactiver le message de bienvenue pour un assistant numérique
Lorsqu'un utilisateur se connecte à un assistant numérique au moyen d'un canal Microsoft Teams, un message interne lui est envoyé pour lancer une conversation. Par défaut, ce message est le mot "help", qui déclenche ensuite l'intention système help
de l'assistant numérique, ce qui entraîne l'affichage d'un message de bienvenue et de cartes pour les compétences de l'assistant numérique.
Pour désactiver ce comportement, vous remplacez la propriété Internal Welcome Message
par une valeur différente de "help". Vous pouvez modifier la valeur de cette propriété dans l'ensemble de ressources de l'assistant numérique.
Pour modifier le message interne réglé à l'assistant numérique lors de la connexion de l'utilisateur à un canal Teams :
- Cliquez sur
pour ouvrir le menu latéral, sélectionnez Development > Digital Assistants (Développement > Assistants numériques) et ouvrez votre assistant.
- Dans la barre de navigation gauche de l'assistant numérique, cliquez sur
, et sélectionnez l'onglet Configuration.
- Dans le champ Filtre, entrez
internal
pour restreindre rapidement la liste des clés d'ensemble de ressources. - Sélectionnez la clé Autre - internalWelcomeMessage.
- Pointez la valeur de la clé et sélectionnez l'icône
qui s'affiche.
- Remplacez la valeur par celle que vous souhaitez utiliser et cliquez sur Mettre à jour l'entrée.
Si votre assistant numérique se trouve sur une version de plate-forme antérieure à 21.04, les clés d'ensemble de ressources ne sont pas automatiquement définies pour les propriétés de configuration. Dans ce cas, vous pouvez simplement mettre à jour la valeur de la propriété dans la page Paramètres des assistants numériques (que vous pouvez ouvrir en cliquant sur

Activer le message de bienvenue pour une compétence
Par défaut, lorsqu'un utilisateur se connecte directement à une compétence autonome au moyen d'un canal Microsoft Teams, aucun message de bienvenue n'est envoyé à l'utilisateur. Toutefois, si vous configurez la propriété Welcome State (État de bienvenue) de la compétence, celle-ci utilise cet état pour afficher un message lorsque l'utilisateur se connecte.
- Cliquez sur
pour ouvrir le menu latéral, sélectionnez Development > Skills (Développement > Compétences) et ouvrez votre compétence.
- Dans la barre de navigation gauche de la compétence, cliquez sur
et sélectionnez l'onglet Digital Assistant.
- Dans le champ État de bienvenue, entrez le nom de l'état dans lequel vous voulez afficher le message de bienvenue.
L'utilisation de la propriété Welcome State (État de bienvenue) de cette façon pour une compétence autonome ne fonctionne que pour les canaux Microsoft Teams. Pour les autres canaux, cette propriété est ignorée dans les compétences autonomes.