Tutoriel avancé pour créer une extension de message basée sur l’API

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 message pour extraire et afficher les données client directement à partir de Teams. Cette application 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.

Configuration requise

• 16 minutes restantes

Voici une liste des outils dont vous avez besoin pour créer et déployer vos applications.

Configurer votre locataire de développement Teams

Un locataire est comme un espace ou un conteneur pour votre organization 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.

Avez-vous déjà un locataire et disposez-vous de l’accès administrateur ? Nous allons case activée si vous le faites vraiment !

Vérifiez si vous pouvez charger une application personnalisée dans Teams :

1. Dans le client Teams, sélectionnez l’icône Applications .

2. Sélectionnez Gérer vos applications.

3. Sélectionnez Charger une application.

4. 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 !

1. Accédez auProgramme pour les développeurs Microsoft 365.

2. Sélectionnez Rejoindre maintenant et suivez les instructions à l’écran.

3. Dans l’écran d’accueil, sélectionnez Configurer l’abonnement E5.

4. Configurez votre compte d’administrateur. Une fois que vous avez terminé, l’écran suivant s’affiche.

   

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

• 15 minutes restantes

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 auth proprié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.url proprié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 nécessiter de paramètres Header ou Cookie 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: 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, a search for "tool to create music" provides a list of 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.
      

Vous pouvez vérifier si le document De description OpenAPI est valide. Pour le vérifier, procédez comme suit :

1. Accédez au validateur Swagger/OpenAPI et validez le document Description OpenAPI.

2. Enregistrez le document De description OpenAPI.

3. Allez à swagger Rédacteur.

4. Dans le volet gauche, collez la description OpenAPI dans l’éditeur.

5. Dans le volet droit, sélectionnez GET.

6. Sélectionnez Essayer.

7. Entrez les valeurs du paramètre de recherche en tant qu’outil pour créer de la musique.

8. Sélectionnez Exécuter. L’éditeur swagger affiche une réponse avec une liste de produits.

   

9. Accédez àCorps de la réponse du serveur>.

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

• 10 minutes restantes

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 :

1. 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"
        ]
   

2. Sélectionnez Envoyer un message.

3. 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. AI Music Generator is powered by advanced AI technology, and it 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"
       }
   ]
   }
   
   

4. Pour vérifier si la carte adaptative générée est liée aux exemples de données, procédez comme suit :

   1. Accédez à La carte adaptative Designer.

   2. Accédez à Sélectionner l’application hôte, puis sélectionnez Microsoft Teams dans la liste déroulante.

   3. Accédez à CARD PAYLOAD EDITOR et collez le code du modèle de carte adaptative.

   4. Accédez à SAMPLE DATA EDITOR et collez la réponse de l’API GET que vous avez enregistrée précédemment.

      

   5. 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 en préversion

L’aperçu carte modèle peut contenir des titlepropriétés et subtitleimage . 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 en préversion :

   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}",
    } 

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 :

1. 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": {
        }
    }
   

2. Mettez à jour les propriétés dans le modèle de rendu de réponse comme suit :

   1. "version": "1.0.0"

   2. "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"

   3. "jsonPath": "tools"

      jsonPath est le chemin d’accès à un ou plusieurs résultats dans la réponse JSON de réponse. Ajoutez au jsonPath tableau/données appropriés à partir de la liste des produits dans la réponse de l’API. Dans ce cas, le est des jsonPath outils. 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.

   4. "responseLayout": "list"

      responseLayout spé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 sur list. Si la réponse de l’API contient uniquement des images ou des miniatures, la disposition de la réponse doit être définie sur grid.

   5. "responseCardTemplate": collez le code du modèle de carte adaptative que vous avez enregistré précédemment.

      responseCardTemplate est un modèle de carte adaptative pour mapper la réponse JSON à une carte adaptative.

   6. "previewCardTemplate": collez l’aperçu carte code de modèle que vous avez enregistré précédemment.

      previewCardTemplateest un aperçu carte modèle est utilisé pour afficher un aperçu des résultats dans le menu volant d’extension de message.

3. 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 :

{
        "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

• 5 minutes restantes

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 :

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

2. 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 Message Extensions",
        "full": "product app for testing API Message Extensions"
    },
    "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": []
   }
   

3. 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 apiSpecificationFile le 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 ou properties.name si une propriété est référencée dans le schéma du corps de la requête.
   • Mettez à jour vers apiResponseRenderingTemplateFile le chemin d’accès de votre fichier de modèle de rendu de réponse.
   • Mettez à jour la valeur de sur validDomains le service URL point de terminaison défini dans le fichier de description OpenAPI.

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

• 2 minutes restantes

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 :

1. Accédez à Microsoft Teams et connectez-vous à l’aide de vos informations d’identification de locataire de test.

2. Accédez à Applications>Gérer votre application>Charger une application.

3. Sélectionnez Charger une application personnalisée.

4. Sélectionnez le fichier zip créé, puis sélectionnez Ouvrir.

5. Sélectionnez Ajouter. L’application est ajoutée à Teams.

   

6. Accédez à une conversation, puis sélectionnez + dans la zone de rédaction des messages, puis recherchez votre application.

7. Sélectionnez l’application et effectuez une requête de recherche.

   

8. L’application répond avec une carte adaptative dans la fenêtre de conversation.

9. Sélectionnez Envoyer.

   

Félicitations !

• Tout est terminé !

Vous avez réussi ! Vous avez appris à créer une extension de message basée sur l’API à l’aide du document De description OpenAPI.