Répondre à la commande de recherche

  • Article

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

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 une recherche supplémentaire 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 status HTTP de 200 OK et 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.
Actuellement, les types suivants sont pris en charge :
list: liste d’objets 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.
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 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 carte de réponse et aperçus

Teams prend en charge les types de carte 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 miniatures et de carte héros, consultez Ajouter des cartes et carte actions.

Pour plus d’informations sur le connecteur carte pour Groupes Microsoft 365, consultez Utilisation de cartes de connecteur pour 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’un héros ou une miniature carte.
  • 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 les carte Héros ou Miniatures, à 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 préversion carte.

Pour envoyer une carte adaptative ou un carte de connecteur pour Groupes Microsoft 365, vous devez inclure une préversion. La preview propriété doit être un 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
      }
  };
}

Activer et gérer les actions d’appui

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

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 générer une extension de message basée sur 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

Voir aussi