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 une fonctionnalité d’application Microsoft Teams qui intègre des API externes directement dans Teams, ce qui améliore la facilité d’utilisation de votre application et offre une expérience utilisateur transparente. Les extensions de message basées sur l’API prennent en charge les commandes de recherche et peuvent être utilisées pour extraire et afficher des données à partir de services externes dans Teams, ce qui simplifie les flux de travail en réduisant le besoin de basculer entre les applications.
Avant de commencer, vérifiez que vous répondez aux exigences suivantes :
1. Description OpenAPI (OAD)
Vérifiez que vous respectez les instructions suivantes pour le document De description OpenAPI (OAD) :
- Les versions 2.0 et 3.0.x d’OpenAPI sont prises en charge.
- JSON et YAML sont les formats pris en charge.
- Le corps de la demande, s’il est présent, doit être application/Json.
- Définissez une URL de serveur de protocole HTTPS pour la
servers.urlpropriété . - Seules les méthodes POST et GET HTTP sont prises en charge.
- Le document De description OpenAPI doit avoir un
operationId. - Un seul paramètre obligatoire sans valeur par défaut est autorisé.
- Un paramètre obligatoire avec une valeur par défaut est considéré comme facultatif.
- Les utilisateurs ne doivent pas entrer de paramètre pour un en-tête ou un cookie.
- L’opération ne doit pas avoir d’en-tête ou de paramètres de cookie requis sans valeurs par défaut.
- Vérifiez qu’il n’existe aucune référence distante dans le document Description OpenAPI.
- La construction de tableaux pour la requête n’est pas prise en charge ; toutefois, les objets imbriqués dans un corps de requête JSON sont pris en charge.
- Teams ne prend pas en charge les
oneOfconstructions ,anyOfallOf, etnot(swagger.io).
Le code suivant est un exemple de document de description OpenAPI :
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, ?search="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.
Pour plus d’informations, consultez Structure OpenAPI.
2. Manifeste de l’application
Veillez à respecter les instructions suivantes pour le manifeste de l’application :
Définissez la version du manifeste de l’application sur
1.17.Définissez sur
composeExtensions.composeExtensionTypeapiBased.Définissez
composeExtensions.apiSpecificationFilecomme chemin d’accès relatif au fichier de description OpenAPI dans le dossier. Cela lie le manifeste de l’application à la spécification de l’API.Définissez
apiResponseRenderingTemplateFilecomme chemin d’accès relatif au modèle de rendu de réponse. Cela spécifie l’emplacement du modèle utilisé pour le rendu des réponses de l’API.Chaque commande doit avoir un lien vers le modèle de rendu de réponse. Cela connecte chaque commande à son format de réponse correspondant.
La
Commands.idpropriété dans le manifeste de l’application doit correspondre à dansoperationIdla description OpenAPI.Si un paramètre requis est sans valeur par défaut, la commande
parameters.namedans le manifeste de l’application doit correspondre à dansparameters.namele document Description OpenAPI.Si aucun paramètre n’est requis, la commande
parameters.namedans le manifeste de l’application doit correspondre au facultatifparameters.namedans la description OpenAPI.Assurez-vous que les paramètres de chaque commande correspondent exactement aux noms des paramètres définis pour l’opération dans la spécification OpenAPI.
Un modèle de rendu de réponse doit être défini par commande, qui est utilisée pour convertir des réponses à partir d’une API.
La description complète ne doit pas dépasser 128 caractères.
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", + "manifestVersion": "devPreview", "version": "1.0.0", "id": "04805b4b-xxxx-xxxx-xxxx-4dbc1cac8f89", "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": "AI tools", "full": "AI tools" }, "description": { "short": "AI tools", "full": "AI tools" }, "accentColor": "#FFFFFF", "composeExtensions": [ { + "composeExtensionType": "apiBased", + "authorization": { + "authType": "apiSecretServiceAuth ", + "apiSecretServiceAuthConfiguration": { + "apiSecretRegistrationId": "96270b0f-7298-40cc-b333-152f84321813" + } + }, + "apiSpecificationFile": "aitools-openapi.yml", "commands": [ { "id": "searchTools", "type": "query", "context": [ "compose", "commandBox" ], "title": "search for AI tools", "description": "search for AI tools", "parameters": [ { "name": "search", "title": "search query", "description": "e.g. search='tool to create music'" } ], + "apiResponseRenderingTemplateFile": "response-template.json" } ] } ], "validDomains": [] }
Paramètres
| Nom | Description |
|---|---|
composeExtensions.composeExtensionType |
Type d’extension compose. Mettez à jour la valeur sur apiBased. |
composeExtensions.authorization |
Informations relatives à l’autorisation pour l’extension de message basé sur l’API |
composeExtensions.authorization.authType |
Énumération des types d’autorisation possibles. Les valeurs prises en charge sont none, apiSecretServiceAuthet microsoftEntra. |
composeExtensions.authorization.apiSecretServiceAuthConfiguration |
Détails de capture d’objet nécessaires pour effectuer l’authentification de service. Applicable uniquement lorsque le type d’authentification est apiSecretServiceAuth. |
composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId |
ID d’inscription retourné lorsque le développeur envoie la clé API via le portail des développeurs. |
composeExtensions.apiSpecificationFile |
Fait référence à un fichier de description OpenAPI dans le package d’application. Incluez lorsque type est apiBased. |
composeExtensions.commands.id |
ID unique que vous affectez à la commande de recherche. La demande de l’utilisateur inclut cet ID. L’ID doit correspondre au OperationId disponible dans la description OpenAPI. |
composeExtensions.commands.context |
Tableau où les points d’entrée pour l’extension de message sont définis. Les valeurs par défaut sont compose et commandBox. |
composeExtensions.commands.parameters |
Définit une liste statique de paramètres pour la commande . Le nom doit être mappé au parameters.name dans la description OpenAPI. Si vous référencez une propriété dans le schéma du corps de la demande, le nom doit être mappé aux properties.name paramètres de requête ou . |
composeExtensions.commands.apiResponseRenderingTemplateFile |
Modèle utilisé pour mettre en forme la réponse JSON de l’API du développeur à la réponse de carte adaptative. [Obligatoire] |
Pour plus d’informations, consultez composeExtensions.
3. Modèle de rendu de réponse
Remarque
Teams prend en charge les cartes adaptatives jusqu’à la version 1.5 et les cartes adaptatives Designer prennent en charge jusqu’à la version 1.6.
- Définissez l’URL de référence de schéma dans la
$schemapropriété pour établir la structure de votre modèle. - Valeurs prises en charge pour
responseLayoutsontlistetgrid, qui déterminent la façon dont la réponse est visuellement présentée. - Un
jsonPathest recommandé pour les tableaux ou lorsque les données de la carte adaptative ne sont pas l’objet racine. Par exemple, si vos données sont imbriquées sousproductDetails, votre chemin JSON estproductDetails. - Définissez
jsonPathcomme chemin d’accès aux données ou au tableau appropriés dans la réponse de l’API. Si le chemin pointe vers un tableau, chaque entrée du tableau est liée au modèle de carte adaptative et retourne un résultat distinct. [Facultatif] - Obtenez un exemple de réponse pour valider le modèle de rendu de réponse. Cela sert de test pour vous assurer que votre modèle fonctionne comme prévu.
- Utilisez des outils tels que Fiddler ou Postman pour appeler l’API et vous assurer que la demande et la réponse sont valides. Cette étape est cruciale pour résoudre les problèmes et confirmer que votre API fonctionne correctement.
- Vous pouvez utiliser la carte adaptative Designer pour lier la réponse de l’API au modèle de rendu de réponse et afficher un aperçu de la carte adaptative. Insérez le modèle dans CARD PAYLOAD EDITOR et insérez l’exemple d’entrée de réponse dans l’ÉDITEUR SAMPLE DATA.
Le code suivant est un exemple de modèle de rendu de réponse :
Exemple de modèle de rendu de réponse
{
"version": "1.0",
"jsonPath": "repairs",
"responseLayout": "grid",
"responseCardTemplate": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "Container",
"items": [
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Title: ${if(title, title, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "Description: ${if(description, description, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
"wrap": true
},
{
"type": "Image",
"url": "${image}",
"size": "Medium",
"$when": "${image != null}"
}
]
},
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "${if(image, image, '')}",
"size": "Medium"
}
]
}
]
},
{
"type": "FactSet",
"facts": [
{
"title": "Repair ID:",
"value": "${if(id, id, 'N/A')}"
},
{
"title": "Date:",
"value": "${if(date, date, 'N/A')}"
}
]
}
]
}
]
},
"previewCardTemplate": {
"title": "Title: ${if(title, title, 'N/A')}",
"subtitle": "Description: ${if(description, description, 'N/A')}",
"text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
"image": {
"url": "${image}",
"$when": "${image != null}"
}
}
}
Carte d’aperçu
Carte adaptative développée
Paramètres
| Propriété | Type | Description | Obligatoire |
|---|---|---|---|
version |
string |
Version de schéma du modèle de rendu de réponse actuel. | Oui |
jsonPath |
string |
Chemin d’accès à la section appropriée dans les résultats auxquels responseCardTemplate et previewCardTemplate doivent être appliqués. S’il n’est pas défini, l’objet racine est traité comme la section appropriée. Si la section appropriée est un tableau, chaque entrée est mappée au responseCardTemplate et au previewCardTemplate. | Non |
responseLayout |
responseLayoutType |
Spécifie la disposition des résultats dans le menu volant d’extension de message. Les types pris en charge sont list et grid. |
Oui |
responseCardTemplate |
adaptiveCardTemplate |
Modèle permettant de créer une carte adaptative à partir d’une entrée de résultat. | Oui |
previewCardTemplate |
previewCardTemplate |
Modèle permettant de créer un aperçu carte à partir d’une entrée de résultat. L’aperçu obtenu carte s’affiche dans le menu volant de l’extension de message. | Oui |
Chemin d’accès Json
Le chemin JSON est facultatif, mais doit être utilisé pour les tableaux ou où l’objet à utiliser comme données pour le carte adaptatif n’est pas l’objet racine. Le chemin JSON doit suivre le format défini par Newtonsoft. Si le chemin JSON pointe vers un tableau, chaque entrée de ce tableau est liée avec le modèle de carte adaptatif et retourne des résultats distincts.
Exemple Supposons que vous disposez du code JSON ci-dessous pour une liste de produits et que vous souhaitez créer un résultat carte pour chaque entrée.
{
"version": "1.0",
"title": "All Products",
"warehouse": {
"products": [
...
]
}
}
Comme vous pouvez le voir, le tableau de résultats se trouve sous « products », qui est imbriqué sous « warehouse », de sorte que le chemin JSON serait « warehouse.products ».
Utilisez https://adaptivecards.io/designer/ pour afficher un aperçu de la carte adaptative en insérant le modèle dans l’Rédacteur de charge utile de la carte, puis prenez un exemple d’entrée de réponse à partir de votre tableau ou de votre objet et insérez-le dans l’éditeur de données identiques à droite. Assurez-vous que le carte s’affiche correctement et est à votre convenance. Notez que Teams prend en charge les cartes jusqu’à la version 1.5, tandis que le concepteur prend en charge la version 1.6.
Mappage de schéma
Les propriétés du document Description OpenAPI sont mappées au modèle de carte adaptative comme suit :
string,number,integer, lesbooleantypes sont convertis en TextBlock.Exemple
Schéma source :
string,number,integeretbooleanname: type: string example: doggieSchéma cible :
Textblock{ "type": "TextBlock", "text": "name: ${if(name, name, 'N/A')}", "wrap": true }
array: un tableau est converti en conteneur à l’intérieur de la carte adaptative.Exemple
Schéma source :
arraytype: array items: required: - name type: object properties: id: type: integer category: type: object properties: name: type: stringSchéma cible :
Container{ "type": "Container", "$data": "${$root}", "items": [ { "type": "TextBlock", "text": "id: ${if(id, id, 'N/A')}", "wrap": true }, { "type": "TextBlock", "text": "category.name: ${if(category.name, category.name, 'N/A')}", "wrap": true } ] }
object: un objet est converti en propriété imbriquée dans la carte adaptative.Exemple
Schéma source :
objectcomponents: schemas: Pet: category: type: object properties: id: type: integer name: type: stringSchéma cible : propriété imbriquée dans une carte adaptative
{ "type": "TextBlock", "text": "category.id: ${if(category.id, category.id, 'N/A')}", "wrap": true }, { "type": "TextBlock", "text": "category.name: ${if(category.name, category.name, 'N/A')}", "wrap": true }
image: si une propriété est une URL d’image, elle est convertie en élément Image dans la carte adaptative.Exemple
Schéma source :
imageimage: type: string format: uri description: The URL of the image of the item to be repairedSchéma cible :
"Image"{ "type": "Image", "url": "${image}", "$when": "${image != null}" }
Authentification
Vous pouvez implémenter l’authentification dans les extensions de message basées sur l’API pour fournir un accès sécurisé et transparent aux applications. Si votre extension de message nécessite une authentification, ajoutez la authorization propriété sous composeExtensions dans le manifeste de l’application et définissez le type d’authentification pour votre application en définissant la authType propriété sous authorization. Pour activer l’authentification pour votre extension de message, mettez à jour le manifeste de votre application avec l’une des méthodes d’authentification suivantes :
Aucun
Vous pouvez mettre à jour none en tant que valeur pour authorization dans une extension de message basée sur l’API lorsque l’extension de message ne nécessite aucune authentification pour que l’utilisateur accède à l’API.
"authorization": {
"authType": "none"
}
},
Authentification du service secret
L’authentification du service secret d’API est une méthode sécurisée permettant à votre application de s’authentifier auprès de l’API. Vous pouvez inscrire une clé API via le portail des développeurs pour Teams et générer un ID d’inscription de clé API. Mettez à jour le manifeste de l’application avec l’objet apiSecretServiceAuthConfiguration avec une apiSecretRegistrationId propriété . Cette propriété doit contenir l’ID de référence retourné lorsque vous avez envoyé la clé API via le portail.
Lorsqu’une demande d’API est lancée, le système récupère la clé API à partir d’un emplacement de stockage sécurisé et l’inclut dans l’en-tête d’autorisation à l’aide du schéma de jeton du porteur. Le point de terminaison d’API, à la réception de la demande, vérifie la validité de la clé API. Si la vérification réussit, le point de terminaison traite la demande et retourne la réponse souhaitée, garantissant que seules les demandes authentifiées reçoivent l’accès aux ressources de l’API.
Inscrire une clé API
L’inscription de clé API vous permet de sécuriser leurs API qui se trouvent derrière une authentification et de les utiliser dans les extensions de message. Vous pouvez inscrire une clé API et spécifier le domaine, le locataire et l’application qui peut accéder aux API, et fournir les secrets nécessaires à l’authentification des appels d’API. Vous pouvez ensuite coller l’ID de clé API dans l’extension de message simplifié et l’ID de clé API active l’authentification pour les appels d’API qui se trouvent derrière une authentification.
Pour inscrire une clé API, procédez comme suit :
Accédez à Outils>Inscription de clé API.
Sélectionnez + Nouvelle clé API.
Dans la page d’inscription de clé API , sous Inscrire une clé API, mettez à jour les éléments suivants :
Description : description de la clé API.
Ajouter un domaine : mettez à jour le chemin de base pour les points de terminaison d’API. Le chemin d’accès doit être une URL HTTPS sécurisée, inclure un nom de domaine complet et peut éventuellement inclure un chemin d’accès spécifique. Par exemple :
https://api.yelp.com.
Sous Définir un locataire cible, sélectionnez l’une des options suivantes :
- Accueil tenent
- N’importe quel locataire
Option Champs d’utilisation Description Locataire d’origine Lorsque vous développez votre application dans votre locataire et testez l’application en tant qu’application personnalisée ou application personnalisée conçue pour votre organisation. La clé API est utilisable uniquement dans le locataire où l’API est inscrite. N’importe quel locataire Une fois que vous avez terminé le test de l’application et que vous souhaitez activer l’application sur différents locataires. Veillez à mettre à jour votre locataire cible vers n’importe quel locataire avant de soumettre votre package d’application à l’Espace partenaires. La clé API peut être utilisée dans d’autres locataires une fois que l’application est disponible dans le Magasin Teams. 
Sous Définir une application Teams, sélectionnez l’une des options suivantes :
- N’importe quelle application Teams
- ID d’application Teams existant
Option Champs d’utilisation Description N’importe quelle application Teams Lorsque vous développez votre application dans votre locataire et testez l’application en tant qu’application personnalisée ou application personnalisée conçue pour votre organisation. La clé API peut être utilisée avec n’importe quelle application Teams. Il est utile lorsque les ID d’une application personnalisée ou d’une application personnalisée créée pour votre organisation sont générés après le chargement de l’application. ID d’application Teams existant Une fois que vous avez terminé le test de votre application au sein de votre locataire en tant qu’application personnalisée ou application personnalisée conçue pour votre organisation. Mettez à jour votre inscription de clé API, sélectionnez Application Teams existante et entrez l’ID de manifeste de votre application. L’option Application Teams existante lie l’inscription du secret d’API à votre application Teams spécifique. 
Sélectionnez + Ajouter un secret. Une boîte de dialogue Ajouter une clé API s’affiche.
Entrez une valeur pour le secret, puis sélectionnez Enregistrer.
Remarque
- Vous pouvez conserver jusqu’à deux secrets pour chaque inscription de clé API. Si une clé est compromise, elle peut être rapidement supprimée et permet à Teams de basculer vers la deuxième clé.
- La valeur du secret doit comporter au moins 10 caractères et au maximum 128 caractères.
- Si la première clé génère une erreur 401, Teams tente automatiquement d’utiliser la deuxième clé. Il permet un service ininterrompu pour les utilisateurs et élimine tout temps d’arrêt potentiel lors de la création d’un nouveau secret.
Un ID d’inscription de clé API est généré.
Copiez et enregistrez l’ID d’inscription de la clé API et mettez-le à jour en tant que valeur de la apiSecretRegistrationId propriété dans le manifeste de l’application.
Mettre à jour le manifeste de l’application
Vous pouvez autoriser les demandes entrantes à votre service en configurant une clé API statique. La clé API est stockée en toute sécurité et ajoutée à l’appel d’API. Ajoutez un apiSecretServiceAuthConfiguration objet avec une apiSecretRegistrationId propriété, qui contient l’ID de référence lorsque vous envoyez la clé API via le portail des développeurs pour Teams. Pour plus d’informations, consultez composeExtensions.commands.
"composeExtensions": [
{
"composeExtensionType": "apiBased",
"authorization": {
"authType": "apiSecretServiceAuth",
"apiSecretServiceAuthConfiguration": {
"apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
}
},
Microsoft Entra
microsoftEntra la méthode d’authentification utilise l’identité Teams d’un utilisateur d’application pour lui fournir l’accès à votre application. Un utilisateur qui s’est connecté à Teams n’a pas besoin de se reconnecter à votre application dans l’environnement Teams. Avec uniquement le consentement de l’utilisateur de l’application, l’application Teams récupère les détails d’accès pour celui-ci à partir de Microsoft Entra ID. Une fois que l’utilisateur de l’application a donné son consentement, il peut y accéder même à partir d’autres appareils sans avoir à être validé à nouveau.
Configuration requise
Avant de commencer, vérifiez que vous disposez des éléments suivants :
- Un compte Azure avec un abonnement actif.
- Connaissance de base du Microsoft Entra ID et du développement d’applications Teams.
L’image suivante montre le fonctionnement de l’authentification unique lorsqu’un utilisateur de l’application Teams tente d’accéder à l’application d’extension de message bsed API :
- L’utilisateur appelle l’application d’extension de message basée sur l’API à partir d’une extension de message dans Teams et demande une commande qui nécessite une authentification.
- L’application envoie une requête au service principal Teams avec l’ID d’application et l’étendue requise (access_as_user).
- Le service principal Teams vérifie si l’utilisateur a donné son consentement à l’application et à l’étendue. Si ce n’est pas le cas, il affiche un écran de consentement à l’utilisateur et demande l’autorisation.
- Si l’utilisateur donne son consentement, le service principal Teams génère un jeton d’accès pour l’utilisateur et l’application, et l’envoie à l’application dans l’en-tête d’autorisation de la demande.
- L’application valide le jeton. L’utilisateur peut extraire les informations utilisateur du jeton, telles que le nom, l’e-mail et l’ID d’objet.
- L’application peut utiliser le jeton pour appeler sa propre API.
- L’application retourne la réponse à l’utilisateur dans Teams.
Pour activer la microsoftEntra méthode d’authentification pour l’extension de message basée sur l’API, procédez comme suit :
Inscrire une nouvelle application dans Microsoft Entra ID
Ouvrez le Portail Azure sur votre navigateur web.
Sélectionnez l’icône Inscriptions d'applications.
La page Inscriptions d'applications s’affiche.
Sélectionnez l’icône + Nouvelle inscription.
La page Inscrire une application s’affiche.
Entrez le nom de l’application que vous souhaitez afficher à l’utilisateur de l’application. Vous pouvez modifier le nom ultérieurement si vous le souhaitez.
Sélectionnez le type de compte d’utilisateur qui peut accéder à votre application. Vous pouvez choisir parmi les options monolocataires ou multilocataires dans les répertoires de l’organisation, ou restreindre l’accès aux comptes Microsoft personnels uniquement.
Options pour les types de comptes pris en charge
Option Sélectionnez cette option pour... Comptes dans cet annuaire d’organisation uniquement (Microsoft uniquement - Monolocataire) Créez une application pour une utilisation uniquement par des utilisateurs (ou des invités) dans votre client.
Souvent appelée application personnalisée conçue pour votre organisation (application métier), cette application est une application monolocataire dans le Plateforme d'identités Microsoft.Comptes dans n’importe quel annuaire organisationnel (n’importe quel locataire Microsoft Entra ID - Multilocataire) Permettre aux utilisateurs de n’importe quel locataire Microsoft Entra d’utiliser votre application. Cette option est appropriée si, par exemple, vous créez une application SaaS et que vous envisagez de la mettre à la disposition de plusieurs organisations.
Ce type d’application est appelé application multilocataire dans le Plateforme d'identités Microsoft.Comptes dans n’importe quel annuaire organisationnel (tout locataire Microsoft Entra ID - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox) Ciblez un large ensemble de clients.
En sélectionnant cette option, vous inscrivez une application multilocataire qui peut également prendre en charge les utilisateurs d’applications qui ont des comptes Microsoft personnels.Comptes Microsoft personnels uniquement Créez une application uniquement pour les utilisateurs disposant de comptes Microsoft personnels. Remarque
Vous n’avez pas besoin d’entrer l’URI de redirection pour activer l’authentification unique pour une application d’extension de message basée sur l’API.
Sélectionnez Inscrire. Un message s’affiche sur le navigateur indiquant que l’application a été créée.
La page avec l’ID d’application et d’autres configurations s’affiche.
Notez et enregistrez l’ID d’application à partir de l’ID d’application (client) pour mettre à jour le manifeste de l’application ultérieurement.
Votre application est inscrite dans Microsoft Entra ID. Vous disposez maintenant de l’ID d’application pour votre application d’extension de message basée sur l’API.
Configurer l’étendue du jeton d’accès
Une fois que vous avez créé une inscription d’application, configurez les options d’étendue (autorisation) pour l’envoi du jeton d’accès au client Teams et autorisez les applications clientes approuvées pour activer l’authentification unique.
Pour configurer l’étendue et autoriser les applications clientes approuvées, vous avez besoin des éléments suivants :
- Ajouter l’URI d’ID d’application : Configurez les options d’étendue (autorisation) pour votre application. Exposez une API web et configurez l’URI de l’ID d’application.
- Configurer l’étendue de l’API : définissez l’étendue de l’API et les utilisateurs qui peuvent donner leur consentement pour une étendue. Vous pouvez uniquement autoriser les administrateurs à donner leur consentement pour des autorisations à privilèges plus élevés.
- Configurer l’application cliente autorisée : créez des ID client autorisés pour les applications que vous souhaitez préautoriser. Cela permet à l’utilisateur de l’application d’accéder aux étendues d’application (autorisations) que vous avez configurées, sans nécessiter de consentement supplémentaire. Préautorisez uniquement les applications clientes auxquelles vous faites confiance, car les utilisateurs de votre application n’ont pas la possibilité de refuser le consentement.
URI de l’ID d’application
Sélectionnez Gérer>Exposer une API dans le volet gauche.
La page Exposer une API s’affiche.
Sélectionnez Ajouter pour générer l’URI d’ID d’application sous la forme .
api://{AppID}
La section relative à la définition de l’URI de l’ID d’application s’affiche.
Entrez l’URI de l’ID d’application au format expliqué ici.
- L’URI d’ID d’application est prérempli avec l’ID d’application (GUID) au format
api://{AppID}. - Le format d’URI de l’ID d’application doit être :
api://fully-qualified-domain-name.com/{AppID}. - Insérez le
fully-qualified-domain-name.comentreapi://et{AppID}(autrement dit, le GUID). Par exemple, api://example.com/{AppID}.
Importante
Informations sensibles : l’URI de l’ID d’application est journalisé dans le cadre du processus d’authentification et ne doit pas contenir d’informations sensibles.
URI d’ID d’application pour l’application avec plusieurs fonctionnalités : si vous créez une extension de message basée sur l’API, entrez l’URI de l’ID d’application en tant que
api://fully-qualified-domain-name.com/{YourClientId}, où {YourClientId} est votre ID d’application Microsoft Entra.Format du nom de domaine : utilisez des lettres minuscules pour le nom de domaine. N’utilisez pas de majuscules.
Par exemple, pour créer un service d’application ou une application web avec le nom de la ressource,
demoapplication:Si le nom de la ressource de base utilisé est l’URL sera... Le format est pris en charge dans... demoapplication https://demoapplication.example.netToutes les plateformes. DemoApplication https://DemoApplication.example.netBureau, web et iOS uniquement. Il n’est pas pris en charge sur Android. Utilisez l’option demoapplication en minuscules comme nom de ressource de base.
- L’URI d’ID d’application est prérempli avec l’ID d’application (GUID) au format
Sélectionnez Enregistrer.
Un message s’affiche sur le navigateur indiquant que l’URI de l’ID d’application a été mis à jour.
L’URI d’ID d’application apparaît sur la page.
Notez et enregistrez l’URI ID d’application pour mettre à jour le manifeste de l’application ultérieurement.
Configurer l’étendue de l’API
Remarque
L’extension de message basée sur l’API prend en charge access_as_user étendue uniquement.
Sélectionnez + Ajouter une étendue dans les étendues définies par cette section d’API.
La page Ajouter une étendue s’affiche.
Entrez les détails de la configuration de l’étendue.
- Entrez le nom de l’étendue. Ce champ est obligatoire.
- Sélectionnez l’utilisateur qui peut donner son consentement pour cette étendue. L’option par défaut est Admins uniquement.
- Entrez le nom d’affichage du consentement de l’administrateur. Ce champ est obligatoire.
- Entrez la description du consentement de l’administrateur. Ce champ est obligatoire.
- Entrez le nom d’affichage du consentement de l’utilisateur.
- Entrez la description du consentement de l’utilisateur.
- Sélectionnez l’option Activé pour l’état.
- Sélectionnez Ajouter une étendue.
Un message s’affiche sur le navigateur indiquant que l’étendue a été ajoutée.
La nouvelle étendue que vous avez définie s’affiche sur la page.
Configurer l’application cliente autorisée
Parcourez la page Exposer une API dans la section Application cliente autorisée, puis sélectionnez + Ajouter une application cliente.
La page Ajouter une application cliente s’affiche.
Entrez l’ID client Microsoft 365 approprié pour les applications que vous souhaitez autoriser pour l’application web de votre application.
Remarque
- Les ID de client Microsoft 365 pour les applications mobiles, de bureau et web pour Teams sont les ID réels que vous devez ajouter.
- Pour une application d’extension de message basée sur l’API Teams, vous avez besoin d’une application web ou SPA, car vous ne pouvez pas avoir d’application cliente mobile ou de bureau dans Teams.
Sélectionnez l’un des ID client suivants :
Utiliser l’ID client Pour autoriser... 1fec8e78-bce4-4aaf-ab1b-5451cc387264 Application Teams mobile ou de bureau 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Application Teams web Sélectionnez l’URI de l’ID d’application que vous avez créé pour votre application dans Étendues autorisées pour ajouter l’étendue à l’API web que vous avez exposée.
Sélectionnez Ajouter une application.
Un message s’affiche sur le navigateur indiquant que l’application cliente autorisée a été ajoutée.
L’ID client de l’application autorisée s’affiche sur la page.
Remarque
Vous pouvez autoriser plusieurs applications clientes. Répétez les étapes de cette procédure pour configurer une autre application cliente autorisée.
Vous avez correctement configuré l’étendue de l’application, les autorisations et les applications clientes. Veillez à noter et à enregistrer l’URI de l’ID d’application. Ensuite, vous configurez la version du jeton d’accès.
Mettre à jour le manifeste de l’application
Remarque
webApplicationInfo est pris en charge dans le manifeste d’application version 1.5 ou ultérieure.
Mettez à jour les propriétés suivantes dans le fichier manifeste de l’application :
webApplicationInfo: active l’authentification unique pour votre application afin d’aider les utilisateurs de l’application à accéder en toute transparence à votre application d’extension de message basée sur l’API. qui contient des détails essentiels sur votre application. L’URI d’ID d’application que vous avez inscrit dans Microsoft Entra ID est configuré avec l’étendue de l’API que vous avez exposée. Configurez l’URI de sous-domaine de votre application dansresourcepour vous assurer que la demande d’authentification à l’aidegetAuthToken()de provient du domaine donné dans le manifeste de l’application. Pour plus d'informations, voir webApplicationInfo ..
microsoftEntraConfiguration: active l’authentification unique pour votre application. Configurez lasupportsSingleSignOnpropriété surtruepour prendre en charge l’authentification unique et réduire le besoin de plusieurs authentifications.
Pour configurer le manifeste de l’application :
Ouvrez le projet d’application d’extension de message basée sur l’API.
Ouvrez le dossier manifeste de l’application.
Remarque
- Le dossier manifeste de l’application doit se trouver à la racine de votre projet. Pour plus d’informations, consultez Créer un robot pour Microsoft Teams.
- Pour plus d’informations sur la création d’un manifest.json, consultez le schéma du manifeste d’application.
Ouvrir le
manifest.jsonfichierAjoutez l’extrait de code suivant au fichier manifeste de l’application :
WebApplicationInfo
"webApplicationInfo": { "id": "{Microsoft Entra AppId}", "resource": "api://subdomain.example.com/{Microsoft Entra AppId}" }où,
{Microsoft Entra AppId}est l’ID d’application que vous avez créé lors de l’inscription de votre application dans Microsoft Entra ID. C’est le GUID.subdomain.example.comest l’URI d’ID d’application que vous avez inscrit lors de la création de l’étendue dans Microsoft Entra ID.
MicrosoftEntraConfiguration
"authorization": { "authType": "microsoftEntra", “microsoftEntraConfiguration”: { “supportsSingleSignOn”: true } },Mettez à jour l’URL du sous-domaine dans les propriétés suivantes :
contentUrlconfigurationUrl
Enregistrez le fichier manifeste de l’application.
Pour plus d’informations, consultez composeExtensions.commands.
Authentifier le jeton
Lorsque l’extension de message appelle l’API pendant l’authentification, elle reçoit une requête avec le jeton d’authentification (jeton AED) de l’utilisateur. L’extension de message ajoute ensuite le jeton dans l’en-tête d’autorisation de la requête HTTP sortante. Le format d’en-tête est Authorization: Bearer <token_value>. Par exemple, lorsqu’une extension de message effectue un appel d’API à un service qui nécessite une authentification. L’extension construit une requête HTTP comme suit :
GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Une fois que l’extension de message basée sur l’API a obtenu un en-tête de requête avec un jeton, procédez comme suit :
Authentifier : vérifiez le jeton pour l’audience, l’étendue, l’émetteur et les revendications de signature à case activée si le jeton est destiné à votre application.
Voici un exemple de jeton web JSON (JWT) avec un en-tête et une réponse :
{ "typ": "JWT", "rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.", "alg": "RS256", "kid": "q-23falevZhhD3hm9CQbkP5MQyU" }.{ "aud": "00000002-0000-0000-c000-000000000000", "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0", "iat": 1712509315, "nbf": 1712509315, "exp": 1712513961, "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=", "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264", "azpacr": "0", "name": "John Doe", "oid": "00000000-0000-0000-0000-000000000000", "preferred_username": "john.doe@contoso.com", "rh": "I", "scp": "access_as_user", "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8", "tid": "12345678-aaaa-bbbb-cccc-9876543210ab", "uti": "h7DMQwSPAEeiEe62JJUGAA", "ver": "2.0" }Utiliser le jeton : extrayez les informations utilisateur du jeton, telles que le nom, l’adresse e-mail et l’ID d’objet, puis utilisez le jeton pour appeler la propre API de l’application d’extension de message.
Remarque
L’API reçoit un jeton Microsoft Entra dont l’étendue est définie
access_as_usersur inscrite dans le Portail Azure. Toutefois, le jeton n’est pas autorisé à appeler d’autres API en aval, telles que Microsoft Graph.
Résolution des problèmes
Si vous recevez un message d’erreur Échec de l’analyse du manifeste lors du chargement de l’application dans les équipes, utilisez le validateur d’application Teams pour valider le package d’application, y compris le manifeste de l’application et le fichier de spécification OpenAPI. Passez en revue le manifeste de l’application et les exigences du document Description OpenAPI pour résoudre les erreurs ou les avertissements et essayer de charger votre application.
Si vous rencontrez des problèmes lors de l’exécution de votre application dans Teams, suivez les étapes de résolution des problèmes suivantes pour identifier et résoudre votre problème :
Réseau : sélectionnez l’onglet Réseau dans Outils de développement pour inspecter l’activité réseau
Ouvrez le client web Teams.
Connectez-vous avec vos informations d’identification Microsoft 365.
Accédez à une conversation et exécutez votre application d’extension de message.
En haut à droite, sélectionnez Paramètres et plus (...). Accédez à Plusd’outils> Outils de développement.
SélectionnezRéseau. Sélectionnez l’option de filtre et entrez invoke dans le champ de recherche.
Sélectionnez une erreur dans la liste.
Dans le volet droit, sélectionnez l’onglet Réponse .
Un objet JSON représentant une réponse d’erreur d’un service ou d’une API s’affiche. Il contient un
standardizedErrorobjet avecerrorCode,errorSubCodeeterrorDescription, qui ont plus de détails sur l’erreur.
Réponses d’erreur HTTP courantes :
- Une erreur de requête incorrecte 400 peut se produire si un paramètre de requête est manquant ou mis en forme de manière incorrecte.
- Une erreur 401 Non autorisé ou 403 Interdit suggère des problèmes avec la clé API, tels qu’elle est manquante ou non autorisée.
- Une erreur de serveur interne 500 indique que le service ne sait pas comment répondre, en raison d’un problème côté serveur.
Résolution des problèmes avec les outils : si les informations de la trace réseau sont insuffisantes, vous pouvez construire une requête à la suite du document de description OpenAPI et utiliser des outils comme Swagger Rédacteur ou Postman pour tester la demande, y compris l’en-tête d’autorisation de la clé API si nécessaire.
Si vous ne parvenez pas à résoudre les erreurs, nous vous recommandons de contacter le support technique de Microsoft Teams pour obtenir de l’aide.
Commentaires
Prochainement : Tout au long de l'année 2024, nous supprimerons progressivement les GitHub Issues en tant que mécanisme de retour d'information pour le contenu et nous les remplacerons par un nouveau système de retour d'information. Pour plus d’informations, voir: https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour