Répondre à la commande de recherche

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de messagerie - V3 SDK dans le dossier Ressources de la documentation.

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

  • À mesure que des caractères sont entrés dans la zone de recherche.
  • initialRun est définie sur true dans le manifeste de votre application, vous recevez le message d’appel dès que la commande de recherche est invoquée. Pour plus d’informations, voir la 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 une requête par défaut.

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

Nom de la propriété Objectif
commandId Nom de la commande invoqué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 parameter contient le nom du paramètre, ainsi que la valeur de paramètre fournie par l’utilisateur.
queryOptions Paramètres de pagination :
skip: Ignorer le nombre pour cette requête
count: Nombre d’éléments à renvoyer.
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  //code to handle the query
}

Répondre aux demandes des utilisateurs

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

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 un objet JSON ou application valide avec 200 OK 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 une liste de résultats de recherche
auth: Demande à l’utilisateur de s’authentifier
config: Demande à l’utilisateur de configurer l’extension de messagerie
message: affiche un message en texte simple
composeExtension.attachmentLayout Spécifie la disposition des pièces jointes. Utilisé pour les réponses de type result .
Actuellement, les types suivants sont pris en charge :
list: Liste d’objets de carte contenant des champs de miniature, de titre et de texte
grid: grille d’images miniatures
composeExtension.attachments Tableau d’objets pièce jointe valides. Utilisé pour les réponses de type result .
Actuellement, 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 config ou .
composeExtension.text Message à afficher. Utilisé pour les réponses de type message .

Types et aperçus de cartes de réponse

Teams prend en charge les types de carte suivants :

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

Pour découvrir comment utiliser les types de carte miniature et hero, voir ajouter des cartes et des actions de carte.

Pour plus d’informations sur la carte connecteur Office 365, voir Utilisation Office 365 cartes de connecteur.

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

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

Pour la carte Hero ou miniature, sauf que 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 Ofiice 365, vous devez inclure un aperçu. La preview propriété doit être une carte Hero ou Miniature. Si vous ne spécifiez pas la propriété d’aperçu dans attachment l’objet, un aperçu n’est pas généré.

Pour les cartes Hero et Thumbnail, vous n’avez pas besoin de spécifier une propriété d’aperçu, un aperçu est généré par défaut. L’exemple suivant affiche la fonctionnalité de déploiement de lien lorsqu’un lien est passé dans l’extension de messagerie :
déploiement de lien

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
      }
  };
}

Activer et gérer les actions d’pression

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 }
        }
    });
}

Notes

OnTeamsMessagingExtensionSelectItemAsync n’est pas déclenché dans l’application mobile teams.

Requête par défaut

Si vous l’avez définie dans le manifeste, Microsoft Teams une requête par défaut lorsque l’utilisateur ouvre l’extension de messagerie pour la initialRun true première fois. Votre service peut répondre à cette requête avec un ensemble de résultats pré-rempli. Cela est utile lorsque votre commande de recherche nécessite une authentification ou une configuration, en affichant les éléments récemment affichés, les 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 normale, avec le champ définie sur et définie sur comme indiqué name initialRun dans value true 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
Teams d’extension de messagerie Décrit comment définir des commandes d’action, créer un module de tâche et répondre à une action d’soumission de module de tâche. View View
Teams d’extension de messagerie Décrit comment définir des commandes de recherche et répondre aux recherches. View View

Étape suivante

Voir aussi

Ajouter une configuration à une extension de messagerie