Déploiement de lien

Importante

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du Kit de développement logiciel (SDK) Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de message - Kit de développement logiciel (SDK) v3 dans le dossier Ressources de la documentation.

Le document vous guide sur la façon d’ajouter un déploiement de lien au manifeste de votre application à l’aide du Portail des développeurs et manuellement. Avec le déploiement de liens, votre application peut s’inscrire pour recevoir une activité de invoke lorsque les URL d’un domaine particulier sont collées dans la zone de composition des messages. invoke contient l’URL complète, qui a été collée dans la zone de rédaction du message. Vous pouvez répondre à l’aide d’une carte que l’utilisateur peut déployer, et qui fournit des informations ou des actions supplémentaires. Cela fonctionne comme une commande de recherche avec l’URL servant de terme de recherche. Vous pouvez maintenant ajouter un déploiement de lien à Microsoft Teams sans installer l’application.

Capture d’écran montrant l’expérience de déploiement de lien dans une conversation d’arborescence pour une application Teams installée ou non installée dans Teams et d’autres applications lorsque le lien est collé dans la zone de message de composition Teams.

Remarque

  • Actuellement, le déploiement de liens n’est pas pris en charge sur les clients mobiles.
  • Le résultat du déploiement du lien est mis en cache pendant 30 minutes.
  • Les commandes d’extension de messagerie ne sont pas requises pour le déploiement de liaison. Toutefois, il doit y avoir au moins une commande dans le manifeste, car il s’agit d’une propriété obligatoire dans les extensions de messagerie. Pour plus d’informations, consultez composer des extensions.

L’image suivante est un exemple de déploiement de lien à l’aide de l’extension de message Azure DevOps. Lorsque le lien Azure DevOps est collé dans la zone de rédaction du message Teams, le lien se déploie dans une carte avec les détails de l’élément de travail :

Capture d’écran de l’exemple d’url de lien pour les liens Azure Dev Ops collés dans la zone de message de composition des équipes.

Pour en savoir plus sur le déploiement des liens, consultez la vidéo suivante :


Pour ajouter un déploiement de lien à votre manifeste d’application, ajoutez un nouveau tableau messageHandlers à la section composeExtensions de votre manifeste d’application JSON. Vous pouvez ajouter le tableau à l’aide du Portail des développeurs ou manuellement. Les listes de domaines peuvent inclure des caractères génériques, par exemple *.example.com. Cela correspond exactement à un segment du domaine, si vous devez faire correspondre a.b.example.com, puis utilisez *.*.example.com.

Remarque

Veillez à ne pas ajouter de domaines qui ne sont pas sous votre contrôle, directement ou par le biais de caractères génériques. Par exemple, yourapp.onmicrosoft.com est valide, mais *.onmicrosoft.com n’est pas valide. Les domaines de niveau supérieur sont interdits, par exemple, *.com, *.org.

  1. Ouvrez le Portail des développeurs à partir du client Microsoft Teams, puis sélectionnez l’onglet Applications .

    créer une application dans le portail des développeurs

    Remarque

    Si vous ne l’avez pas ajoutée à votre client Teams, vous devez ajouter l’application Portail des développeurs.

    Ajouter une application portail des développeurs

  2. Chargez le manifeste de votre application.

    charger le manifeste de votre application

  3. Sélectionnez Extension de messagerie sous Fonctionnalités de l’application , puis sélectionnez Sélectionner un bot existant ou Créer un bot.

    Sélectionner l’option d’extension de messagerie

    sélectionner un bot existant ou créer un bot

  4. Sélectionnez Enregistrer.

  5. Sélectionnez Ajouter un domaine sous la section Liens en préversion , puis entrez domaine valide.

  6. Sélectionnez Ajouter. L’image suivante explique le processus :

    Capture d’écran de la section Gestionnaires de messages dans le Portail des développeurs.

Remarque

Si l’authentification est ajoutée via Azure AD, déploiez les liens dans Teams à l’aide du bot.

Tout d’abord, vous devez ajouter le messageHandlers tableau au manifeste de votre application et permettre à votre extension de message d’interagir avec les liens. L’exemple suivant explique comment ajouter manuellement un déploiement de lien :

...
{
  "composeExtensions": [
    {
      "botId": "abc123456-ab12-ab12-ab12-abcdef123456",
      "messageHandlers": [
        {
          "type": "link",
          "value": {
            "domains": [
              "*.trackeddomain.com"
            ]
          }
        }
      ]
    }
  ]
}
...

Pour obtenir un exemple complet de manifeste, consultez référence de manifeste.

Après avoir ajouté le domaine au manifeste de l’application, vous devez mettre à jour votre code de service web pour gérer la demande d’appel. Utilisez l’URL reçue pour rechercher votre service et créer une réponse de carte. Si vous répondez avec plusieurs cartes, seule la première réponse de carte est utilisée.

Les types de champs suivants sont pris en charge :

Pour plus d’informations, consultez Invocation du type d’action.

Voici un exemple de demande invoke :

      protected override async Task<MessagingExtensionResponse> OnTeamsAppBasedLinkQueryAsync(ITurnContext<IInvokeActivity> turnContext, AppBasedLinkQuery query, CancellationToken cancellationToken)
      {
          //You'll use the query.link value to search your service and create a card response
          var card = new HeroCard
             {
              Title = "Hero Card",
              Text = query.Url,
              Images = new List<CardImage> { new CardImage("https://raw.githubusercontent.com/microsoft/botframework-sdk/master/icon.png") },
          };

          var attachments = new MessagingExtensionAttachment(HeroCard.ContentType, null, card);
          var result = new MessagingExtensionResult(AttachmentLayoutTypes.List, "result", new[] { attachments }, null, "test unfurl");

          return new MessagingExtensionResponse(result);
      }

Le déploiement de lien d’installation zéro vous permet de déployer les aperçus de vos liens partagés avant même qu’un utilisateur ne découvre ou installe votre application dans Teams. Vous pouvez déployer anonymement des cartes avec une nouvelle demande d’appel ou créer une préversion de carte adaptative pré-authentifiée pour les utilisateurs avant d’installer ou d’authentifier votre application.

L’image suivante fournit un flux séquentiel permettant d’activer et d’utiliser le déploiement de lien d’installation nulle :

Capture d’écran du flux utilisateur du code de déploiement de lien.

Pour préparer votre application pour le déploiement du lien d’installation zéro, procédez comme suit :

  1. Définissez la propriété supportsAnonymizedPayloads sur true dans le schéma de manifeste.

  2. Définissez votre application pour gérer la nouvelle demande composeExtension/anonymousQueryLinkd’appel .

    Exemple de nouvelle demande d’appel :

    Capture d’écran de la déclaration « composeExtension/anonymousQueryLink » de la demande d’appel dans le manifeste.

    Exemple de charge utile d’appel de demande :

    {
       "name":"composeExtension/anonymousQueryLink",
       "type":"invoke",
       "timestamp":"2021-12-02T08:12:21.148Z",
       "localTimestamp":"2021-12-02T00:12:21.148-08:00",
       "id":"f:43d59e15-6114-bd53-08c3-b232aa648ec1",
       "channelId":"msteams",
       "serviceUrl":"https://smba.trafficmanager.net/amer/",
       "from":{
          "id":"redacted",
          "name":"redacted"
       },
       "conversation":{
          "isGroup":true,
          "conversationType":"groupChat",
          "tenantId":"redacted",
          "id":" redacted",
          "name":" redacted"
       },
       "recipient":{
          "id":"28:85fa138c-7654-4236-86eb-466160687029",
          "name":"test bot"
       },
       "entities":[
          {
             "locale":"en-US",
             "country":"US",
             "platform":"Mac",
             "timezone":"America/Los_Angeles",
             "type":"clientInfo"
          }
       ],
       "channelData":{
          "tenant":{
             "id":" redacted"
          },
          "source":{
             "name":"compose"
          }
       },
       "value":{
          "url":"https://test.test.com/test"
       },
       "locale":"en-US",
       "localTimezone":"America/Los_Angeles"
    }
    
  3. Répondre à la composeExtension/anonymousQueryLink charge utile.

    1. Pour les scénarios sans authentification : vous devez renvoyer une réponse avec le type sous result et une carte. Utilisez le modèle suivant :

      {
        "composeExtension": {
          "type": "result",
          "attachmentLayout": "list",
          "attachments": [
            {
              "contentType": "application/vnd.microsoft.teams.card.o365connector",
              "content": {
                "sections": [
                  {
                    "activityTitle": "[85069]: Create a cool app",
                    "activityImage": "https://placekitten.com/200/200"
                  },
                  {
                    "title": "Details",
                    "facts": [
                      {
                    "name": "Assigned to:",
                    "value": "[Larry Brown](mailto:larryb@example.com)"
                      },
                      {
                    "name": "State:",
                    "value": "Active"
                      }
                    ]
                  }
                 ]
               }
            }
          ]
        }
      }
      
    2. Pour les scénarios d’authentification : vous devez renvoyer une réponse avec le type sous auth avec une carte de pré-authentification facultative dans les pièces jointes. Utilisez le modèle suivant :

      {
         "composeExtension": {
            "type": "auth",
            "attachmentLayout": "list",
            "attachments": [
               {
                 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                 "type": "AdaptiveCard",
                 "version": "1.5",
                 "actions": [],
                 "body": [
                   {
                     "type": "TextBlock",
                     "size": "medium",
                     "weight": "bolder",
                     "text": "Zero-install test app"
                  },
                  {
                     "type": "TextBlock",
                     "text": "Link your account with this app for a full experience",
                     "wrap": true
                  }
                 ]
               }
            ]
         }
      }
      
  4. Carte de pré-authentification (pour l’authentification uniquement) : créez un aperçu de carte pour déployer vos liens pour les utilisateurs qui n’ont pas votre application installée. Vous pouvez créer une carte pré-modèle ou ajouter des champs d’espace réservé pertinents pour les utilisateurs à mettre à jour. Les utilisateurs peuvent en savoir plus sur l’application avant même de l’avoir installée.

    Vous pouvez créer une carte personnalisée et ajouter des champs pertinents. Les utilisateurs peuvent renseigner les informations requises en fonction des champs. L’image suivante illustre un aperçu de carte personnalisé :

    Capture d’écran de la carte personnalisée avec les champs que l’utilisateur doit mettre à jour.

    L’image suivante illustre une carte d’aperçu par défaut :

    Capture d’écran de la carte d’aperçu par défaut du code de déploiement de lien.

    Remarque

    Une fois le lien collé dans la zone de composition du message, Teams déploie le lien dans une carte et invite l’utilisateur à se connecter à l’application. Si l’utilisateur ne se connecte pas à l’application, le lien n’est pas publié sous forme de carte dans la conversation.

  5. Avantages et limitations :

    Le déploiement d’un lien d’installation zéro vous permet de fournir une expérience améliorée aux utilisateurs, par exemple :

    • Déployer les préversions de vos liens que les utilisateurs partagent dans Teams avant même d’avoir installé votre application.

    • Créez une carte de bienvenue pour votre application afin d’afficher un aperçu avec les champs d’espace réservé.

Lorsqu’un utilisateur partage un lien dans une réunion, l’application Teams déploie le lien vers une carte adaptative. Le résultat du déploiement de lien est mis en cache dans Teams pendant 30 minutes. Vous pouvez mettre à jour votre application pour définir une stratégie de cache et supprimer le cache de l’application, ce qui vous permet d’afficher un contenu différent dans une carte adaptative lorsque le lien de l’application est partagé dans un autre contexte dans Teams.

Pour supprimer le cache de déploiement de lien, mettez à jour votre bot avec le type sous setcachepolicy sous la suggestedActions propriété . Teams ne met pas en cache les résultats pour les liens d’application avec le "type": "setCachePolicy".

L’exemple de charge utile JSON suivant pour suggestedActions la propriété :

"suggestedActions": {
            "actions": [
                {
                    "type": "setCachePolicy",
                    "value": "{\"type\":\"no-cache\"}"
                }
            ]
        },

Guide pas à pas

Suivez le guide pas à pas pour déployer des liens dans Teams à l’aide d’un bot.

Voir aussi