Развертывание ссылки
Важно!
Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел Расширения сообщений — пакет SDK версии 3 в папке Resources документации.
В этом документе описывается, как добавить раскройку ссылок в манифест приложения с помощью портала разработчика и вручную. При распаковке ссылок приложение может зарегистрироваться для получения действия вызова, когда URL-адреса с определенным доменом вставляются в область создания сообщений.
invoke
содержит полный URL-адрес, вставленный в область создания сообщения, и вы можете показать карточку с дополнительной информацией или действиями, которую пользователь может развернуть. Это работает аналогично команде поиска, только в качестве условия поиска используется URL-адрес. Теперь можно добавить раскройку ссылок в Microsoft Teams без установки приложения.
Примечание.
- Результат развертывания ссылки кэшируется в течение 30 минут.
- Распаковка ссылок поддерживает адаптивные карточки версии 1.3 и более ранних версий.
- Команды расширения обмена сообщениями не требуются для распаковки связи. Однако в манифесте должна быть по крайней мере одна команда, так как она является обязательным свойством в расширениях обмена сообщениями. Дополнительные сведения см. в разделе Создание расширений.
- Для мобильного клиента распаковка ссылок поддерживается только для ссылок, не требующих проверки подлинности.
На следующем рисунке показан пример распаковки ссылок в классических и мобильных клиентах Teams:
Когда ссылка вставляется в область сообщения Создания Teams, ссылка разворачивается в карточке с сведениями о рабочем элементе.
Дополнительные сведения о раскрое ссылок см. в следующем видео:
Добавление развертывания ссылок в манифест приложения
Чтобы добавить развертывание ссылок в манифест приложения, добавьте новый массив messageHandlers
в раздел composeExtensions
манифеста приложения JSON. Массив можно добавить с помощью портала разработчика или вручную. Списки доменов могут содержать подстановочные знаки, например *.example.com
, которые соответствуют только одному сегменту домена. Если необходимо сопоставить a.b.example.com
, используйте *.*.example.com
.
Примечание.
Убедитесь, что вы не добавляете домены, которые не являются вашим контролем, напрямую или с помощью подстановочных знаков. Например, yourapp.onmicrosoft.com
является допустимым, но *.onmicrosoft.com
недопустимым. Домены верхнего уровня запрещены, например *.com
, *.org
.
Добавление распаковки ссылок с помощью портала разработчика
Откройте портал разработчика в клиенте Microsoft Teams и выберите вкладку Приложения .
Примечание.
Необходимо добавить приложение портала разработчика, если оно не добавлено в клиенте Teams.
Загрузите манифест вашего приложения.
Выберите Расширение для обмена сообщениями в разделе Функции приложения , а затем выберите Выбрать существующего бота или Создать новый бот.
Выберите Сохранить.
Выберите Добавить домен в разделе Ссылки предварительного просмотра и введите допустимый домен.
Нажмите Добавить. На изображении ниже даны пояснения по этому процессу.
Добавление развертывания ссылок вручную
Примечание.
Если проверка подлинности добавлена с помощью Идентификатора Microsoft Entra, разворачивайте ссылки в Teams с помощью бота.
Во-первых, необходимо добавить массив в messageHandlers
манифест приложения и включить расширение сообщений для взаимодействия со ссылками. В следующем примере объясняется, как вручную добавить развертывание ссылок.
...
{
"composeExtensions": [
{
"botId": "abc123456-ab12-ab12-ab12-abcdef123456",
"messageHandlers": [
{
"type": "link",
"value": {
"domains": [
"*.trackeddomain.com"
]
}
}
]
}
]
}
...
Полный пример манифеста см. по ссылке на манифест.
Обработка вызова composeExtensions/queryLink
После добавления домена в манифест приложения необходимо обновить код веб-службы для обработки invoke
запроса. Используйте полученный URL-адрес для поиска в службе и создания ответа карточки. Если вы отвечаете с помощью более чем одной карточки, используется только первый ответ.
Примечание.
Ответ бота должен содержать preview
свойство .
Поддерживаемые типы карточек представлены ниже.
- Адаптивная карточка
- Карточка эскиза
- Карточка главного имиджевого баннера
- Карточка соединителя для групп Microsoft 365
Дополнительные сведения см. в статье Вызов типа действия.
Следующий код является примером invoke
запроса:
Ниже приводится пример invoke
, отправленного вашему боту.
{
"type": "invoke",
"name": "composeExtension/queryLink",
"value": {
"url": "https://theurlsubmittedbyyouruser.trackeddomain.com/id/1234"
}
}
Пример ответа:
{
"composeExtension":
{
"type": "result",
"attachmentLayout": "list",
"attachments":
[
{
"contentType": "application/vnd.microsoft.card.adaptive",
"preview":
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": << Card Payload >>
},
"contentType": "application/vnd.microsoft.card.adaptive",
"content": << Card Payload >>
}
]
}
}
Микро-возможности для ссылок на веб-сайт
Самый распространенный способ предоставления общего доступа к содержимому в Microsoft Teams — это ссылки. Для любой ссылки Teams разворачивает предварительный просмотр ссылки в адаптивную карточку с такими сведениями, как изображение, заголовок и описание.
Вы можете отображать расширенные предварительные версии ссылок, не устанавливая приложение в Microsoft Teams. Добавьте метаданные schema.org на веб-сайт в формате JSON-LD и используйте шаблоны микро-возможностей, соответствующие вашему продукту. Teams использует эти шаблоны, чтобы развернуть расширенные предварительные версии ссылок в Microsoft Teams.
Включение полнофункционированных предварительных просмотров ссылок
Если вы уже добавили schema.org на веб-сайт, вы можете просмотреть расширенный предварительный просмотр ссылки, вставив ее в область создания сообщений Teams.
Если вы не добавили schema.org на веб-сайт, вы можете вручную проверить расширенный предварительный просмотр, выполнив следующие действия.
Добавьте метаданные schema.org в формате JSON-LD на веб-сайт .
На веб-сайте проверьте поддерживаемый
@type
атрибут и скопируйте метаданные в тегapplication/ld+json
скрипта .Откройте конструктор адаптивных карточек и создайте новый файл.
В редакторе примеров данных вставьте метаданные JSON с веб-сайта.
Проверьте шаблон микро-возможностей и добавьте его код в РЕДАКТОР ПОЛЕЗНЫХ ДАННЫХ КАРТОЧКИ.
При необходимости добавьте новые атрибуты из шаблона в метаданные веб-сайта в редакторе примеров данных.
Чтобы предварительный просмотр интерфейса разворачивать адаптивную карточку, выберите Режим предварительного просмотра.
Дополнительные сведения см. в разделе Микро-возможности для ссылок на веб-сайт.
Нулевая установка для распаковки ссылок
Распаковка ссылок нулевой установки позволяет развертывать предварительные версии общих ссылок даже до того, как пользователь обнаружит или установит приложение в Teams. Вы можете анонимно разворачивать карточки с новым invoke
запросом или создавать предварительную версию адаптивной карточки для пользователей перед установкой или проверкой подлинности приложения.
На следующем рисунке представлен последовательный поток для включения и использования распаковки канала установки.
Включение распаковки канала нулевой установки
Чтобы подготовить приложение к распаковку ссылки нулевой установки, выполните следующие действия.
Присвойте свойству
supportsAnonymizedPayloads
значение true в схеме манифеста.Настройте приложение для обработки нового
invoke
запросаcomposeExtensions/anonymousQueryLink
.Пример нового
invoke
запроса:Пример полезных
invoke
данных запроса:{ "name":"composeExtension/anonymousQueryLink", "type":"invoke", "timestamp":"2021-12-02T08:12:21.148Z", "localTimestamp":"2021-12-02T00:12:21.148-08:00", "id":"f:43d59e15-6114-bd53-08c3-b232aa648ec1", "channelId":"msteams", "serviceUrl":"https://smba.trafficmanager.net/amer/", "from":{ "id":"redacted", "name":"redacted" }, "conversation":{ "isGroup":true, "conversationType":"groupChat", "tenantId":"redacted", "id":" redacted", "name":" redacted" }, "recipient":{ "id":"28:85fa138c-7654-4236-86eb-466160687029", "name":"test bot" }, "entities":[ { "locale":"en-US", "country":"US", "platform":"Mac", "timezone":"America/Los_Angeles", "type":"clientInfo" } ], "channelData":{ "tenant":{ "id":" redacted" }, "source":{ "name":"compose" } }, "value":{ "url":"https://test.test.com/test" }, "locale":"en-US", "localTimezone":"America/Los_Angeles" }
Ответ на полезные
composeExtensions/anonymousQueryLink
данные.Для сценариев, не относящихся к проверке подлинности: необходимо отправить ответ с
type
result
карточкой как и . Используйте следующий шаблон:{ "composeExtension": { "type": "result", "attachmentLayout": "list", "attachments": [ { "contentType": "application/vnd.microsoft.teams.card.o365connector", "content": { "sections": [ { "activityTitle": "[85069]: Create a cool app", "activityImage": "https://placekitten.com/200/200" }, { "title": "Details", "facts": [ { "name": "Assigned to:", "value": "[Larry Brown](mailto:larryb@example.com)" }, { "name": "State:", "value": "Active" } ] } ] } } ] } }
Для сценариев проверки подлинности: необходимо отправить ответ с
type
auth
как с необязательной карточкой предварительной проверки подлинности во вложениях. Используйте следующий шаблон:{ "composeExtension": { "type": "auth", "attachmentLayout": "list", "attachments": [ { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "actions": [], "body": [ { "type": "TextBlock", "size": "medium", "weight": "bolder", "text": "Zero-install test app" }, { "type": "TextBlock", "text": "Link your account with this app for a full experience", "wrap": true } ] } ] } }
Карточка предварительной проверки подлинности (только для проверки подлинности). Создайте предварительную версию карточки, чтобы развернуть ссылки для пользователей, у которых не установлено приложение. Вы можете создать предварительно шаблонную карточку или добавить соответствующие поля заполнителей для обновления пользователей. Пользователи могут узнать о приложении еще до его установки.
Вы можете создать настраиваемую карточку и добавить соответствующие поля. Пользователи могут заполнить необходимые сведения в соответствии с полями. На следующем рисунке показана настраиваемая предварительная версия карточки:
На следующем рисунке показана карточка предварительного просмотра по умолчанию:
Примечание.
После вставки ссылки в область создания сообщения Teams разворачивает ссылку в карточку и предлагает пользователю войти в приложение. Если пользователь не входит в приложение, ссылка не публикуется в виде карточки в чате.
Преимущества и ограничения:
Распаковка канала нулевой установки помогает предоставить пользователям расширенные возможности, например:
- Разворачивайте предварительные версии для ссылок, которыми пользователи обмениваются в Teams, даже до установки приложения.
- Создайте карточку приветствия для приложения, чтобы отобразить предварительный просмотр с полями заполнителей.
Как протестировать распаковку канала нулевой установки
При проверке распаковки ссылки нулевой установки не устанавливайте приложение как личное приложение. Вместо этого отправьте приложение в Teams.
Примечание.
Не запускайте тестовое приложение непосредственно из отладчика Microsoft Visual Studio.
Чтобы протестировать распаковку канала нулевой установки, выполните следующие действия.
Войдите в Центр администрирования Teams.
На панели слева выберите Приложения> TeamsУправление приложениями.
Выберите + Отправить новое приложение.
Выберите Добавить.
Выберите Открыть , чтобы отправить ZIP-файл для тестового приложения.
После успешной отправки приложения перейдите в разделПриложения>Teams>,созданные для вашей организации.
Запрос вызова можно протестировать
composeExtensions/anonymousQueryLink
, настроив точку останова в методе, который реализует запрос anonymousQueryLink в приложении.
Удаление кэша распаковки ссылок
Когда пользователь предоставляет общий доступ к ссылке на собрании, приложение Teams разворачивает ссылку на адаптивную карточку. Результат распаковки ссылки кэшируется в Teams в течение 30 минут. Вы можете обновить приложение, чтобы задать политику кэша и удалить кэш для приложения. Это действие помогает отображать разное содержимое в адаптивной карточке, когда ссылка приложения предоставляется в другом контексте в Teams.
Чтобы удалить кэш распаковки связи, обновите бот, указав в type
качестве setcachepolicy
в свойстве suggestedActions
. Teams не кэшируют результаты для ссылок приложения с помощью "type": "setCachePolicy"
.
Следующий пример полезных данных JSON для suggestedActions
свойства:
"suggestedActions": {
"actions": [
{
"type": "setCachePolicy",
"value": "{\"type\":\"no-cache\"}"
}
]
},
Пошаговые инструкции
Следуйте пошаговым инструкциям по развертыванию ссылок в Teams с помощью бота.
Пример кода
Название примера | Описание | .NET | Node.js | Манифест |
---|---|---|---|---|
Отмена распаковки канала установки. | В этом примере показано, как использовать расширение обмена сообщениями на основе поиска со страницей конфигурации. В этом примере также показано распаковка ссылки нулевой установки. | Просмотр | Просмотр | Просмотр |
См. также
Platform Docs