Répondre à la commande de recherche

Article
06/26/2024

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.

Une fois que l’utilisateur a envoyé la commande de recherche, votre service web reçoit un message d’appel composeExtension/query qui contient un value objet avec les paramètres de recherche. L’appel est déclenché avec les conditions suivantes :

Au fur et à mesure que les caractères sont entrés dans la zone de recherche.
initialRun est défini sur true dans le manifeste de votre application et vous recevez le message d’appel dès que la commande de recherche est appelée. Pour plus d’informations, consultez requête par défaut.

Ce document vous guide sur la façon de répondre aux demandes des utilisateurs sous forme de cartes et d’aperçus, ainsi que sur les conditions dans lesquelles Microsoft Teams émet une requête par défaut.

Les paramètres de la requête se trouvent dans l’objet value de la requête, qui inclut les propriétés suivantes :

Nom de la propriété	Objectif
`commandId`	Nom de la commande appelée par l’utilisateur, correspondant à l’une des commandes déclarées dans le manifeste de l’application.
`parameters`	Tableau de paramètres. Chaque objet de paramètre contient le nom du paramètre, ainsi que la valeur de paramètre fournie par l’utilisateur.
`queryOptions`	Paramètres de pagination : `skip`: Nombre d’ignorer pour cette requête `count`: nombre d’éléments à retourner.

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  // Code to handle the query.
}

Exemple de référence de code

class TeamsMessagingExtensionsSearch extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
  // Code to handle the query.
    }
}

Le code JSON suivant est raccourci pour mettre en évidence les sections les plus pertinentes.

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "searchKeywords",
        "value": "Toronto"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
...
}

Répondre aux demandes des utilisateurs

Lorsque l’utilisateur effectue une requête, Microsoft Teams envoie une requête HTTP synchrone à votre service. À ce stade, votre code dispose 5 de secondes pour fournir une réponse HTTP à la requête. Pendant ce temps, votre service peut effectuer d’autres recherches ou toute autre logique métier nécessaire pour traiter la requête.

Votre service doit répondre avec les résultats correspondant à la requête de l’utilisateur. La réponse doit indiquer un code d’état HTTP et 200 OK une application ou un objet JSON valide avec les propriétés suivantes :

Nom de la propriété	Objectif
`composeExtension`	Enveloppe de réponse de niveau supérieur.
`composeExtension.type`	Type de réponse. Les types suivants sont pris en charge : `result`: affiche la liste des résultats de la recherche `auth`: invite l’utilisateur à s’authentifier `config`: invite l’utilisateur à configurer l’extension de message `message`: affiche un message en texte brut
`composeExtension.attachmentLayout`	Spécifie la disposition des pièces jointes. Utilisé pour les réponses de type `result`. Les types suivants sont pris en charge : `list`: liste d’objets de carte contenant des champs miniature, titre et texte `grid`: grille d’images miniatures
`composeExtension.attachments`	Tableau d’objets de pièce jointe valides. Utilisé pour les réponses de type `result`. Les types suivants sont pris en charge : `application/vnd.microsoft.card.thumbnail` `application/vnd.microsoft.card.hero` `application/vnd.microsoft.teams.card.o365connector` `application/vnd.microsoft.card.adaptive`
`composeExtension.suggestedActions`	Actions suggérées. Utilisé pour les réponses de type `auth` ou `config`.
`composeExtension.text`	Message à afficher. Utilisé pour les réponses de type `message`.

Réponse de configuration

La réponse de configuration est les données retournées par le serveur ou l’application pour configurer et activer l’extension de message dans la plateforme de messagerie. Le code suivant est un exemple de configuration d’extension de message :

{
    "name": "composeExtension/submitAction",
    "type": "invoke",
    "timestamp": "2024-03-08T14:10:47.575Z",
    "localTimestamp": "2024-03-08T19:40:47.575+05:30",
    "id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
        "name": "MOD Administrator",
        "aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
        "id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
        "name": "PSDAzureBot"
    },
    "entities": [
        {
            "locale": "en-GB",
            "country": "GB",
            "platform": "Web",
            "timezone": "Asia/Calcutta",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
        },
        "source": {
            "name": "compose"
        }
    },
    "value": {
        "commandId": "razorView",
        "commandContext": "compose",
        "data": {
            "Title": "Welcome to RazorView!",
            "DisplayData": " Today&#x27;s date is 8-3-2024, Friday"
        },
        "context": {
            "theme": "default"
        }
    },
    "locale": "en-GB",
    "localTimezone": "Asia/Calcutta"
}

La réponse suivante est la réponse de configuration qui s’affiche lorsque l’utilisateur interagit avec l’extension compose :

{
    "composeExtension": {
        "type": "config",
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
                }
            ]
        }
    }
}

La capture d’écran montre la réponse de configuration pour l’extension de message.

Types de cartes de réponse et aperçus

Remarque

Les résultats de recherche de l’extension de message ne prennent pas en charge le remplissage.

Teams prend en charge les types de cartes suivants :

Pour avoir une meilleure compréhension et une vue d’ensemble des cartes, consultez ce que sont les cartes.

Pour savoir comment utiliser les types de cartes miniature et héros, consultez Ajouter des cartes et des actions de carte.

Pour plus d’informations sur la carte de connecteur pour les groupes Microsoft 365, consultez Utilisation de cartes de connecteur pour les groupes Microsoft 365.

La liste des résultats s’affiche dans l’interface utilisateur de Microsoft Teams avec un aperçu de chaque élément. La préversion est générée de l’une des deux manières suivantes :

Utilisation de la preview propriété dans l’objet attachment . La preview pièce jointe ne peut être qu’une carte Hero ou Miniature.
Extraction des propriétés de base title, textet image de l’objet attachment . Les propriétés de base sont utilisées uniquement si la preview propriété n’est pas spécifiée.

Pour la carte Héros ou Miniature, à l’exception de l’action d’appel, d’autres actions telles que le bouton et l’appui ne sont pas prises en charge dans la carte d’aperçu.

Pour envoyer une carte adaptative ou une carte de connecteur pour les groupes Microsoft 365, vous devez inclure une préversion. La preview propriété doit être une carte Hero ou Thumbnail. Si vous ne spécifiez pas la propriété preview dans l’objet attachment , un aperçu n’est pas généré.

Pour les cartes Héros et Miniatures, vous n’avez pas besoin de spécifier une propriété d’aperçu, une préversion est générée par défaut.

Exemple de réponse

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  // Searches NuGet for a package.
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

Exemple de référence de code

class TeamsMessagingExtensionsSearchBot extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;
        const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);

        const attachments = [];
        response.data.objects.forEach(obj => {
            const heroCard = CardFactory.heroCard(obj.package.name);
            const preview = CardFactory.heroCard(obj.package.name);
            const attachment = { ...heroCard, preview };
            attachments.push(attachment);
        });

        return {
            composeExtension: {
                type: 'result',
                attachmentLayout: 'list',
                attachments: attachments
            }
        };
    }
}

{
  "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"
                }
              ]
            }
          ]
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        }
      },
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "type": "AdaptiveCard",
          "body": [
            {
              "type": "Container",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Microsoft Corp (NASDAQ: MSFT)",
                  "size": "medium",
                  "isSubtle": true
                },
                {
                  "type": "TextBlock",
                  "text": "September 19, 4:00 PM EST",
                  "isSubtle": true
                }
              ]
            },
            {
              "type": "Container",
              "spacing": "none",
              "items": [
                {
                  "type": "ColumnSet",
                  "columns": [
                    {
                      "type": "Column",
                      "width": "stretch",
                      "items": [
                        {
                          "type": "TextBlock",
                          "text": "75.30",
                          "size": "extraLarge"
                        },
                        {
                          "type": "TextBlock",
                          "text": "▼ 0.20 (0.32%)",
                          "size": "small",
                          "color": "attention",
                          "spacing": "none"
                        }
                      ]
                    },
                    {
                      "type": "Column",
                      "width": "auto",
                      "items": [
                        {
                          "type": "FactSet",
                          "facts": [
                            {
                              "title": "Open",
                              "value": "62.24"
                            },
                            {
                              "title": "High",
                              "value": "62.98"
                            },
                            {
                              "title": "Low",
                              "value": "62.20"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ],
          "version": "1.0"
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "Microsoft Corp (NASDAQ: MSFT)",
            "text": "75.30 ▼ 0.20 (0.32%)"
          }
        }
      }
    ]
  }
}

Activer et gérer les actions d’appui

Exemple de référence de code

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
    // The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event.
    var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();

    var card = new ThumbnailCard
    {
        Title = "Card Select Item",
        Subtitle = description
    };

    var attachment = new MessagingExtensionAttachment
    {
        ContentType = ThumbnailCard.ContentType,
        Content = card,
    };

    return Task.FromResult(new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            Type = "result",
            AttachmentLayout = "list",
            Attachments = new List<MessagingExtensionAttachment> { attachment }
        }
    });
}

Exemple de référence de code

async handleTeamsMessagingExtensionSelectItem(context, obj) {
        return {
            composeExtension: {
                  type: 'result',
                  attachmentLayout: 'list',
                  attachments: [CardFactory.thumbnailCard(obj.Item3)]
            }
        };
    }

{
    "name": "composeExtension/selectItem",
    "type": "invoke",
    "value": {
        "Item1": "Package_Name",
        "Item2": "Version",
        "Item3": "Package Description"
    },
    .
    .
    .
}

Requête par défaut

Si vous définissez initialRuntrue sur dans le manifeste, Microsoft Teams émet une requête par défaut lorsque l’utilisateur ouvre l’extension de message pour la première fois. Votre service peut répondre à cette requête avec un ensemble de résultats préremplies. Cela est utile lorsque votre commande de recherche nécessite une authentification ou une configuration, l’affichage des éléments récemment consultés, des favoris ou toute autre information qui ne dépend pas de l’entrée utilisateur.

La requête par défaut a la même structure que n’importe quelle requête utilisateur standard, avec le name champ défini initialRun sur et value défini sur true comme indiqué dans l’objet suivant :

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Exemple de code

Exemple de nom	Description	.NET	Node.js	Manifeste
Recherche d'extension des messages Teams	Cet exemple montre comment créer une extension de message basée sur la recherche. Il recherche les packages d’incitation et affiche les résultats dans l’extension de messagerie basée sur la recherche.	View	View	View
Authentification et configuration de l’extension de message Teams	Cet exemple montre une extension de message qui a une page de configuration, accepte les demandes de recherche et retourne des résultats une fois que l’utilisateur s’est connecté. Il présente également le déploiement de lien d’installation d’application nulle avec le déploiement de lien normal	View	View	View

Étape suivante

Ajouter l’authentification tierce à l’extension de message

Partager via