Создание исходящих веб-перехватчиков

Статья
03/22/2023

Исходящий веб-перехватчик выступает в качестве бота и ищет сообщения в каналах с помощью @mention. Он отправляет уведомления внешней веб-службе и отвечает расширенными сообщениями, включая карточки и изображения. Это помогает пропустить процесс создания ботов с помощью Microsoft Bot Framework.

См. следующее видео, чтобы узнать, как создать исходящие веб-перехватчики:

Основные функции исходящих веб-перехватчиков

В следующей таблице представлены функции и описание исходящих веб-перехватчиков.

Возможности	Описание
Конфигурация с заданная областью	Веб-перехватчики имеют область действия на уровне группы. Обязательный процесс настройки для каждого из них добавляет исходящий веб-перехватчик.
Реактивный обмен сообщениями	Пользователи должны использовать @mention для веб-перехватчика для получения сообщений. Пользователи могут получать сообщения о исходящих веб-перехватчиках только в общедоступных каналах, а не в личной или частной области.
Стандартный обмен сообщениями HTTP	Ответы появятся в той же цепочке, что и исходное сообщение-запрос, и могут содержать все, что содержат сообщения Bot Framework. Например, форматированный текст, изображения, карточки и эмодзи. Хотя исходящие веб-перехватчики могут использовать карточки, они не могут использовать никакие действия с карточками, кроме `openURL`.
Поддержка метода API Teams	Исходящие веб-перехватчики отправляют HTTP POST в веб-службу и получают ответ. Они не могут получить доступ к другим API, таким как извлечение списка сотрудников или списка каналов в команде.

Создание исходящих веб-перехватчиков

Создание исходящих веб-перехватчиков и добавление пользовательских ботов в Teams. Чтобы создать исходящий веб-перехватчик, выполните следующие действия.

Выберите Teams в левой области.
На странице Teams выберите необходимую команду для создания исходящего веб-перехватчика и выберите •••.
Выберите Управление командой в раскрывающемся меню.
Выберите Приложения на странице канала.
Выберите Создать исходящий веб-перехватчик.
Введите следующие сведения на странице Создание исходящего веб-перехватчика :
- Имя: заголовок веб-перехватчика и вкладка @mention .
- URL-адрес обратного вызова: конечная точка HTTPS, которая принимает полезную нагрузку JSON и получает запросы POST от Teams.
- Описание: подробная строка, которая отображается в карточке профиля и на панели мониторинга приложения уровня команды.
- Изображение профиля: значок приложения для веб-перехватчика, который является необязательным.
Нажмите Создать. Исходящий веб-перехватчик добавляется в канал команды.

Откроется диалоговое окно Код проверки подлинности сообщений на основе хэша (HMAC). Это маркер безопасности, используемый для проверки подлинности звонков между Teams и назначенной внешней службой. Маркер безопасности HMAC не истекает и является уникальным для каждой конфигурации.

Примечание.

Исходящий веб-перехватчик доступен пользователям команды, только если URL-адрес действителен, а маркеры проверки подлинности сервера и клиента равны. Например, рукопожатие HMAC.

В следующем сценарии даны подробные сведения о добавлении исходящего веб-перехватчика.

Сценарий: push-уведомления об изменении состояния на сервере базы данных канала Teams в ваше приложение.
Пример. У вас есть пользовательское приложение, созданное для организации (бизнес-приложение), которое отслеживает все операции CRUD (создание, чтение, обновление и удаление). Эти операции выполняются в записях сотрудников пользователями канала Управления персоналом Teams в клиенте Microsoft 365.

Создайте URL-адрес на сервере приложения, чтобы принять и обработать POST-запрос с помощью полезной нагрузки JSON

Ваша служба получает сообщения в стандартной схеме обмена сообщениями службы Azure Bot. Соединитель Bot Framework — это служба RESTful, которая позволяет обрабатывать обмен сообщениями в формате JSON с помощью протоколов HTTPS, как описано в API службы Azure Bot. Кроме того, вы можете использовать пакет SDK Microsoft Bot Framework для обработки и анализа сообщений. Дополнительные сведения см. в разделе с обзором службы Azure Bot.

Исходящие веб-перехватчики имеют область действия на уровне team и видны всем участникам команды. Чтобы вызвать его в канале, пользователям необходимо @mention имя исходящего веб-перехватчика.

Создание метода проверки токена HMAC исходящего веб-перехватчика

Использование примера входящие сообщения и идентификатора: "contoso" из SigningKeyDictionary из {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }.

Используйте значение "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" в авторизации заголовка запроса.

Чтобы убедиться, что ваша служба получает вызовы только от фактических клиентов Teams, Teams предоставляет код HMAC в заголовке авторизации HTTP hmac. Всегда включайте код в протокол проверки подлинности.

Код всегда должен проверять подпись HMAC, включенную в запрос, следующим образом.

Создание маркера HMAC из текста запроса сообщения. Для этого на большинстве платформ существуют стандартные библиотеки, такие как пример веб-перехватчика Crypto для Node.js и пример веб-перехватчика Teams для C#. В Microsoft Teams используется стандартное шифрование HMAC SHA256. Необходимо преобразовать тело в массив байтов в UTF8.
Вычислите хэш-значение из массива байтов маркера безопасности, предоставленного Teams при регистрации исходящего веб-перехватчика в клиенте Teams. См. статью Создание исходящего веб-перехватчика.
Преобразуйте хэш-значение в строку с помощью кодировки UTF-8.
Сравните строковое значение сгенерированного хэш-значения со значением, предоставленным в HTTP-запросе.

Пример справочника по коду

public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
    //...
    string providedHmacValue = authenticationHeaderValue.Parameter;
    string calculatedHmacValue = null;
    try
    {
        byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
 
        byte[] keyBytes = Convert.FromBase64String(signingKey);
        using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
            calculatedHmacValue = Convert.ToBase64String(hashBytes);
        }
 
        if (string.Equals(providedHmacValue, calculatedHmacValue))
        {
            return new AuthResponse(true, null);
        }
        else
        {
            string errorMessage = string.Format(
                "AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
                calculatedHmacValue,
                providedHmacValue);
 
            return new AuthResponse(false, errorMessage);
        }
    }
    catch (Exception ex)
    {
        Trace.TraceError("Exception occcured while verifying HMAC on the incoming request. Exception: {0}", ex);
        return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
    }
}

Создание метода отправки ответа о выполнении или ошибке

Ответы от исходящих веб-перехватчиков отображаются в той же цепочке ответов, что и исходное сообщение. При выполнении запроса пользователем, Teams отправляет синхронный HTTP-запрос к вашей службе, после чего у вашего кода есть пять секунд, чтобы ответить на сообщение, прежде чем время ожидания соединения истечет и оно прервется.

Пример отклика

{
    "type": "message",
    "text": "This is a reply!"
}

Использование адаптивных карточек с исходящими веб-перехватчиками

Можно отправлять адаптивные карточки, карточки главного имиджевого баннера и текстовые сообщения в виде вложений с помощью исходящего веб-перехватчика. Карточки поддерживают форматирование. Дополнительные сведения см. в разделе Форматирование карточек с помощью Markdown. Адаптивная карточка в исходящих веб-перехватчиках поддерживает только openURL действия с карточками.

Следующие части кода являются примерами отклика адаптивной карточки:

Пример справочника по коду


// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
    {
        content = await reader.ReadToEndAsync();
    }

var Card = new AdaptiveCard(new AdaptiveSchemaVersion("1.4"))
{
    Body = new List<AdaptiveElement>()
    {
        new AdaptiveTextBlock(){Text= $"Request sent by: {incomingActivity.From.Name}"},
        new AdaptiveImage(){Url=new Uri("https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6")},
        new AdaptiveTextBlock(){Text="Sample image for Adaptive Card.."}
    }
};

var attachment = new Attachment()
{
    ContentType = AdaptiveCard.ContentType,
    Content = Card
};

var sampleResponseActivity = new Activity
{
    Attachments = new [] { attachment }
};

return sampleResponseActivity;

Пример справочника по коду

var receivedMsg = JSON.parse(payload);
var responseMsg = JSON.stringify({
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": {
                "type": "AdaptiveCard",
                "version": "1.4",
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Request sent by: " + receivedMsg.from.name
                    },
                    {
                        "type": "Image",
                        "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
                    },
                    {
                        "type": "TextBlock",
                        "text": "Sample image for Adaptive Card."
                    }
                ]
            },
            "name": null,
            "thumbnailUrl": null
        }
    ]
});

{
 "type": "message",
 "attachments": [
  {
   "contentType": "application/vnd.microsoft.card.adaptive",
   "content": {
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
     {
      "type": "TextBlock",
      "text": "Request sent by: Megan"
     },
     {
      "type": "Image",
      "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
     },
     {
      "type": "TextBlock",
      "text": "Sample image for Adaptive Card.."
     }
    ]
   }
  }
 ]
}

Пример кода

Название примера	Описание	.NET	Node.js
Исходящие веб-перехватчики	В этом примере показано, как реализовать и использовать исходящий веб-перехватчик.	Просмотр	View

Пошаговые инструкции

Следуйте пошаговой инструкции, чтобы создать исходящие веб-перехватчики в Teams.

Поделиться через

Создание исходящих веб-перехватчиков

Основные функции исходящих веб-перехватчиков

Создание исходящих веб-перехватчиков

Пример отклика

Использование адаптивных карточек с исходящими веб-перехватчиками

Пример кода

Пошаговые инструкции

См. также

Дополнительные ресурсы