Créer des onglets avec les Cartes adaptatives

Article
12/28/2023

Avertissement

Les onglets Carte adaptative ne sont pas disponibles dans le nouveau client Teams. Le client Teams classic devrait être déprécié d’ici le 31 mars 2024. Si votre application utilise des onglets de carte adaptative, nous vous recommandons de reconstruire l’onglet en tant qu’onglet web. Pour plus d’informations, consultez Onglets de génération pour Teams.

Lorsque vous développez un onglet en utilisant la méthode traditionnelle, vous pouvez rencontrer ces problèmes :

Considérations sur le HTML et le CSS
Temps de chargement lent
Contraintes iFrame
Maintenance et coûts des serveurs

Vous pouvez créer des onglets carte adaptative dans Teams. Au lieu d’incorporer du contenu web dans un iFrame, vous pouvez afficher des cartes adaptatives dans un onglet. Bien que le front-end soit rendu avec des cartes adaptatives, le back-end est alimenté par un bot. Le robot est chargé d'accepter les demandes et de répondre de manière appropriée avec la carte adaptative qui est rendue.

Vous pouvez créer vos onglets à l'aide de modules d'interface utilisateur prêts à l'emploi, natifs des ordinateurs de bureau, du web et des téléphones mobiles. Cet article vous aide à comprendre les modifications à apporter au manifeste de l'application. L’article identifie également comment l’activité d’appel demande et envoie des informations dans l’onglet avec des cartes adaptatives, et son effet sur le flux de travail de la boîte de dialogue modale (appelée module de tâche dans TeamsJS v1.x).

L'image suivante montre des onglets de construction avec les cartes adaptatives sur le bureau et le mobile :

Capture d’écran montrant un exemple de carte adaptative affichée sous les onglets.

Configuration requise

Avant de commencer à utiliser les cartes adaptatives pour construire des onglets, vous devez :

Familiarisez-vous avec le développement de bots, les cartes adaptatives et les dialogues modals dans Teams.
Faites fonctionner un robot dans Teams pour votre développement.

Modifications du manifeste de l'application

Les applications personnelles qui rendent les onglets doivent inclure staticTabsun tableau dans leur manifeste d'application.. Les onglets de la carte adaptative sont rendus lorsque la contentBotIdpropriété est fournie dansstaticTab la définition. Les définitions d'onglets statiques doivent contenir soit un , contentBotIdspécifiant un onglet de carte adaptativecontentUrl, soit un , spécifiant un onglet de contenu Web hébergé typique.

Remarque

La contentBotId propriété est disponible dans le manifeste version 1.9 ou ultérieure.

Indiquez la contentBotIdpropriété avec laquellebotId l'onglet Carte adaptative doit communiquer. La entityIdconfiguration de l'onglet de la carte adaptative est envoyée dans le tabContextparamètre de chaque demande d'invocation, et peut être utilisée pour différencier les onglets de la carte adaptative qui sont alimentés par le même robot. Pour plus d'informations sur les autres champs de définition des onglets statiques, voir le schéma du manifeste.

Voici un exemple de manifeste de l'onglet Carte adaptative :

{
  "$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "1.9",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "0.0.1",
  "developer": {
    "name": "Contoso",
    "websiteUrl": "https://contoso.yourwebsite.com",
    "privacyUrl": "https://contoso.yourwebsite.com/privacy.html",
    "termsOfUseUrl": "https://contoso.yourwebsite.com/terms.html"
  },
  "name": {
    "short": "Contoso",
    "full": "Contoso Home"
  },
  "description": {
    "short": "Add short description here",
    "full": "Add full description here"
  },
  "icons": {
    "outline": "icon-outline.png",
    "color": "icon-color.png"
  },
  "accentColor": "#D85028",
  "configurableTabs": [],
  "staticTabs": [
    {
      "entityId": "homeTab",
      "name": "Home",
      "contentBotId": "00000000-0000-0000-0000-000000000000",
      "scopes": ["personal"]
    },
    {
      "entityId": "moreTab",
      "name": "More",
      "contentBotId": "00000000-0000-0000-0000-000000000000",
      "scopes": ["personal"]
    }
  ],
  "connectors": [],
  "composeExtensions": [],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": [
    "contoso.yourwebsite.com",
    "token.botframework.com"
  ]
}

Invoquer des activités

La communication entre votre onglet de carte adaptative et votre robot se fait par le biais d'activités.invoked’activités. Chaque invoke activité a un nom correspondant. Utilisez le nom de chaque activité pour différencier chaque demande. tab/fetch et tab/submit sont les activités couvertes dans cette section.

Remarque

Les robots doivent envoyer toutes les réponses à l'URL du service. L'URL du service est reçu dans le cadre des données utiles activityentrantes.
La taille de la charge utile de l'invocation a augmenté à 80kb.

Récupérer la carte adaptative pour la rendre dans un onglet

tab/fetch est la première demande d'invocation que votre robot reçoit lorsqu'un utilisateur ouvre un onglet de carte adaptative. Lorsque votre robot reçoit cette requête, il envoie soit une réponse onglet continu , soit une réponse onglet authentifié .de tabulation. La réponse continue inclut un tableau pour les cartes, qui est affiché verticalement dans l’onglet dans l’ordre du tableau.

Remarque

Pour plus d’informations sur la réponse d’authentification , consultez l’authentification.

Le code suivant fournit des exemples de demande et de tab/fetch réponse :

tab/fetch demande

// tab/fetch POST request: agents/{botId}/invoke
{
    "name": "tab/fetch",
    "value: {
        "tabContext": {
            "tabEntityId": "{tab_entity_id}"
        },
        "context": {
            "theme": "default"
            }
    },
    "conversation": {
        "id": "{generated_conversation_id}"
    },
    "imdisplayname": "{user_display_name}"
}

tab/fetch réponse

// tab/fetch **continue** POST response:
{
    "tab": {
        "type": "continue",
        "value": {
            "cards": [
                {
                    "card": adaptiveCard1,
                },
                {
                    "card": adaptiveCard2,
                },
                {
                    "card": adaptiveCard3
                }  
            ]
        },
    },
    "responseType": "tab"
}

Traiter les soumissions de la carte adaptative

Une fois qu'une carte adaptative est rendue dans l'onglet, elle peut répondre aux interactions de l'utilisateur. Cette réponse est traitée par la tab/submitdemande d'invocation.

Lorsqu'un utilisateur sélectionne un bouton dans l'onglet Carte adaptative, la tab/submitdemande est déclenchée vers votre robot avec les données correspondantes via la Action.Submitfonction de la Carte adaptative. Les données de la carte adaptative sont disponibles via la propriété data de la tab/submitdemande. Vous recevez l'une des réponses suivantes à votre demande :

Une réponse de 200code d'état HTTP sans corps. Une réponse 200 vide n'entraîne aucune action de la part du client.
La réponse de 200l'onglet standard continue, comme expliqué dans la carte adaptative de récupération. Une réponse continuee l'onglet déclenche la mise à jour par le client de l'onglet de carte adaptative rendu avec les cartes adaptatives fournies dans le tableau de cartes de la réponse continue.

Le code suivant fournit des exemples de tab/submitdemande et de réponse :

tab/submit demande

// tab/submit POST request: agents/{botId}/invoke:
{
    "name": "tab/submit",
    "value": {
        "data": {
            "type": "tab/submit",
            //...<data properties>
            },
        "context": {
            "theme": "default"
            },
        "tabContext": {
            "tabEntityId": "{tab_entity_id}"
            },
        },
    "conversation": {
           "id": "{generated_conversation_id}" 
        },
    "imdisplayname": "{user_display_name}"
}

tab/submit réponse

//tab/fetch **continue** POST response:
{
    "tab": {
        "type": "continue",
        "value": {
            "cards": [
              {
                "card": adaptiveCard1,
                },
              {
                "card": adaptiveCard2,
                } 
            ]
        },
    },
    "responseType": "tab"
}

Comprendre le flux de travail de dialogue

Les boîtes de dialogue modales utilisent également des cartes adaptatives pour appeler et task/submit demander task/fetch et répondre. Pour plus d’informations, consultez Utilisation de boîtes de dialogue dans les bots Microsoft Teams.

Avec l'introduction de l'onglet Carte adaptative, la façon dont le robot répond à une task/submitdemande a changé. Si vous utilisez un onglet Carte adaptative, le bot répond à la demande d’appel avec la task/submit réponse continue de l’onglet standard et ferme la boîte de dialogue. L'onglet Carte adaptative est mis à jour en rendant la nouvelle liste de cartes fournie dans le corps de réponse de l'onglet continue.

Invoquer `task/fetch`

Le code suivant fournit des exemples detask/fetch demande et de réponse :

task/fetch demande

// task/fetch POST request: agents/{botId}/invoke
{
    "name": "task/fetch",
    "value": {
        "data": {
            "type": "task/fetch"
        },
        "context": {
            "theme": "default",
        },
        "tabContext": {
            "tabEntityId": "{tab_entity_id}"
        }
    },
    "imdisplayname": "{user_display_name}",
    "conversation": {
        "id": "{generated_conversation_id}"
    } 
}

task/fetch réponse

// task/fetch POST response: agents/{botId}/invoke
{
    "task": {
        "value": {
            "title": "Ninja Cat",
            "height": "small",
            "width": "small",
            "card": {
                "contentType": "application/vnd.microsoft.card.adaptive",
                "content": adaptiveCard,
            }
        },
    "type": "continue"
    },
    "responseType": "task"
}

Invoquer `task/submit`

Le code suivant fournit des exemples detask/submit demande et de réponse :

task/submit demande

// task/submit POST request: agent/{botId}/invoke:
{
    "name": "task/submit",
    "value": {
        "data": {serialized_data_object},
        "context": {
            "theme": "default"
        },
    "tabContext": {
        "tabEntityId": "{tab_entity_id}"
        },
    },
    "conversation": {
        "id": "{generated_conversation_id}"
    },
    "imdisplayname": "{user_display_name}",
}

task/submit onglet type de réponse

// tab/fetch **continue** POST response: 
{
    "task":{
        "value": {
            "tab": {
                "type": "continue",
                "value": {
                    "cards": [
                        {
                            "card": adaptiveCard1
                        },
                        {
                            "card": adaptiveCard2
                        }
                    ]
                }
            }
        },
        "type": "continue"
    },
    "responseType": "task"
}

Authentification

Dans les sections précédentes, vous avez vu que la plupart des paradigmes de développement peuvent être étendus à partir des demandes et réponses de boîte de dialogue en demandes et réponses d’onglet. En ce qui concerne la gestion de l'authentification, le flux de travail pour l'onglet Carte adaptative suit le modèle d'authentification pour les extensions de message. Pour plus d'informations, voir Ajouter l'authentification.

tab/fetch les demandes peuvent avoir une réponse continue ou une réponse d’authentification . Lorsqu'une tab/fetchrequête est déclenchée et qu'elle reçoit une réponse d'authentification par onglet, la page de connexion est affichée à l'utilisateur..

Pour obtenir un code d'authentification en invoquant tab/fetch

Ouvrez votre application. La page de connexion apparaît.

Remarque

Le logo de l'application est fourni par la iconpropriété définie dans le manifeste de l'application. Le titre apparaissant après le logo est défini dans la titlepropriété retournée dans le corps de la réponse de l'onglet d'authentification.
Sélectionnez Connexion. Vous êtes redirigé vers l'URL d'authentification fournie dans la valuepropriété du corps de la réponse d'authentification.
Une fenêtre contextuelle apparaît. Cette fenêtre pop-up héberge votre page web en utilisant l'URL d'authentification.
Après vous être connecté, fermez la fenêtre. Un code d'authentification est envoyé au client Teams.
Le client Teams réitère ensuite la tab/fetchdemande à votre service, qui inclut le code d'authentification fourni par votre page Web hébergée.

`tab/fetch` flux de données d’authentification

L'image suivante donne une vue d'ensemble du fonctionnement du flux de données d'authentification pour une tab/fetchinvocation.

Capture d’écran montrant l’exemple de flux d’authentification tabulation de carte adaptative.

tab/fetchExemple de flux d'authentification de l'onglet Carte adaptative.

Le code suivant fournit un exemple de réponse tab/fetchd'authentification :

// tab/auth POST response (openURL)
{
    "tab": {
        "type": "auth",
        "suggestedActions":{
            "actions":[
                {
                    "type": "openUrl",
                    "value": "https://example.com/auth",
                    "title": "Sign in to this app"
                }
            ]
        }
    }
}

Exemple

Le code suivant montre un exemple de demande rééditée :

{
    "name": "tab/fetch",
    "type": "invoke",
    "timestamp": "2021-01-15T00:10:12.253Z",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "{id}",
        "name": "John Smith",
        "aadObjectId": "00000000-0000-0000-0000-000000000000"
    },
    "conversation": {
        "tenantId": "{tenantId}",
        "id": "tab:{guid}"
    },
    "recipients": {
        "id": "28:00000000-0000-0000-0000-000000000000",
        "name": "ContosoApp"
    },
    "entities": [
        {
            "locale": "en-us",
            "country": "US",
            "platform": "Windows",
            "timezone": "America/Los_Angeles",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": { "id": "00000000-0000-0000-0000-000000000000" },
        "source": { "name": "message" }
    },
    "value": {
        "tabContext": { "tabEntityId": "homeTab" },
        "state": "0.43195668034524815"
    },
    "locale": "en-US",
    "localTimeZone": "America/Los_Angeles"
}

Exemple de code

Exemple de nom	Description	.NET	Node.js	Manifeste
Afficher les cartes adaptatives dans l'onglet Équipes	L'exemple de code de l'onglet Microsoft Teams, qui montre comment afficher les cartes adaptatives dans Teams.	View	View	View

Créer des onglets avec les Cartes adaptatives

Configuration requise

Modifications du manifeste de l'application

Invoquer des activités

Récupérer la carte adaptative pour la rendre dans un onglet

Traiter les soumissions de la carte adaptative

Comprendre le flux de travail de dialogue

Invoquer `task/fetch`

Invoquer `task/submit`

Authentification

`tab/fetch` flux de données d’authentification

Exemple

Exemple de code

Guide pas à pas

Étape suivante

Voir aussi

Commentaires

Ressources supplémentaires

Créer des onglets avec les Cartes adaptatives

Configuration requise

Modifications du manifeste de l'application

Invoquer des activités

Récupérer la carte adaptative pour la rendre dans un onglet

Traiter les soumissions de la carte adaptative

Comprendre le flux de travail de dialogue

Invoquer task/fetch

Invoquer task/submit

Authentification

tab/fetch flux de données d’authentification

Exemple

Exemple de code

Guide pas à pas

Étape suivante

Voir aussi

Commentaires

Ressources supplémentaires

Invoquer `task/fetch`

Invoquer `task/submit`

`tab/fetch` flux de données d’authentification