Отправка сообщений соединителям и веб-перехватчикамSending messages to connectors and webhooks

Чтобы отправить сообщение через соединитель Office 365 или входящий веб-перехватчик, необходимо отправить полезные данные JSON на URL-адрес веб-перехватчика.To send a message through your Office 365 Connector or incoming webhook, you post a JSON payload to the webhook URL. Как правило, эти полезные данные будут отображаться в форме карточки соединителя Office 365.Typically this payload will be in the form of an Office 365 Connector Card.

С помощью этого кода JSON также можно создавать карточки с различными элементами для ввода данных, например текстовыми полями, переключателями множественного выбора или средствами выбора даты и времени.You can also use this JSON to create cards containing rich inputs, such as text entry, multi-select, or picking a date and time. Код, генерирующий карточку и отправляющий ее на URL-адрес веб-перехватчика, может выполняться в любой размещенной службе.The code that generates the card and posts to the webhook URL can be running on any hosted service. Эти карточки определяются в составе сообщений с действиями, а также поддерживаются в карточках, используемых ботами Teams и расширениями для обмена сообщениями.These cards are defined as part of actionable messages, and are also supported in cards used in Teams bots and Messaging extensions.

Пример сообщения соединителяExample 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://..."
        }]
    }]
}

Это сообщение создает на канале представленную ниже карточку.This message produces the following card in the channel.

Снимок экрана с карточкой соединителя

Создание сообщений с действиямиCreating actionable messages

В примере карточки из предыдущего раздела отображаются три кнопки.The example in the preceding section includes three visible buttons on the card. Каждая кнопка определена в свойстве potentialAction сообщения с помощью действий ActionCard, каждое из которых содержит тип элемента ввода: текстовое поле, элемент управления "Выбор даты" или список с возможностью выбора нескольких вариантов.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. С каждым действием ActionCard связано другое действие, например HttpPOST.Each ActionCard action has an associated action, for example HttpPOST.

Карточки соединителей поддерживают действия трех типов:Connector cards support three types of actions:

  • ActionCard: представляет один или несколько типов входных данных и соответствующие действия;ActionCard Presents one or more input types and associated actions
  • HttpPOST: отправляет запрос POST на URL-адрес;HttpPOST Sends a POST request to a URL
  • OpenUri: открывает URI в отдельном браузере или приложении; при необходимости ссылается на разные URI в зависимости от операционной системы.OpenUri Opens a URI in a separate browser or app; optionally targets different URIs based on operating systems

(Четвертое действие, ViewAction, также поддерживается, но больше не требуется. Используйте вместо него действие OpenUri.)(A fourth action, ViewAction, is still supported but no longer needed; use OpenUri instead.)

Действие ActionCard поддерживает три типа входных данных:The ActionCard action supports three input types:

  • TextInput: однострочное или многострочное текстовое поле с необязательным ограничением длины;TextInput A single-line or multiline text field with an optional length limit
  • DateInput: средство выбора даты с необязательным выбором времени;DateInput A date selector with an optional time selector
  • MultichoiceInput: нумерованный список вариантов с возможностью выбора одного или нескольких пунктов;MultichoiceInput A enumerated list of choices offering either a single selection or multiple selections

MultichoiceInput поддерживает свойство style, указывающее, отображается ли список изначально полностью развернутым.MultichoiceInput supports a style property that controls whether the list initially appears fully expanded. Значение style по умолчанию зависит от значения isMultiSelect.The default value of style depends on the value of isMultiSelect.

isMultiSelect Значение style по умолчаниюstyle default
false или не заданоfalse or not specified compact
true expanded

Если вам нужно, чтобы список со множественным выбором изначально отображался в компактном стиле, необходимо задать значения "isMultiSelect": true и "style": true.If you want a multiselect list initially displayed in the compact style, you must specify both "isMultiSelect": true and "style": true.

Примечание

Значение compact для свойства style в Microsoft Teams равноценно значению normal для свойства style в Microsoft Outlook.Specifying compact for the style property in Microsoft Teams is the same as specifying normal for the style property in Microsoft Outlook.

Все остальные сведения о действиях карточек соединителей представлены в разделе Действия справки по карточкам сообщений с действиями.For all other details about Connector card actions, see Actions in the actionable message card reference.

Настройка пользовательского входящего веб-перехватчикаSetting up a custom incoming webhook

Выполните указанные ниже действия, чтобы отправить простую карточку в соединитель.Follow these steps to see how to send a simple card to a Connector.

  1. В Microsoft Teams нажмите Дополнительные параметры ( ) рядом с названием канала и выберите Соединители.In Microsoft Teams, choose More options ( ) next to the channel name and then choose Connectors.
  2. Прокрутите список соединителей до пункта Входящий веб-перехватчик и нажмите кнопку Добавить.Scroll through the list of Connectors to Incoming Webhook , and choose Add.
  3. Введите имя веб-перехватчика, отправьте изображение, которое следует связать с данными от веб-перехватчика, и нажмите кнопку Создать.Enter a name for the webhook, upload an image to associate with data from the webhook, and choose Create.
  4. Скопируйте веб-перехватчик в буфер обмена и сохраните его.Copy the webhook to the clipboard and save it. Для отправки информации в Microsoft Teams вам потребуется URL-адрес веб-перехватчика.You'll need the webhook URL for sending information to Microsoft Teams.
  5. Нажмите кнопку Готово.Choose Done.

Отправка сообщения веб-перехватчику с помощью cURLPost a message to the webhook using cURL

Для выполнения описанных ниже действий используется cURL.The following steps use cURL. Предполагается, что у вас уже установлена эта программа, а вы знакомы с основами ее использования.We assume that you have this installed and are familiar with its basic usage.

  1. Введите в командной строке следующую команду cURL: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. В случае успешного выполнения запроса POST команда curl должна возвращать простой отклик 1.If the POST succeeds, you should see a simple 1 output by curl.

  3. Проверьте клиент Microsoft Teams.Check the Microsoft Team client. Вы увидите новую карточку, опубликованную в группе.You should see the new card posted to the team.

Отправка сообщения веб-перехватчику с помощью PowerShellPost a message to the webhook using PowerShell

Для выполнения описанных ниже действий используется PowerShell.The following steps use PowerShell. Предполагается, что у вас уже установлена эта программа, а вы знакомы с основами ее использования.We assume that you have this installed and are familiar with its basic usage.

  1. В командной строке PowerShell введите следующую команду:From the PowerShell prompt, enter the following command:

    Invoke-RestMethod -Method post -ContentType 'Application/Json' -Body '{"text":"Hello World!"}' -Uri <YOUR WEBHOOK URL>
    
  2. В случае успешного выполнения запроса POST команда Invoke-RestMethod должна возвращать простой отклик 1.If the POST succeeds, you should see a simple 1 output by Invoke-RestMethod.

  3. Проверьте канал Microsoft Teams, связанный с URL-адресом веб-перехватчика.Check the Microsoft Teams channel associated with the webhook URL. На канале должна появиться новая карточка.You should see the new card posted to the channel.

  • Включите два значка, следуя инструкциям из раздела Значки.Include two icons, following the instructions in Icons.
  • Измените раздел icons манифеста, чтобы он ссылался на имена файлов значков, а не на их URL-адреса.Modify the icons portion of the manifest to refer to the file names of the icons instead of URLs.

Приведенный ниже файл manifest.json содержит основные элементы, необходимые для тестирования и отправки приложения.The following manifest.json file contains the basic elements needed to test and submit your app.

Примечание

Замените id и connectorId в приведенном ниже примере на GUID соединителя.Replace id and connectorId in the following example with the GUID of your Connector.

Пример manifest.json с соединителемExample manifest.json with connector

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/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"
}

Отправка адаптивных карточек с помощью входящего веб-перехватчикаSend adaptive cards using an incoming webhook

Примечание

✔ Все встроенные элементы схемы адаптивной карточки, кроме Action.Submit, полностью поддерживаются.✔ All native adaptive card schema elements, except Action.Submit, are fully supported.

✔ Поддерживаемые действия: Action.OpenURL, Action.ShowCard и Action.ToggleVisibility.✔ The supported Actions are Action.OpenURL, Action.ShowCard, and Action.ToggleVisibility.

Для отправки адаптивных карточек через входящий веб-перехватчик используется следующий поток:The flow for sending adaptive cards via an incoming webhook is as follows:

1. Настройка пользовательского веб-перехватчика в Teams.1. Setup a custom webhook in Teams.

2. Создание файла JSON адаптивной карточки: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)",
                }
            ]
         }
      }
   ]
}
  • Поле "type" должно иметь значение "message".The "type" field must be "message".
  • Массив "attachments" содержит набор объектов card.The "attachments" array contains a set of card objects.
  • В поле "contentType" следует задать тип "Адаптивная карточка".The "contentType" field must be set to adaptive card type.
  • Объект "content" — это карточка, отформатированная в JSON.The "content" object is the card formatted in JSON.

3. Тестирование адаптивной карточки с помощью Postman3. Test your adaptive card with Postman

Вы можете протестировать адаптивную карточку с помощью Postman, чтобы отправить запрос POST на URL-адрес, который вы создали при настройке входящего веб-перехватчика.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. Вставьте файл JSON в текст запроса и просмотрите сообщение адаптивной карточки в Teams.Paste your JSON file in the body of the request and view your adaptive card message in Teams.

Совет

В тексте запроса проверки POST можно использовать образцы и шаблоны кода адаптивной карточки.You can use adaptive card code Samples and Templates for the body of your test Post request.

Тестирование соединителяTesting your connector

Чтобы тестировать соединитель, отправьте его команде, как в любом другом приложении.To test your Connector, upload it to a team as you would with any other app. Вы можете создать ZIP-пакет, используя файл манифеста с панели администрирования для разработчиков соединителей (измененный согласно инструкциям из предыдущего раздела) и два файла значков.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.

После отправки приложения откройте список соединителей с любого канала.After you upload the app, open the Connectors list from any channel. Прокрутите вниз, чтобы найти свое приложение в разделе Отправленные.Scroll to the bottom to see your app in the Uploaded section.

Снимок экрана раздела отправленных приложений в диалоговом окне соединителя

Теперь можно запустить среду настройки.You can now launch the configuration experience. Обратите внимание, что этот процесс полностью выполняется в Microsoft Teams во всплывающем окне.Be aware that this flow occurs entirely within Microsoft Teams through a pop-up window. В настоящее время он отличается от процесса настройки в созданных нами соединителях. Мы работаем над согласованием этих процессов.Currently, this behavior differs from the configuration experience in Connectors that we created; we are working on unifying the experiences.

Чтобы убедиться в правильной работе действия HttpPOST, используйте пользовательский входящий веб-перехватчик.To verify that an HttpPOST action is working correctly, use your custom incoming webhook.

Ограничение скорости для соединителейRate limiting for connectors

Ограничения скорости приложений управляют трафиком, который разрешено создавать в канале соединителю или входящему веб-перехватчику.Application rate limits control the traffic that a connector or an incoming webhook is allowed to generate on a channel. В Teams запросы отслеживаются с помощью окна фиксированной скорости и инкрементного счетчика с измерением в секундах.Teams tracks requests via a fixed-rate window and incremental counter measured in seconds. При наличии слишком большого количества запросов скорость подключения клиента будет ограничена до обновления окна, т. е. в течение длительности окна фиксированной скорости.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.

Пороговые значения количества транзакций в секундуTransactions per second thresholds

Время (секунды)Time (seconds) Максимальное разрешенное количество запросовMaximum allowed requests
11 44
3030 6060
36003600 100100
72007200 150150
86 40086400 18001800

Также см. Соединители Office 365 — Microsoft TeamsSee also Office 365 Connectors — Microsoft Teams

Логика повторных попыток с экспоненциальной задержкой, подобная приведенной ниже, поможет избежать ограничения скорости в тех случаях, когда число запросов за секунду превышает пределы.A retry logic with exponential back-off like below would mitigate rate limiting for cases where requests are exceeding the limits within a second. Следуйте рекомендациям, чтобы предотвратить достижение пределов скорости.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
    }
}

Эти ограничения установлены с целью предотвратить перегрузку канала запросами от соединителя и обеспечивают удобство работы пользователей.These limits are in place to reduce spamming a channel by a connector and ensures an optimal experience to your end users.