Générer une extension de message basée sur l’API
Remarque
- Les extensions de message basées sur l’API prennent uniquement en charge les commandes de recherche.
- Les extensions de message basées sur l’API sont disponibles uniquement dans la préversion publique pour les développeurs.
Les extensions de message créées à l’aide de l’API (basées sur l’API) améliorent considérablement les fonctionnalités de vos applications Teams en leur permettant d’interagir avec des services externes. Les extensions de message basées sur l’API peuvent aider à rationaliser les flux de travail en réduisant le besoin de basculer entre différentes applications.
Vous pouvez utiliser des extensions de message basées sur l’API pour intégrer des services externes couramment utilisés dans le flux de travail métier. Par exemple, une entreprise qui utilise fréquemment un système CRM pour la gestion des clients peut utiliser une extension de messagerie pour extraire et afficher les données client directement à partir de Teams, ce qui permet de gagner du temps et d’améliorer l’efficacité en réduisant le besoin de basculer entre différentes applications. Cette fonctionnalité est prise en charge sur toutes les plateformes où Teams est disponible, y compris les ordinateurs de bureau, le web et les appareils mobiles.
Conditions préalables
Voici une liste des outils dont vous avez besoin pour créer et déployer vos applications.
| Installer | Pour l’utilisation... |
|---|---|
| Microsoft Teams | Microsoft Teams pour collaborer avec toutes les personnes avec lesquelles vous travaillez via des applications pour la conversation, les réunions ou les appels, le tout au même endroit. |
| Microsoft Edge (recommandé) ou Google Chrome | Un navigateur avec des outils de développement. |
| Visual Studio Code | Environnements de build JavaScript, TypeScript ou SharePoint Framework (SPFx). Utilisez la version 1.55 ou ultérieure. |
| Compte de développeur Microsoft 365 | Accès au compte Teams avec les autorisations appropriées pour installer une application. |
| Compte Azure | Accès aux ressources Azure. |
| Document De description OpenAPI (OAD) | Document qui décrit les fonctionnalités de votre API. Pour plus d’informations, consultez Description OpenAPI. |
Configurer votre locataire de développement Teams
Un locataire est comme un espace ou un conteneur pour votre organisation dans Teams, où vous discutez, partagez des fichiers et exécutez des réunions. Cet espace est également l’endroit où vous chargez et testez votre application personnalisée. Vérifions si vous êtes prêt à développer avec le locataire.
Rechercher l’option de chargement d’application personnalisée
Après avoir créé l’application, vous devez charger votre application dans Teams sans la distribuer. Ce processus est appelé chargement d’application personnalisée. Connectez-vous à votre compte Microsoft 365 pour afficher cette option.
Remarque
Le chargement d’applications personnalisées est nécessaire pour afficher un aperçu et tester les applications dans l’environnement local Teams. S’il n’est pas activé, vous ne pouvez pas afficher un aperçu et tester votre application dans l’environnement local Teams.
Avez-vous déjà un locataire et disposez-vous de l’accès administrateur ? Vérifions si vous le faites vraiment !
Vérifiez si vous pouvez charger une application personnalisée dans Teams :
Dans le client Teams, sélectionnez l’icône Applications .
Sélectionnez Gérer vos applications.
Sélectionnez Charger une application.
Recherchez l’option Charger une application personnalisée. Si vous voyez l’option , le chargement d’applications personnalisées est activé.
Remarque
Si vous ne trouvez pas l’option de charger une application personnalisée, contactez votre administrateur Teams.
Créer un locataire développeur Teams gratuit (facultatif)
Si vous n’avez pas de compte de développeur Teams, vous pouvez l’obtenir gratuitement. Rejoignez le programme des développeurs Microsoft 365 !
Sélectionnez Rejoindre maintenant et suivez les instructions à l’écran.
Dans l’écran d’accueil, sélectionnez Configurer l’abonnement E5.
Configurez votre compte d’administrateur. Une fois que vous avez terminé, l’écran suivant s’affiche.
Connectez-vous à Teams à l’aide du compte d’administrateur que vous venez de configurer. Vérifiez que vous disposez de l’option Charger une application personnalisée dans Teams.
Obtenir un compte Azure gratuit
Si vous souhaitez héberger votre application ou accéder à des ressources dans Azure, vous devez disposer d’un abonnement Azure. Créez un compte gratuit avant de commencer.
Vous disposez de tous les outils pour configurer votre compte. Ensuite, nous allons configurer votre environnement de développement et commencer à créer ! Sélectionnez d’abord l’application que vous souhaitez générer.
Créer un document de description OpenAPI
OpenAPI Description
La description OpenAPI (OAD) est la spécification standard qui décrit la façon dont les fichiers OpenAPI sont structurés et décrits. Il s’agit d’un format indépendant du langage et lisible par l’homme pour décrire les API. Il est facile pour les humains et les machines de lire et d’écrire. Le schéma est lisible par l’ordinateur et représenté en YAML ou JSON.
Pour interagir avec les API, un document De description OpenAPI est nécessaire. Le document De description OpenAPI doit répondre aux critères suivants :
- La
authpropriété ne doit pas être spécifiée. - JSON et YAML sont les formats pris en charge.
- Les versions 2.0 et 3.0.x d’OpenAPI sont prises en charge.
- Teams ne prend pas en charge les constructions oneOf, anyOf, allOf et pas (swagger.io).
- La construction de tableaux pour la requête n’est pas prise en charge, mais les objets imbriqués dans un corps de requête JSON sont pris en charge.
- Le corps de la demande, le cas échéant, doit être une application/Json pour garantir la compatibilité avec un large éventail d’API.
- Définissez une URL de serveur de protocole HTTPS pour la
servers.urlpropriété . - Seule la recherche par paramètre unique est prise en charge.
- Un seul paramètre obligatoire sans valeur par défaut est autorisé.
- Seules les méthodes POST et GET HTTP sont prises en charge.
- Le document De description OpenAPI doit avoir un
operationId. - L’opération ne doit pas avoir de paramètres d’en-tête ou de cookie requis sans valeurs par défaut.
- Une commande doit avoir exactement un paramètre.
- Vérifiez qu’il n’existe aucune référence distante dans le document Description OpenAPI.
- Un paramètre obligatoire avec une valeur par défaut est considéré comme facultatif.
Nous avons utilisé la description OpenAPI suivante comme exemple pour ce tutoriel :
OpenAPI Description
openapi: 3.0.1
info:
title: OpenTools Plugin
description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
/tools:
get:
operationId: searchTools
summary: Search for AI Tools
parameters:
- in: query
name: search
required: true
schema:
type: string
description: Used to search for AI tools by their category based on the keywords. For example, "tool to create music" will give tools that can create music.
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/searchToolsResponse'
"400":
description: Search Error
content:
application/json:
schema:
$ref: '#/components/schemas/searchToolsError'
components:
schemas:
searchToolsResponse:
required:
- search
type: object
properties:
tools:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tool.
opentools_url:
type: string
description: The URL to access the tool.
main_summary:
type: string
description: A summary of what the tool is.
pricing_summary:
type: string
description: A summary of the pricing of the tool.
categories:
type: array
items:
type: string
description: The categories assigned to the tool.
platforms:
type: array
items:
type: string
description: The platforms that this tool is available on.
description: The list of AI tools.
searchToolsError:
type: object
properties:
message:
type: string
description: Message of the error.
Remarque
Vérifiez que la required: true propriété n’est disponible que pour un seul paramètre. S’il existe plusieurs paramètres requis, vous pouvez mettre à jour la propriété requise sur required: false pour les autres paramètres.
Vous pouvez vérifier si le document De description OpenAPI est valide. Pour le vérifier, procédez comme suit :
Accédez au validateur Swagger/OpenAPI et validez le document Description OpenAPI.
Enregistrez le document De description OpenAPI.
Accédez à l’éditeur Swagger.
Dans le volet gauche, collez la description OpenAPI dans l’éditeur.
Dans le volet droit, sélectionnez GET.
Sélectionnez Essayer.
Entrez les valeurs du paramètre de recherche en tant qu’outil pour créer de la musique.
Sélectionnez Exécuter. L’éditeur swagger affiche une réponse avec une liste de produits.
Accédez àCorps de la réponse du serveur>.
Sous
products, copiez le premier produit de la liste et enregistrez-le pour référence ultérieure.
Créer un modèle de rendu de réponse
Un document De description OpenAPI nécessite un modèle de rendu de réponse pour que l’application réponde aux requêtes GET ou POST. Le modèle de rendu de réponse se compose d’un modèle de carte adaptative, d’un modèle de carte d’aperçu et de métadonnées.
Modèle de carte adaptative
Pour créer un modèle de carte adaptative, procédez comme suit :
Accédez à ChatGPT et posez la requête suivante dans la zone de composition des messages :
Create an Adaptive Card Template that binds to the following response: "categories": [ "Music Generation", "AI Detection" ], "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator", "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.", "name": "AI Music Generator", "opentools_url": "https://goto.opentools.ai/ai-music-generator", "platforms": [ "Web", "App", "API" ]Sélectionnez Envoyer un message.
ChatGPT génère une réponse avec un modèle de carte adaptative qui lie les exemples de données. Enregistrez le modèle de carte adaptative pour référence ultérieure.
Voici un exemple de modèle de carte adaptative :
Modèle de carte adaptative
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.4", "body": [ { "type": "TextBlock", "text": "AI Music Generator", "weight": "Bolder", "size": "Large" }, { "type": "TextBlock", "text": "Categories", "size": "Medium" }, { "type": "TextBlock", "text": "Music Generation, AI Detection", "wrap": true }, { "type": "TextBlock", "text": "Description", "size": "Medium" }, { "type": "TextBlock", "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. Powered by advanced AI technology, AI Music Generator makes music production accessible to everyone.", "wrap": true }, { "type": "TextBlock", "text": "Platform", "size": "Medium" }, { "type": "TextBlock", "text": "Web, App, API", "wrap": true } ], "actions": [ { "type": "Action.OpenUrl", "title": "Learn More", "url": "https://goto.opentools.ai/ai-music-generator" }, { "type": "Action.OpenUrl", "title": "Try It", "url": "https://goto.opentools.ai/c/ai-music-generator" } ] }Pour vérifier si la carte adaptative générée est liée aux exemples de données, procédez comme suit :
Accédez au Concepteur de cartes adaptatives.
Accédez à Sélectionner l’application hôte et, dans la liste déroulante, sélectionnez Microsoft Teams.
Accédez à CARD PAYLOAD EDITOR et collez le code du modèle de carte adaptative.
Accédez à SAMPLE DATA EDITOR et collez la réponse de l’API GET que vous avez enregistrée précédemment.
Sélectionnez Mode d’aperçu. Le concepteur de cartes adaptatives affiche une carte adaptative avec les données qui lient la réponse au modèle.
Créer un modèle de carte d’aperçu
Le modèle de carte d’aperçu peut contenir des titlepropriétés , subtitle et image . Si la réponse de l’API n’a pas d’image, vous pouvez supprimer la propriété image.
Voici un exemple de modèle de carte d’aperçu :
Modèle de carte d’aperçu
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}",
}
Créez une condition if pour et titlesubtitle où, si le nom existe, le bot utilise le nom ; sinon, il utilise NA. Par exemple : "title": "Name: ${if(name, name, 'N/A')}". Enregistrez le modèle de carte d’aperçu pour référence ultérieure.
Modèle de rendu de réponse
Le modèle de rendu de réponse doit être conforme au schéma hébergé sur https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.json.
Pour créer un modèle de rendu de réponse, procédez comme suit :
Créez un fichier JSON et ajoutez le code suivant au fichier :
{ "version": "1.0.0", "$schema": "<URL_REFERENCE_TO_SCHEMA>", "jsonPath": "", "responseLayout": "", "responseCardTemplate": { }, "previewCardTemplate": { } }Mettez à jour les propriétés dans le modèle de rendu de réponse comme suit :
"version":"1.0.0""$schema":"http://adaptivecards.io/schemas/adaptive-card.json""jsonPath":"tools"jsonPathest le chemin d’accès à un ou plusieurs résultats dans la réponse JSON de réponse. Ajoutez aujsonPathtableau/données appropriés à partir de la liste des produits dans la réponse de l’API. Dans ce cas, le est desjsonPathoutils. Pour plus d’informations sur la façon de déterminer le chemin JSON, consultez Interrogation de JSON avec le chemin d’accès JSON."responseLayout":"list"responseLayoutspécifie la disposition des pièces jointes. Utilisé pour les réponses du résultat de type. Les types pris en charge sont list et grid. Si le corps de la réponse contient un objet avec plusieurs éléments tels que le texte, le titre et l’image, la disposition de la réponse doit être définie surlist. Si la réponse de l’API contient uniquement des images ou des miniatures, la disposition de la réponse doit être définie surgrid."responseCardTemplate": collez le code du modèle de carte adaptative que vous avez enregistré précédemment.responseCardTemplateest un modèle de carte adaptative pour mapper la réponse JSON à une carte adaptative."previewCardTemplate": collez le code du modèle de carte d’aperçu que vous avez enregistré précédemment.previewCardTemplateest un modèle de carte d’aperçu utilisé pour afficher un aperçu des résultats dans le menu volant d’extension de message.
Enregistrez le modèle de rendu de réponse dans le même dossier que celui où vous avez enregistré le document De description OpenAPI.
Le code suivant est un exemple de modèle de rendu de réponse :
Modèle de rendu de réponse
{
"version": "devPreview",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "AI Music Generator",
"weight": "Bolder",
"size": "Large"
},
{
"type": "TextBlock",
"text": "Categories",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Music Generation, AI Detection",
"wrap": true
},
{
"type": "TextBlock",
"text": "Description",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
"wrap": true
},
{
"type": "TextBlock",
"text": "Platform",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Web, App, API",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "https://goto.opentools.ai/ai-music-generator"
},
{
"type": "Action.OpenUrl",
"title": "Try It",
"url": "https://goto.opentools.ai/c/ai-music-generator"
}
]
},
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}",
}
}
Créer un manifeste d’application
Maintenant, vous devez créer un manifeste d’application (précédemment appelé manifeste d’application Teams). Le manifeste de l’application décrit comment votre application s’intègre au produit Microsoft Teams.
Créer un manifeste d’application Teams
Pour créer le manifeste, procédez comme suit :
Créez un fichier JSON. Votre manifeste d’application doit être conforme au schéma défini dans le schéma du manifeste d’application développeur public en préversion.
Ajoutez le code suivant au fichier JSON :
Manifeste de l’application
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", "manifestVersion": "devPreview", "version": "1.0.3", "id": "<<YOUR-MICROSOFT-APP-ID>>", "packageName": "com.microsoft.teams.extension", "developer": { "name": "Teams App, Inc.", "websiteUrl": "https://www.example.com", "privacyUrl": "https://www.example.com/termofuse", "termsOfUseUrl": "https://www.example.com/privacy" }, "icons": { "color": "color.png", "outline": "outline.png" }, "name": { "short": "Search ME API", "full": "Search ME API full" }, "description": { "short": "product app for testing API MEs", "full": "product app for testing API MEs" }, "accentColor": "#FFFFFF", "composeExtensions": [ { "composeExtensionType": "", "apiSpecificationFile": "", "commands": [ { "context": [ "compose" ], "type": "query", "title": "API for fetching Klarna.", "id": "", "parameters": [ { "name": "", "title": "", "description": "" } ], "description": "", "apiResponseRenderingTemplateFile": "" } ] } ], "permissions": [ "identity", "messageTeamMembers" ], "validDomains": [] }Mettez à jour les propriétés du manifeste de l’application comme suit :
- Remplacez par
<<YOUR-MICROSOFT-APP-ID>>l’ID d’application Microsoft du bot. - Mettez à jour la valeur de sur
composeExtensionTypeapiBased. - Mettez à jour la valeur de avec
apiSpecificationFilele chemin d’accès de votre fichier de description OpenAPI. - Mettez à jour la valeur de sur
commands.idsearchTools. - Mettez à jour la valeur de sur
commands.titleSearch for AI Tools. - Mettez à jour la valeur de sur
commands.descriptionSearch for AI Tools. - Mettez à jour la valeur de sur
parameters.namesearch. S’il n’existe aucun paramètre, les valeurs doivent être des paramètres de requête ouproperties.namesi une propriété est référencée dans le schéma du corps de la requête. - Mettez à jour vers
apiResponseRenderingTemplateFilele chemin d’accès de votre fichier de modèle de rendu de réponse. - Mettez à jour la valeur de sur
validDomainsleservice URLpoint de terminaison défini dans le fichier de description OpenAPI.
- Remplacez par
Enregistrez le manifeste de l’application Teams dans le même dossier que celui où vous avez enregistré le document Description OpenAPI et le modèle de rendu de réponse.
- Vous avez besoin d’une image couleur et d’une image hiérarchique. Ces images doivent être incluses dans le dossier et référencées dans le manifeste de votre application Teams.
- Compressez le contenu du dossier. Le fichier zip doit inclure les fichiers suivants :
- Document de description OpenAPI
- Modèle de rendu de réponse
- Manifeste d'application
- Icône de couleur
- Icône de contour
Charger une application personnalisée dans Teams
Connectez-vous à l’environnement de test Teams pour tester votre application dans Teams. Pour charger une application personnalisée dans Teams, procédez comme suit :
Accédez à Microsoft Teams et connectez-vous à l’aide de vos informations d’identification de locataire de test.
Accédez à Applications>Gérer votre application>Charger une application.
Sélectionnez Charger une application personnalisée.
Sélectionnez le fichier zip créé, puis sélectionnez Ouvrir.
Sélectionnez Ajouter. L’application est ajoutée à Teams.
Accédez à une conversation et, dans la zone de rédaction des messages, sélectionnez + et recherchez votre application.
Sélectionnez l’application et effectuez une requête de recherche.
L’application répond avec une carte adaptative dans la fenêtre de conversation.
Sélectionnez Envoyer.
Félicitations !
Tu l’as fait ! Vous avez appris à créer une extension de message basée sur l’API à l’aide du document De description OpenAPI.
Vous avez un défi avec cette section ? Si c'est le cas, faites-nous part de vos commentaires pour que nous puissions l'améliorer.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour