Envoi de messages à des connecteurs et WebhooksSending messages to connectors and webhooks

Pour envoyer un message par le biais de votre connecteur Office 365 ou de webhook entrant, vous publiez une charge utile JSON dans l’URL webhook.To send a message through your Office 365 Connector or incoming webhook, you post a JSON payload to the webhook URL. En règle générale, cette charge utile se présente sous la forme d’une carte de connecteur Office 365.Typically this payload will be in the form of an Office 365 Connector Card.

Vous pouvez également utiliser ce JSON pour créer des cartes contenant des entrées enrichies, telles que l’entrée de texte, la sélection multiple ou la sélection d’une date et d’une heure.You can also use this JSON to create cards containing rich inputs, such as text entry, multi-select, or picking a date and time. Le code qui génère la carte et publie sur l’URL webhook peut être exécuté sur un service hébergé.The code that generates the card and posts to the webhook URL can be running on any hosted service. Ces cartes sont définies dans le cadre de messages intégrant des actions et sont également prises en charge dans les cartes utilisées dans les bots Teams et les extensions de messagerie.These cards are defined as part of actionable messages, and are also supported in cards used in Teams bots and Messaging extensions.

Exemple de message de connecteurExample connector message

{
    "@type": "MessageCard",
    "@context": "http://schema.org/extensions",
    "themeColor": "0076D7",
    "summary": "Larry Bryant created a new task",
    "sections": [{
        "activityTitle": "![TestImage](https://47a92947.ngrok.io/Content/Images/default.png)Larry Bryant created a new task",
        "activitySubtitle": "On Project Tango",
        "activityImage": "https://teamsnodesample.azurewebsites.net/static/img/image5.png",
        "facts": [{
            "name": "Assigned to",
            "value": "Unassigned"
        }, {
            "name": "Due date",
            "value": "Mon May 01 2017 17:07:18 GMT-0700 (Pacific Daylight Time)"
        }, {
            "name": "Status",
            "value": "Not started"
        }],
        "markdown": true
    }],
    "potentialAction": [{
        "@type": "ActionCard",
        "name": "Add a comment",
        "inputs": [{
            "@type": "TextInput",
            "id": "comment",
            "isMultiline": false,
            "title": "Add a comment here for this task"
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Add comment",
            "target": "http://..."
        }]
    }, {
        "@type": "ActionCard",
        "name": "Set due date",
        "inputs": [{
            "@type": "DateInput",
            "id": "dueDate",
            "title": "Enter a due date for this task"
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Save",
            "target": "http://..."
        }]
    }, {
        "@type": "ActionCard",
        "name": "Change status",
        "inputs": [{
            "@type": "MultichoiceInput",
            "id": "list",
            "title": "Select a status",
            "isMultiSelect": "false",
            "choices": [{
                "display": "In Progress",
                "value": "1"
            }, {
                "display": "Active",
                "value": "2"
            }, {
                "display": "Closed",
                "value": "3"
            }]
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Save",
            "target": "http://..."
        }]
    }]
}

Ce message génère la carte suivante dans le canal.This message produces the following card in the channel.

Capture d’écran d’une carte de connecteur

Créations des messages intégrant des actionsCreating actionable messages

L’exemple de la section précédente inclut trois boutons visibles sur la carte.The example in the preceding section includes three visible buttons on the card. Chaque bouton est défini dans la propriété potentialAction du message à l’aide d'actions ActionCard, contenant chacune un type d’entrée : un champ de texte, un sélecteur de dates ou une liste à choix multiple.Each button is defined in the potentialAction property of the message by using ActionCard actions, each containing an input type: a text field, a date picker, or a multi-choice list. Chaque action ActionCard est associée à une action (par exemple, HttpPOST).Each ActionCard action has an associated action, for example HttpPOST.

Les cartes de connecteur prennent en charge trois types d’actions :Connector cards support three types of actions:

  • ActionCard Affiche un ou plusieurs types d’entrées et actions associéesActionCard Presents one or more input types and associated actions
  • HttpPOST Envoie une demande de publication à une URL.HttpPOST Sends a POST request to a URL
  • OpenUri Ouvre un URI dans un navigateur ou une application distincte, cible de façon facultative différents URI basés sur des systèmes d’exploitationOpenUri Opens a URI in a separate browser or app; optionally targets different URIs based on operating systems

(Une quatrième action, ViewAction, n’est pas encore prise en charge, mais n’est plus nécessaire. Utilisez OpenUri à la place.)(A fourth action, ViewAction, is still supported but no longer needed; use OpenUri instead.)

L'action ActionCard prend en charge trois types d'entrée :The ActionCard action supports three input types:

  • TextInput Zone de texte d'une ou plusieurs lignes avec une limite de longueur facultativeTextInput A single-line or multiline text field with an optional length limit
  • DateInput Sélecteur de date avec un sélecteur d’heures facultatifDateInput A date selector with an optional time selector
  • MultichoiceInput Liste énumérée de choix proposant une sélection unique ou plusieurs sélectionsMultichoiceInput A enumerated list of choices offering either a single selection or multiple selections

MultichoiceInput prend en charge une propriété style qui contrôle l’affichage initial complet de la liste.MultichoiceInput supports a style property that controls whether the list initially appears fully expanded. La valeur par défaut de style dépend de la valeur de isMultiSelect.The default value of style depends on the value of isMultiSelect.

isMultiSelect style par défautstyle default
false ou non spécifiéfalse or not specified compact
true expanded

Si vous souhaitez afficher une liste de sélections à l’origine dans le style compact, vous devez spécifier "isMultiSelect": true et "style": true.If you want a multiselect list initially displayed in the compact style, you must specify both "isMultiSelect": true and "style": true.

Notes

Spécifier compact pour la propriété style dans Microsoft Teams revient à spécifier normal pour la propriété style dans Microsoft Outlook.Specifying compact for the style property in Microsoft Teams is the same as specifying normal for the style property in Microsoft Outlook.

Pour accéder à d’autres informations sur les actions de la carte de connecteur, consultez Actions dans la référence de carte de message intégrant des actions.For all other details about Connector card actions, see Actions in the actionable message card reference.

Configuration d’un webhook entrant personnaliséSetting up a custom incoming webhook

Pour découvrir comment envoyer une carte simple à un connecteur, procédez comme suit.Follow these steps to see how to send a simple card to a Connector.

  1. Dans Microsoft Teams, choisissez Autres options () à côté du nom de la chaîne, puis choisissez Connecteurs.In Microsoft Teams, choose More options () next to the channel name and then choose Connectors.
  2. Faites défiler la liste des Connecteurs à Webhook entrant, puis choisissez Ajouter.Scroll through the list of Connectors to Incoming Webhook, and choose Add.
  3. Entrez un nom pour le webhook, téléchargez une image à associer aux données du webhook, puis choisissezCréer.Enter a name for the webhook, upload an image to associate with data from the webhook, and choose Create.
  4. Copiez le webhook dans le presse-papiers et enregistrez-le.Copy the webhook to the clipboard and save it. Vous aurez besoin de l’URL de webhook pour envoyer des informations à Microsoft Teams.You'll need the webhook URL for sending information to Microsoft Teams.
  5. Choisissez OK.Choose Done.

Publier un message sur le webhook à l’aide de cURLPost a message to the webhook using cURL

Les étapes suivantes utilisent cURL.The following steps use cURL. Nous partons du principe que vous avez installé cette application et que vous êtes familiarisé avec son utilisation de base.We assume that you have this installed and are familiar with its basic usage.

  1. Depuis la ligne de commande , entrez la commande cURL suivante :From the command line, enter the following cURL command:

    // on macOS or Linux
    curl -H 'Content-Type: application/json' -d '{"text": "Hello World"}' <YOUR WEBHOOK URL>
    
    // on Windows
    curl.exe -H "Content-Type:application/json" -d "{'text':'Hello World'}" <YOUR WEBHOOK URL>
    
  2. Si la publication réussit, un simple résultat 1 est affiché par curl.If the POST succeeds, you should see a simple 1 output by curl.

  3. Consultez le client Microsoft Team.Check the Microsoft Team client. Vous devriez voir la nouvelle carte publiée dans l’équipe.You should see the new card posted to the team.

Publier un message sur le webhook à l’aide de PowerShellPost a message to the webhook using PowerShell

Les étapes suivantes utilisent PowerShell.The following steps use PowerShell. Nous partons du principe que vous avez installé cette application et que vous êtes familiarisé avec son utilisation de base.We assume that you have this installed and are familiar with its basic usage.

  1. À partir de l'invite PowerShell, entrez les commandes suivantes :From the PowerShell prompt, enter the following command:

    Invoke-RestMethod -Method post -ContentType 'Application/Json' -Body '{"text":"Hello World!"}' -Uri <YOUR WEBHOOK URL>
    
  2. Si la publication réussit, un simple résultat 1 est affichée par Invoke-RestMethod.If the POST succeeds, you should see a simple 1 output by Invoke-RestMethod.

  3. Vérifiez le canal Microsoft Teams associé à l’URL de webhook.Check the Microsoft Teams channel associated with the webhook URL. Vous devriez voir la nouvelle carte publiée sur le canal.You should see the new card posted to the channel.

  • Vous avez le choix entre deux icônes, en suivant les instructions figurant dans Icônes.Include two icons, following the instructions in Icons.
  • Modifiez la partie icons du manifeste pour faire référence aux noms de fichier des icônes au lieu des URL.Modify the icons portion of the manifest to refer to the file names of the icons instead of URLs.

Le fichier manifest.json suivant contient les éléments de base nécessaires pour tester et envoyer votre application.The following manifest.json file contains the basic elements needed to test and submit your app.

Notes

Remplacez id et connectorId de l’exemple suivant par le GUID de votre connecteur.Replace id and connectorId in the following example with the GUID of your Connector.

Exemple de fichier manifest.json avec ConnecteurExample manifest.json with connector

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "id": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
  "version": "1.0",
  "packageName": "com.sampleapp",
  "developer": {
    "name": "Publisher",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.microsoft.com",
    "termsOfUseUrl": "https://www.microsoft.com"
  },
  "description": {
    "full": "This is a small sample app we made for you! This app has samples of all capabilities Microsoft Teams supports.",
    "short": "This is a small sample app we made for you!"
  },
  "icons": {
    "outline": "sampleapp-outline.png",
    "color": "sampleapp-color.png"
  },
  "connectors": [
    {
      "connectorId": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
      "scopes": [
        "team"
      ]
    }
  ],
  "name": {
    "short": "Sample App",
    "full": "Sample App"
  },
  "accentColor": "#FFFFFF",
  "needsIdentity": "true"
}

Envoyer des cartes adaptatives à l'aide d'un webhook entrantSend adaptive cards using an incoming webhook

Notes

✔ Tous les éléments du schéma de la carte adaptative native, à l'exceptionAction.Submit, sont entièrement pris en charge.✔ All native adaptive card schema elements, except Action.Submit, are fully supported.

✔ Les actions soutenues sont ** Action.OpenURL **, Action.ShowCard,et **Action.ToggleVisibility **.✔ The supported Actions are Action.OpenURL, Action.ShowCard, and Action.ToggleVisibility.

Le flux pour l'envoide cartes adaptatives via un webhook entrant est le suivant :The flow for sending adaptive cards via an incoming webhook is as follows:

1. Configurer un webhook personnalisé dans Teams.1. Setup a custom webhook in Teams.

2. Créez votre fichier JSON de carte adaptative :2. Create your adaptive card JSON file:

{
   "type":"message",
   "attachments":[
      {
         "contentType":"application/vnd.microsoft.card.adaptive",
         "contentUrl":null,
         "content":{
            "$schema":"http://adaptivecards.io/schemas/adaptive-card.json",
            "type":"AdaptiveCard",
            "version":"1.2",
            "body":[
                {
                "type": "TextBlock",
                "text": "For Samples and Templates, see https://adaptivecards.io/samples](https://adaptivecards.io/samples)",
                }
            ]
         }
      }
   ]
}
  • Le "type" champ doit être"message".The "type" field must be "message".
  • Le"attachments" tableau contient un ensemble d'objets carte.The "attachments" array contains a set of card objects.
  • Le"contentType" champ doit être réglé sur le type de carte adaptative.The "contentType" field must be set to adaptive card type.
  • L’"content" objet est la carte formatée en JSON.The "content" object is the card formatted in JSON.

3. Testez votre carte adaptative avec le facteur3. Test your adaptive card with Postman

Vous pouvez tester votre carte adaptative en utilisant le facteur pour envoyer une demande POST à l'URL que vous avez créée lors de la configuration de votre webhook entrant.You can test your adaptive card using Postman to send a POST request to the URL that you created when you setup your incoming webhook. Collez votre fichier JSON dans le corps de la demande et visualisez le message de votre carte adaptative dans Teams.Paste your JSON file in the body of the request and view your adaptive card message in Teams.

Conseil

Vous pouvez utiliser des échantillons et des modèles de codes de carte adaptative pour le corps de votre demande de test Post.You can use adaptive card code Samples and Templates for the body of your test Post request.

Test du connecteurTesting your connector

Pour tester le connecteur, téléchargez-le dans une équipe comme vous le feriez avec une autre application.To test your Connector, upload it to a team as you would with any other app. Vous pouvez créer un package .zip à l’aide du fichier manifeste à partir du tableau de bord du développeur de connecteurs (modifié comme indiqué dans la section précédente) et des deux fichiers d’icône.You can create a .zip package using the manifest file from the Connectors Developer Dashboard (modified as directed in the preceding section) and the two icon files.

Une fois que vous avez téléchargé l’application, ouvrez la liste des connecteurs à partir de n’importe quel canal.After you upload the app, open the Connectors list from any channel. Faites défiler la page vers le bas pour afficher votre application dans la section Téléchargé.Scroll to the bottom to see your app in the Uploaded section.

Capture d’écran de la section téléchargée dans la boîte de dialogue connecteur

Vous pouvez à présent lancer l’expérience de configuration.You can now launch the configuration experience. N’oubliez pas que ce flux se produit entièrement au sein de Microsoft Teams via une fenêtre indépendante.Be aware that this flow occurs entirely within Microsoft Teams through a pop-up window. Pour l’instant, ce comportement diffère de l’expérience de configuration dans les connecteurs que vous avez créés. Nous travaillons à l’unification de l’expérience.Currently, this behavior differs from the configuration experience in Connectors that we created; we are working on unifying the experiences.

Pour vérifier qu’une action HttpPOST fonctionne correctement, utilisez votre webhook entrant personnalisé.To verify that an HttpPOST action is working correctly, use your custom incoming webhook.

Limitation du taux pour les connecteursRate limiting for connectors

Les limites de débit d'application contrôlent le trafic qu'un connecteur ou un webhook entrant est autorisé à générer sur un canal.Application rate limits control the traffic that a connector or an incoming webhook is allowed to generate on a channel. Les équipes effectuent le suivi des demandes via une fenêtre à débit fixe et un compteur incrémentiel mesuré en secondes.Teams tracks requests via a fixed-rate window and incremental counter measured in seconds. Si le nombre de demandes est trop élevé, la connexion client sera limitée jusqu’à l’actualisation de la fenêtre, c’est-à-dire, pour la durée du débit fixe.If too many requests are made, the client connection will be throttled until the window refreshes, i.e., for the duration of the fixed rate.

Seuils de transaction par secondeTransactions per second thresholds

Durée (secondes)Time (seconds) Nombre maximal de demandes autoriséesMaximum allowed requests
11 44
3030 6060
36003600 100100
72007200 150150
8640086400 18001800

Voir aussi Connecteurs Office 365 — Microsoft TeamsSee also Office 365 Connectors — Microsoft Teams

Une logique des nouvelles tentatives avec une sauvegarde exponentielle comme ci-dessous permet de limiter les débits pour les cas où les demandes dépassent les limites en une seconde.A retry logic with exponential back-off like below would mitigate rate limiting for cases where requests are exceeding the limits within a second. Veuillez suivre les meilleures pratiques pour éviter d’atteindre les limites de débit.Please follow best practices to avoid hitting the rate limits.

// Please note that response body needs to be extracted and read 
// as Connectors do not throw 429s
try
{
    // Perform Connector POST operation     
    var httpResponseMessage = await _client.PostAsync(IncomingWebhookUrl, new StringContent(content));
    // Read response content
    var responseContent = await httpResponseMessage.Content.ReadAsStringAsync();
    if (responseContent.Contains("Microsoft Teams endpoint returned HTTP error 429")) 
    {
        // initiate retry logic
    }
}

Ces limites sont en place pour réduire le courrier indésirable d’un canal par un connecteur et de garantir une expérience optimale pour vos utilisateurs finaux.These limits are in place to reduce spamming a channel by a connector and ensures an optimal experience to your end users.