Развертывание ссылки

Статья
02/14/2024

Важно!

Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел Расширения сообщений — пакет SDK версии 3 в папке Resources документации.

В этом документе описывается, как добавить раскройку ссылок в манифест приложения с помощью портала разработчика и вручную. При распаковке ссылок приложение может зарегистрироваться для получения действия вызова, когда URL-адреса с определенным доменом вставляются в область создания сообщений. invoke содержит полный URL-адрес, вставленный в область создания сообщения, и вы можете показать карточку с дополнительной информацией или действиями, которую пользователь может развернуть. Это работает аналогично команде поиска, только в качестве условия поиска используется URL-адрес. Теперь можно добавить раскройку ссылок в Microsoft Teams без установки приложения.

Примечание.

Результат развертывания ссылки кэшируется в течение 30 минут.
Распаковка ссылок поддерживает адаптивные карточки версии 1.3 и более ранних версий.
Команды расширения обмена сообщениями не требуются для распаковки связи. Однако в манифесте должна быть по крайней мере одна команда, так как она является обязательным свойством в расширениях обмена сообщениями. Дополнительные сведения см. в разделе Создание расширений.
Для мобильного клиента распаковка ссылок поддерживается только для ссылок, не требующих проверки подлинности.

На следующем рисунке показан пример распаковки ссылок в классических и мобильных клиентах Teams:

Компьютер
Мобильные устройства

Когда ссылка вставляется в область сообщения Создания Teams, ссылка разворачивается в карта с сведениями о рабочем элементе.

Снимок экрана: пример распаковки ссылок для ссылок Azure Dev Ops, вставленных в область создания сообщений teams.

Дополнительные сведения о раскрое ссылок см. в следующем видео:

Добавление развертывания ссылок в манифест приложения

Чтобы добавить развертывание ссылок в манифест приложения, добавьте новый массив messageHandlers в раздел composeExtensions манифеста приложения JSON. Массив можно добавить с помощью портала разработчика или вручную. Списки доменов могут содержать подстановочные знаки, например *.example.com , которые соответствуют только одному сегменту домена. Если необходимо сопоставить a.b.example.com, используйте *.*.example.com.

Примечание.

Убедитесь, что вы не добавляете домены, которые не являются вашим контролем, напрямую или с помощью подстановочных знаков. Например, yourapp.onmicrosoft.com является допустимым, но *.onmicrosoft.com недопустимым. Домены верхнего уровня запрещены, например *.com, *.org.

Добавление распаковки ссылок с помощью портала разработчика

Откройте портал разработчика в клиенте Microsoft Teams и выберите вкладку Приложения .

Примечание.

Необходимо добавить приложение портала разработчика, если оно не добавлено в клиенте Teams.
Загрузите манифест вашего приложения.
Выберите Расширение для обмена сообщениями в разделе Функции приложения , а затем выберите Выбрать существующего бота или Создать новый бот.
Нажмите кнопку Сохранить.
Выберите Добавить домен в разделе Ссылки предварительного просмотра и введите допустимый домен.
Нажмите Добавить. На изображении ниже даны пояснения по этому процессу.

Добавление развертывания ссылок вручную

Примечание.

Если проверка подлинности добавлена через Microsoft Entra ID, разворачивайте ссылки в Teams с помощью бота.

Во-первых, необходимо добавить массив в messageHandlers манифест приложения и включить расширение сообщений для взаимодействия со ссылками. В следующем примере объясняется, как вручную добавить развертывание ссылок.

...
{
  "composeExtensions": [
    {
      "botId": "abc123456-ab12-ab12-ab12-abcdef123456",
      "messageHandlers": [
        {
          "type": "link",
          "value": {
            "domains": [
              "*.trackeddomain.com"
            ]
          }
        }
      ]
    }
  ]
}
...

Полный пример манифеста см. по ссылке на манифест.

Обработка вызова `composeExtensions/queryLink`

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

Примечание.

Ответ бота должен содержать preview свойство .

Поддерживаемые типы карточек представлены ниже.

Дополнительные сведения см. в статье Вызов типа действия.

Следующий код является примером 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 >>
       }
      ]
   }
}

 protected override Task<MessagingExtensionResponse> OnTeamsAppBasedLinkQueryAsync(ITurnContext<IInvokeActivity> turnContext, AppBasedLinkQuery query, CancellationToken cancellationToken)
  {
     AdaptiveCard adaptiveCard = new AdaptiveCard(new AdaptiveSchemaVersion(1, 3));
     adaptiveCard.Body.Add(new AdaptiveTextBlock()
       {
           Text = "Adaptive Card",
           Size = AdaptiveTextSize.ExtraLarge
       });
         adaptiveCard.Body.Add(new AdaptiveImage()
         {
           Url = new Uri("https://raw.githubusercontent.com/microsoft/botframework-sdk/master/icon.png")
         });
         var attachments = new MessagingExtensionAttachment()
         {
            Content = adaptiveCard,
            ContentType = AdaptiveCard.ContentType
         };
         return Task.FromResult(new MessagingExtensionResponse
         {
           ComposeExtension = new MessagingExtensionResult
             {
               AttachmentLayout = "list",
               Type = "result",
               Attachments = new List<MessagingExtensionAttachment>
                 {
                    new MessagingExtensionAttachment
                    {
                      Content = adaptiveCard,
                      ContentType = AdaptiveCard.ContentType,
                      Preview = attachments,
                    },       
                  },
              },
         }); 
   }


handleTeamsAppBasedLinkQuery(context, query) {
   const card = CardFactory.adaptiveCard({
   "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
   "type": "AdaptiveCard",
   "version": "1.3"
   });
const attachment = CardFactory.adaptiveCard(card);
attachment.preview = {
   content: {
     title: "Thumbnail Card",
     text: query.url,
     images: [
       {
          url: "https://raw.githubusercontent.com/microsoft/botframework-sdk/master/icon.png",
       },
     ],
   },
contentType: "application/vnd.microsoft.card.thumbnail",
}

Микро-возможности для ссылок на веб-сайт

Самый распространенный способ предоставления общего доступа к содержимому в 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 данные.

Для сценариев, не относящихся к проверке подлинности: необходимо отправить ответ как typeresult и карта. Используйте следующий шаблон:

{
  "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"
                }
              ]
            }
           ]
         }
      }
    ]
  }
}

Для сценариев проверки подлинности: необходимо отправить ответ с typeauth как с необязательным карта предварительной проверки подлинности во вложениях. Используйте следующий шаблон:

{
   "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, даже до установки приложения.
- Создайте карта приветствия для приложения, чтобы отобразить предварительный просмотр с полями заполнителей.
Ниже приведены ограничения.
- Бот может отправить ответ только в виде result или auth в качестве значения свойства type в ответ на composeExtensions/anonymousQueryLink запрос вызова. Пользователь может записывать в журнал ошибку для всех других типов ответов, таких как silentAuth и config.
- Бот не может отправить адаптивные карточки с универсальными действиями в ответ на composeExtensions/anonymousQueryLink запрос вызова в результате или в качестве карта предварительной проверки подлинности в авторизации.
- Если бот выбирает отправить "type": "auth" обратно свойство с предварительной проверкой подлинности карта, 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	Манифест
Отмена распаковки канала установки.	В этом примере показано, как использовать расширение обмена сообщениями на основе Поиск со страницей конфигурации. В этом примере также показано распаковка ссылки нулевой установки.	Просмотр	Просмотр	Просмотр

Развертывание ссылки

Добавление развертывания ссылок в манифест приложения

Добавление распаковки ссылок с помощью портала разработчика

Добавление развертывания ссылок вручную

Обработка вызова `composeExtensions/queryLink`

Микро-возможности для ссылок на веб-сайт

Включение полнофункционированных предварительных просмотров ссылок

Нулевая установка для распаковки ссылок

Включение распаковки канала нулевой установки

Как протестировать распаковку канала нулевой установки

Удаление кэша распаковки ссылок

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

Пример кода

См. также

Обратная связь

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

Развертывание ссылки

Добавление развертывания ссылок в манифест приложения

Добавление распаковки ссылок с помощью портала разработчика

Добавление развертывания ссылок вручную

Обработка вызова composeExtensions/queryLink

Микро-возможности для ссылок на веб-сайт

Включение полнофункционированных предварительных просмотров ссылок

Нулевая установка для распаковки ссылок

Включение распаковки канала нулевой установки

Как протестировать распаковку канала нулевой установки

Удаление кэша распаковки ссылок

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

Пример кода

См. также

Обратная связь

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

Обработка вызова `composeExtensions/queryLink`