Microsoft Teams
Lorsque vous configurez un canal Microsoft Teams, les utilisateurs peuvent discuter avec votre assistant numérique (ou avec une brique autonome) via l'interface utilisateur Microsoft Teams.
Voici le processus de configuration d'un canal :
- Dans le portail de développement de Microsoft Teams, créez une application et ajoutez un bot à cette application.
- A l'aide de l'ID d'application et du mot de passe du bot, créez un canal dans Digital Assistant.
- Copiez l'URL de webhook générée lors de la création du canal et ajoutez-la au bot.
- Testez votre assistant numérique dans Microsoft Teams.
Les briques et les assistants numériques mis à disposition via les canaux Microsoft Teams peuvent également être inclus dans les discussions de groupe. Reportez-vous à Discussions de groupe.
Etape 1 : création d'un bot
Pour mettre à disposition votre assistant numérique (ou votre brique autonome) dans Microsoft Teams, vous devez créer les éléments suivants via le portail Développeur d'équipes :
- Une application Microsoft Teams. Cette application est le conteneur du bot que vous créez et votre moyen d'accès au bot dans Teams.
- Un bot. Il s'agit de l'artefact de l'application qui communique avec Oracle Digital Assistant
Le portail des développeurs d'équipes 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 télécharger l'application sur votre cloud national. Pour plus d'informations, reportez-vous à Portail des développeurs pour les équipes et à Déploiements cloud nationaux sur le site de Microsoft.
Procédez comme suit :
- Accédez à https://dev.teams.microsoft.com/home et connectez-vous avec votre compte Microsoft.
- Dans la navigation de 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 bot que vous allez créer ultérieurement.)
- Sur la page Informations de base, renseignez les champs obligatoires restants à l'exception de l'ID de l'application (client), puis cliquez sur Enregistrer.
Remarque
Ce champ n'est nécessaire que si vous configurez le bot pour l'accès avec connexion unique. Reportez-vous à Configuration de l'authentification unique pour les canaux Microsoft Teams. - Dans la navigation de gauche de la page, sous la section Configurer, sélectionnez Fonctionnalités d'application.
- Cliquez sur Bot.
- Cliquez sur le lien Créer un bot.
- Sur la page Gestion des bots, cliquez sur + Nouveau bot.
- Dans la boîte de dialogue Ajouter un bot, entrez le nom du bot.
- Dans la section Canaux de la page, cochez la case Microsoft Teams et cliquez sur Enregistrer.
- Dans la section Clés secrètes client, sélectionnez Ajouter une clé secrète client pour le bot.
- Copiez la valeur de la clé secrète client générée et enregistrez-la dans un emplacement sûr de votre système.
- Dans la section Clés secrètes client de la page, cliquez avec le bouton droit de la souris sur le lien Azure pour ouvrir la page Inscriptions d'application d'Azure Active Directory dans un onglet de navigateur distinct.
- Sur la page Inscriptions d'application, sélectionnez la ressource de bot que vous avez créée.
- Dans le rail de gauche, sélectionnez authentification.
- Dans la section Types de compte pris en charge de la page, sélectionnez l'option colocative (Comptes dans n'importe quel annuaire organisationnel (Tenant d'ID Entra Microsoft - Multitenant).
- Si vous souhaitez pouvoir utiliser des événements externes pour envoyer des messages aux utilisateurs via un canal Microsoft Teams, ajoutez des droits d'accès permettant d'extraire le profil utilisateur via l'API Microsoft Graph. (La fonctionnalité d'événements externes utilise les données utilisateur mises en cache à partir de conversations passées pour générer des notifications ou lancer des conversations de manière proactive avec l'utilisateur.) Pour ajouter ces autorisations, procédez comme suit :
- Dans la navigation de gauche de la page Inscriptions d'application du bot, sélectionnez Droits d'accès d'API.
- Cliquez sur Ajouter un droit d'accès.
- Dans la boîte de dialogue Demander des droits d'accès à l'API, sélectionnez Microsoft Graph.
- Sélectionnez Autorisations d'application.
- Sélectionnez le droit d'accès Directory.Read.All et cliquez sur Ajouter des droits d'accès.
- Une fois le droit d'accès affiché dans la liste Droits d'accès configurés, sélectionnez-le, cliquez sur Octroyer le consentement de l'administrateur pour..., puis sur Oui dans la boîte de dialogue Octroyer le consentement de l'administrateur.
-
Revenez à l'onglet dans lequel le portail de développeur est ouvert dans votre navigateur.
-
Dans la navigation de gauche, cliquez sur Applications, puis sélectionnez l'application.
-
Dans la navigation de gauche de l'application, sélectionnez Fonctionnalités de l'application.
-
Cliquez sur la mosaïque Bot.
-
Dans la liste déroulante située sous Sélectionner un bot existant, sélectionnez le bot que vous venez de créer.
-
Encore une fois, dans la navigation de gauche de l'application, sélectionnez Fonctionnalités de l'application.
-
Dans le titre Bot, copiez l'ID de bot et enregistrez-le dans un fichier texte.
Remarque
Vous devrez peut-être transcrire manuellement l'ID de bot.Vous aurez besoin de cet ID lors de la création du canal dans Digital Assistant.
- Dans la section Portées de la page, sélectionnez Personnel.
(Vous pouvez également sélectionner d'autres portées, mais Personnel est requis pour que le bot réponde.)
-
Cliquez sur Enregistrer.
-
Si vous le souhaitez, dans la navigation de gauche de la page, sous la section Configurer, sélectionnez Domaines et ajoutez les domaines dont les utilisateurs du bot peuvent provenir.
-
Laissez le portail de développeur ouvert dans votre navigateur.
Vous terminerez l'inscription ultérieurement avec une URL de webhook que vous obtiendrez lors de la création du canal dans Digital Assistant.
Etape 2 : création d'un canal dans Digital Assistant
-
Dans une autre fenêtre ou un autre onglet de navigateur, ouvrez Digital Assistant, cliquez sur Canaux dans le menu de gauche et sélectionnez Utilisateurs.
-
Cliquez sur + Canal pour ouvrir la boîte de dialogue Créer un canal.
-
Nommez votre canal.
-
Choisissez Microsoft Teams comme type de canal.
-
Renseignez ID de bot Microsoft avec l'ID du bot Microsoft que vous avez créé.
-
Entrez le mot de passe de bot Microsoft (valeur de clé secrète client) avec la valeur de clé secrète client (à ne pas confondre avec l'ID de clé secrète client) générée pour le bot.
-
Cliquez sur Créer.
-
Sur la page Canaux, copiez l'URL de webhook et collez-la dans un emplacement pratique de votre système.
-
Cliquez sur
et sélectionnez l'assistant numérique ou la brique à associer au canal.
-
Activez la commande Canal activé.
Etape 3 : configuration de l'URL de webhook pour Microsoft Teams
Maintenant, vous devez revenir en arrière et terminer la configuration dans Microsoft Teams.
-
Revenez à l'onglet du navigateur dans lequel le portail Teams Developer Portal est ouvert.
-
Dans la navigation à l'extrême gauche de la page, sélectionnez l'icône Outils, puis cliquez sur Gestion des bots.
-
Sélectionnez le bot que vous avez créé.
- Sur la page du bot, sélectionnez l'onglet Configurer.
-
Dans le champ Adresse d'adresse de bot, collez l'URL de webhook que vous avez obtenue lors de la création du canal dans Digital Assistant, puis cliquez sur Enregistrer.
Etape 4 : activation des applications dans votre locataire Office 365
Vous devez ensuite demander à l'administrateur Office 365 de configurer votre locataire de façon à effectuer les opérations suivantes :
- Autoriser les applications externes dans Microsoft Teams.
- Autoriser le chargement annexe d'applications externes.
- Autoriser les nouvelles applications externes par défaut.
Pour la procédure détaillée, reportez-vous à https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant.
Etape 5 : test dans Microsoft Teams
Une fois que vous avez fini de configurer la messagerie et le canal Microsoft Teams, vous pouvez tester votre assistant numérique (ou votre brique) dans Microsoft Teams. Pour ce faire, procédez comme suit :
- Sur la page de l'application que vous avez créée avec le portail Microsoft Developer Portal, cliquez sur le bouton Aperçu dans les équipes.
Configuration de l'authentification unique pour les canaux Microsoft Teams
Si vous voulez qu'un assistant numérique ou une brique exige la même authentification que celle que vous avez définie pour Microsoft Teams, vous pouvez configurer l'authentification SSO (accès avec connexion unique) pour cet assistant numérique ou cette brique dans Microsoft Teams.
Une fois cette authentification SSO configurée, les utilisateurs peuvent se connecter à Teams avec leurs informations d'identification Azure Active Directory (Azure AD), puis interagir directement avec l'assistant numérique, sans devoir se reconnecter.
Les applications back-end accessibles via l'assistant numérique doivent prendre en charge directement les jetons d'accès Azure AD. Les clients Fusion-based Cloud Applications (FA) utilisant Teams peuvent également avoir l'accès avec connexion unique activé 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é par Teams ne peut actuellement pas être utilisé directement pour communiquer avec FA. Pour remédier à cette divergence, vous pouvez implémenter une solution personnalisée pour un échange de jetons. Consultez ce billet de blog pour plus de détails.
Voici la procédure générale de configuration de SSO pour un canal Microsoft Teams :
- Si vous ne l'avez pas déjà fait, créez un canal Microsoft Teams comme décrit dans les rubriques précédentes.
- Créez une application Azure AD sur le portail Azure.
- Mettez à jour l'inscription de bot Microsoft avec les détails SSO.
- Dans Oracle Digital Assistant, inscrivez l'application Azure AD en tant que service d'authentification de la plate-forme d'identité Microsoft.
- Activez l'authentification dans vos briques via le service d'authentification que vous avez inscrit.
Création d'une application Azure AD
Pour configurer SSO pour une brique 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 de ce qui suit :
- Compte Azure avec abonnement actif
- ID d'application Microsoft pour le bot que vous avez configuré avec votre canal Microsoft Teams
- Accès administrateur au portail Azure
Voici la procédure de création d'une application Azure AD pour SSO :
- Créez une inscription d'application :
- Accédez à https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade sur le portail Azure.
- Cliquez sur Nouvelle inscription.
- Remplissez le champ Nom.
- Dans la section Types de compte pris en charge, sélectionnez le bouton radio Comptes dans n'importe quel répertoire d'organisation (tout répertoire Azure AD colocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox).
- Cliquez sur Inscrire.
Une fois l'application créée, vous accédez à la section Aperçu. L'ID d'application (client) et l'ID de répertoire (locataire) doivent être créés pour votre application.
- Ajoutez une configuration de plate-forme Web :
- Dans la navigation de gauche, sélectionnez Authentification.
- Sous Configurations de plate-forme, cliquez sur Ajouter une plate-forme et sélectionnez Web.
- Ajoutez un URI de réacheminement au format suivant :
<YOUR_Oracle-Digital-Assistant_URL>/connectors/v2/callback
- Cliquez sur Configurer.
- Créez une clé secrète client :
- Dans la navigation de gauche, sélectionnez Certificats et clés secrètes.
- Cliquez sur + Nouvelle clé secrète client, remplissez les champs requis, puis cliquez sur Ajouter.
- Copiez la valeur de clé secrète client et stockez-la dans un emplacement sécurisé. Vous aurez besoin de cette valeur ultérieurement.
- Configurez le jeton :
- Dans la navigation de gauche, sélectionnez Configuration de jeton.
- Cliquez sur + Ajouter une déclaration facultative.
- Dans Type de jeton, sélectionnez Accès.
- Sélectionnez les déclarations suivantes :
- given_name
- upn
- Cliquez sur Ajouter.
- Sélectionnez l'option Activer les droits d'accès de profil de courriel Microsoft Graph (requis pour que les déclarations apparaissent dans le jeton) et cliquez sur Ajouter.
- Dans la navigation de gauche, sélectionnez Droits d'accès d'API.
Vous pouvez constater que trois droits d'accès sont créés.
- Cliquez sur + Ajouter un droit d'accès et ajoutez User.ReadBasic.All.
Vous en aurez besoin pour accéder aux informations de profil.
- Définissez l'URI d'ID d'application :
- Dans la navigation de gauche, sélectionnez Exposer une API.
- Cliquez sur le champ URI d'ID d'application.
- Mettez à jour la valeur au format suivant :
api://botid-<Microsoft_App_ID_for_your_bot>
Remarque
Il doit s'agir de l'ID d'application du bot, pas de celui de l'application SSO. - Cliquez sur + Ajouter une portée.
- Dans le panneau qui apparaît, effectuez les opérations suivantes :
- Définissez
access_as_user
comme nom de portée.La partie domaine du nom de portée affiché juste en dessous du champ de texte doit automatiquement correspondre à l'URI d'ID d'application défini à l'étape précédente, avec
/access_as_user
ajouté à la fin. - Définissez Qui peut accepter ? sur Administrateurs et utilisateurs.
- Définissez
- Remplissez les champs de configuration des invites de consentement administrateur et utilisateur avec les valeurs appropriées pour la portée
access_as_user
.Voici quelques suggestions :
- Titre du consentement administrateur : Teams peut accéder au profil de l'utilisateur.
- Description du consentement administrateur : Permet à Teams d'appeler les API Web de l'application sous le nom de l'utilisateur en cours.
- Titre du consentement utilisateur : Teams peut accéder à votre profil utilisateur et effectuer des demandes en votre nom.
- Description du consentement utilisateur : Autorisez Teams à appeler les API de cette application avec les mêmes droits que vous.
- Assurez-vous que Etat est défini sur Activé.
- Dans la section Applications client autorisées, cliquez sur + Ajouter une application client.
- 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.
- Mettez à jour le manifeste :
- Dans la navigation de gauche, sélectionnez Manifeste.
- Définissez
"acceptMappedClaims"
surtrue
. - Définissez
"accessTokenAcceptedVersion"
sur2
. - Cliquez sur Enregistrer.
- Accordez des droits d'accès d'administrateur de locataires à l'application Azure AD.
- Dans la navigation de gauche, sélectionnez Aperçu.
- Copiez l'ID d'application (client), l'ID de répertoire (locataire) et l'URI d'ID d'application, et enregistrez-les dans un emplacement pratique.
- Dans une fenêtre de navigateur privée, connectez-vous au compte d'administrateur Microsoft.
L'URL présente le format suivant :
où vous remplacezhttps://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>
<tenant-id>
par l'ID de répertoire (locataire) que vous venez de copier, et<client-id>
par l'ID d'application (client) que vous venez de copier.
- Dans la boîte de dialogue Droits d'accès demandés, vérifiez et acceptez les droits d'accès.
Mise à jour de l'inscription de bot avec les détails SSO
Mettez à jour votre bot Microsoft avec les détails SSO que vous avez configurés :
- Ouvrez le bot dans le portail Teams Developer et ouvrez l'éditeur de manifeste.
- Sélectionnez l'onglet Informations de base.
- Faites défiler l'affichage jusqu'au champ ID (client) d'application et insérez l'ID (client) d'application.
- Sélectionnez l'onglet Authentification unique.
- Dans l'URI d'ID d'application, ajoutez l'URI d'ID d'application que vous avez copié précédemment.
- Dans la navigation de gauche, sélectionnez Publier vers l'organisation.
Inscription de l'application Azure AD en tant que service d'authentification dans Digital Assistant
Vous allez maintenant inscrire l'application Azure AD en tant que service d'authentification dans Oracle Digital Assistant.
-
Dans une fenêtre ou un onglet de navigateur distinct, ouvrez Digital Assistant, développez Paramètres dans le menu de gauche, puis sélectionnez Services d'authentification.
- Cliquez sur + Service.
- Dans la boîte de dialogue Nouveau service d'authentification, entrez les valeurs suivantes :
- Fournisseur d'identités : Plate-forme d'identité Microsoft
- Nom : nom permettant d'identifier le service d'authentification.
- URL endpoint de jeton : URL du fournisseur d'identités pour la demande de jetons d'accès. Utilisez :
https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token
- Adresse d'autorisation : URL du fournisseur d'identités pour la page avec laquelle les utilisateurs s'authentifient en entrant leur nom utilisateur et leur mot de passe. Utilisez :
https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize
- ID client et clé secrète client : ID et clé secrète client pour l'application Azure AD (client OAuth) inscrite. Utilisez l'ID et la clé secrète d'application.
- Portée :
<Application(client)_ID_for_your_bot>/access_as_user
- Déclaration du sujet : déclaration de profil access-token à utiliser pour identifier l'utilisateur. Utilisez le courriel.
Référencement du service d'authentification à partir de vos briques
Dans les briques nécessitant une authentification SSO, intégrez le composant OAuth 2.0 Account Link dans le flux de dialogue pour gérer l'authentification via le service d'authentification. Dans ce composant, veillez à définir la propriété enableSingleSignOn
sur true
. (Pour les flux de dialogue basés sur YAML, le composant est appelé System.OAuth2AccountLink.)
Conseil :
Si vous ne voulez pas coder en dur le nom du service d'authentification dans le composant, vous pouvez créer un paramètre personnalisé que vous transmettez au composant. Reportez-vous à Paramètres personnalisés.Fonctionnalités prises en charge
Les canaux Microsoft Teams dans Digital Assistant prennent en charge les fonctionnalités suivantes :
- texte (envoi et réception),
- images (envoi et réception),
- fichiers (envoi et réception),
- emojis (envoi et réception),
- liens,
- postbacks,
- propriétés personnalisées,
- composants de carrousel,
- composants de liste.
Si vous ciblez votre brique sur plusieurs canaux avec des fonctionnalités et une syntaxe de formatage différentes, vous pouvez utiliser le balisage HTML de base dans vos messages. Si vous le faites, ce balisage sera automatiquement converti au format de balisage Microsoft Teams lorsque le message sera transmis au canal. Cela est particulièrement utile si vous ciblez vos compétences sur d'autres canaux en plus de Microsoft Teams. Reportez-vous à Formatage de texte enrichi dans les canaux.
Contraintes imposées aux messages
Les canaux Microsoft Teams dans Digital Assistant présentent les contraintes de message suivantes :
- Messages texte
- Longueur maximale du libellé d'action de texte : 1 ligne (environ 50 caractères)
- Types d'action de texte autorisés : postback, appel, URL
- Cartes horizontales
- Longueur maximale du titre : 2 lignes (environ 80 caractères)
- Longueur maximale de la description : 25 000 caractères
- Longueur maximale du libellé d'action de carte : 1 ligne (environ 50 caractères)
- 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 de carte 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 : postback, appel, URL.
- Types d'action de liste de cartes autorisés : postback, appel, URL.
- Cartes verticales
- Longueur maximale du titre : 2 lignes (environ 80 caractères)
- Longueur maximale de la description : 25 000 caractères
- Longueur maximale du libellé d'action de carte : 1 ligne (environ 50 caractères)
- 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 : postback, appel, URL.
- Types d'action de liste de cartes autorisés : postback, appel, URL
- Messages de pièce jointe
- Pris en charge ? : oui
- Types d'action de carte autorisés : postback, appel, URL
- Boutons d'action
- Longueur maximale du libellé d'action globale : 1 ligne (environ 50 caractères)
- Nombre maximal d'actions globales : 6
- Types d'action globale autorisés : postback, appel, URL
Cartes adaptatives dans Microsoft Teams
Pour les briques mises à disposition via les canaux Microsoft Teams dans Oracle Digital Assistant, vous pouvez utiliser des cartes adaptatives.
Pour ce faire, utilisez l'élément channelCustomProperties
d'un composant Réponse commune et définissez la propriété type
sur "AdaptiveCard"
.
Vous pouvez l'utiliser aux niveaux suivants du composant :
- Au niveau d'un élément de carte contenu dans un élément de réponse
cards
. Cela vous permet de définir une structure de carte adaptative unique qui sera appliquée plusieurs fois lorsqu'une propriétéiteratorVariable
est spécifiée pour l'élément de carte. - Au niveau d'un élément de réponse texte, généralement pour créer une carte adaptative unique. (Vous pouvez définir plusieurs cartes, mais la propriété
iteratorVariable
n'est pas prise en charge ici.)
Conseil :
Dans l'éditeur de flux de dialogue (en mode de boîte de dialogue Visual et YAML), un modèle de cartes adaptatives Microsoft contient des exemples de métadonnées que vous pouvez adapter à vos besoins.Pour le moment, Microsoft Teams ne prend pas en charge les carrousels comportant des cartes adaptatives. Dans le contexte des métadonnées du composant Common Response, cela signifie que la propriété de disposition de la carte est ignorée. Les cartes sont toujours présentées verticalement car leur disposition horizontale (carrousel) n'est tout simplement pas prise en charge.
Vous devez également garder à l'esprit que lorsqu'un utilisateur touche un bouton inclus avec la carte adaptative, le libellé de celui-ci n'est pas affiché comme un message utilisateur dans l'historique de la conversation. En d'autres termes, l'utilisateur n'obtient pas de confirmation visuelle du bouton sélectionné. Cela peut entraîner une expérience utilisateur incohérente, car les boutons affichés avec des messages texte simples ou les boutons affichés avec des cartes standard du composant Réponse commune (à l'aide de la carte Microsoft) affichent le libellé du bouton.
Exemple : carte adaptative dans un élément de réponse de cartes
Pour appliquer plusieurs cartes, vous pouvez utiliser l'élément iteratorVariable
avec l'élément card
d'un élément de réponse de type cartes. Voici un exemple d'utilisation d'une carte adaptative pour appliquer 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 texte
Vous pouvez définir une carte adaptative avec un élément de réponse texte 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 préfixe à la propriété type
avec un tiret (-
) pour indiquer une liste YAML plutôt qu'une correspondance :
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
- type: AdaptiveCard
body: ...
- type: AdaptiveCard
body: ...
Ceci peut s'avérer utile si vous devez appliquer plusieurs cartes statiques, mais en règle générale vous appliquerez plusieurs cartes à l'aide de la propriété iteratorVariable
.
Actions de soumission
Les cartes adaptatives disposent d'une action de soumission (Action.Submit
) que vous pouvez utiliser pour collecter les saisies utilisateur et les envoyer à la brique.
Vous devez définir la charge utile de l'action dans la propriété data
de l'action de soumission. Pour que le composant Common Response (Réponse commune) effectue une transition lorsque le bouton est sélectionné ou définisse des variables, vous pouvez utiliser les propriétés standard action
et variables
:
actions:
- type: "Action.Submit"
title: "Order"
data:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
Si vous utilisez des champs de saisie dans votre carte, le nom et la valeur de ces champs seront ajoutés en tant que paires clé-valeur à l'objet JSON data
. L'exemple ci-dessus pour la carte Modifier les dépenses inclut trois champs permettant de modifier le type de dépense, le montant et la date. Dans cet exemple, lorsque l'utilisateur appuie sur le bouton Soumettre, 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 il ne suit pas la même structure de charge utile commune que les propriétés action
et variables
. Pour résoudre ce problème, vous disposez des options suivantes :
-
Convertissez la charge utile JSON en une chaîne qui sera ensuite mise en correspondance avec les entités. Si des correspondances sont trouvées, la variable définie par le composant est mise à jour avec la valeur d'entité correspondante (ou les valeurs d'entité dans le cas d'une entité de conteneur composite).
Pour configurer cette option, ajoutez la propriété booléenne
system.convertToString
à la propriétédata
de l'action de soumission :actions: - type: Action.Submit title: Submit id: submit data: system.convertToString: true
-
Mettez à jour les variables de la brique de façon à utiliser le même nom que les champs d'entrée. Dans l'exemple ci-dessus, les variables
"Type"
,"Amount"
et"Date"
seraient mises à jour.Pour configurer cette option, ajoutez la propriété booléenne
system.setVariables
à 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 seront simplement ignorées.
Lorsque vous utilisez un composant Réponse commune avec une entité de conteneur composite, vous utilisez généralement la première option, qui renseigne toutes les entités correspondantes du conteneur sur la base de la charge utile JSON indiquée sous forme de chaîne.
Vous devez définir la propriété
processUserMessage
du composant sur true
pour que ces actions de soumission fonctionnent.
Mention du texte du bouton sélectionné dans la carte adaptative
Lorsqu'un utilisateur sélectionne un bouton dans une carte adaptative, la conversation n'est pas mise à jour pour montrer que l'utilisateur a sélectionné cette option, sauf si vous incluez une action messageBack
pour la carte.
Pour configurer une action messageBack
, reportez-vous à https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.
Désactivation des boutons et des champs dans les cartes adaptatives
Bien que vous ne puissiez pas désactiver techniquement les boutons et les champs dans les 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 aux composants Microsoft Teams in Common Response.
Pour permettre l'affichage de la carte de cette manière, 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 de définitions de cartes adaptatives
Le schéma JSON des cartes adaptatives est relativement complexe et prend en charge de nombreuses structures différentes. C'est pourquoi des erreurs sont susceptibles de survenir lorsque vous essayez de définir manuellement le contenu de la carte adaptative directement dans un composant Common Respone. Nous vous recommandons d'utiliser la procédure suivante pour créer des cartes adaptatives :
- Utilisez les outils visuels du concepteur de cartes adaptatives de Microsoft pour créer une définition de carte adaptative.
- Cliquez sur Copier le fichier JSON de la carte pour obtenir la définition au format JSON.
- Utilisez un convertisseur en ligne (tel que https://jsonformatter.org/json-to-yaml) pour convertir la définition en YAML.
- Copiez le résultat dans un éditeur de texte et insérez la mise en retrait nécessaire à l'endroit où celui-ci apparaît dans la définition de flux de dialogue.
- Collez le texte obtenu dans le flux de dialogue.
Pour rester à jour sur la version des cartes adaptatives prises en charge par Teams, reportez-vous à https://docs.microsoft.com/en-us/adaptive-cards/resources/partners. Vous pouvez consulter https://adaptivecards.io/explorer/ pour obtenir la liste de l'ensemble des éléments et des propriétés, ainsi que la version dans laquelle ils ont été introduits.
N'oubliez pas que le concepteur de cartes adaptatives ne vérifie pas la combinaison entre les éléments utilisés et 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 d'ajouter cet élément, même si vous avez spécifié le numéro de version 1.0.
Pour utiliser des actions avec la version 1.0, vous pouvez utiliser la propriété actions
distincte située sous la propriété body
. Cet élément actions
ne peut pas être ajouté à l'aide du concepteur visuel. Vous devez donc le faire manuellement.
Désactivation du message de bienvenue pour un assistant numérique
Lorsqu'un utilisateur se connecte à un assistant numérique via un canal Microsoft Teams, un message interne est envoyé à l'assistant numérique pour lancer une conversation. Par défaut, ce message est le mot "aide", 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 briques 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 le groupe de ressources de l'assistant numérique.
Pour modifier le message interne défini sur l'assistant numérique lorsque l'utilisateur se connecte à une équipe, canal :
- Cliquez sur
pour ouvrir le menu latéral, sélectionnez Développement > Assistants numériques, puis ouvrez l'assistant numérique.
- Dans la barre de navigation de gauche de l'assistant numérique, cliquez sur
, et sélectionnez l'onglet Configuration.
- Dans le champ Filtre, saisissez
internal
pour réduire rapidement la liste des clés de regroupement de ressources. - Sélectionnez la clé Autre - internalWelcomeMessage.
- Placez le pointeur de la souris sur la valeur de la clé et sélectionnez l'icône
qui apparaît.
- 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 à la version 21.04, les clés de groupe 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é sur la page Paramètres des assistants numériques (que vous pouvez ouvrir en cliquant sur

Activer le message de bienvenue pour une brique
Par défaut, lorsqu'un utilisateur se connecte directement à une brique autonome via un canal Microsoft Teams, aucun message de bienvenue n'est envoyé à l'utilisateur. Toutefois, si vous configurez la propriété Welcome State de la brique, celle-ci utilisera cet état pour afficher un message lorsque l'utilisateur se connectera.
- Cliquez sur
pour ouvrir le menu latéral, sélectionnez Développement > Briques, puis ouvrez votre brique.
- Dans la barre de navigation de gauche de la brique, cliquez sur
et sélectionnez l'onglet Assistant numérique.
- Dans le champ Etat de bienvenue, entrez le nom de l'état dans lequel vous souhaitez afficher le message de bienvenue.
L'utilisation de la propriété Etat de bienvenue de cette manière pour une brique autonome ne fonctionne que pour les canaux Microsoft Teams. Pour les autres canaux, cette propriété est ignorée dans les briques autonomes.