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

Важно!

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

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

Примечание.

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

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

Компьютер

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

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

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

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

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

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

Примечание.

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

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

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

   

   Примечание.

   Необходимо добавить приложение портала разработчика, если оно не добавлено в клиенте Teams.

   

2. Загрузите манифест вашего приложения.

   

3. Выберите Расширение для обмена сообщениями в разделе Функции приложения , а затем выберите Выбрать существующего бота или Создать новый бот.

   

   

4. Выберите Сохранить.

5. Выберите Добавить домен в разделе Ссылки предварительного просмотра и введите допустимый домен.

6. Нажмите Добавить. На изображении ниже даны пояснения по этому процессу.

   

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

Примечание.

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

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

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

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

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

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

Примечание.

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

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

• Адаптивная карточка
• Карточка эскиза
• Карточка главного имиджевого баннера
• Карта соединителя для Группы Microsoft 365

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

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

JSON

Ниже приводится пример 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 >>
       }
      ]
   }
}
      

C#

 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,
                    },       
                  },
              },
         }); 
   }

JavaScript

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 на веб-сайт, вы можете вручную проверка расширенный предварительный интерфейс развертывания, выполнив следующие действия.

1. Добавьте метаданные schema.org в формате JSON-LD на веб-сайт .

2. На веб-сайте проверка для поддерживаемого @type атрибута и скопируйте метаданные под тегом application/ld+jsonскрипта .

3. Откройте конструктор адаптивных карточек и создайте новый файл.

4. В редакторе примеров данных вставьте метаданные JSON с веб-сайта.

   

5. Проверьте шаблон микро-возможностей и добавьте его код в РЕДАКТОР ПОЛЕЗНЫХ ДАННЫХ КАРТОЧКИ.

   

   При необходимости добавьте новые атрибуты из шаблона в метаданные веб-сайта в редакторе примеров данных.

6. Чтобы предварительный просмотр интерфейса разворачивать адаптивную карточку, выберите Режим предварительного просмотра.

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

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

Распаковка ссылок нулевой установки позволяет развертывать предварительные версии общих ссылок даже до того, как пользователь обнаружит или установит приложение в Teams. Вы можете анонимно разворачивать карточки с новым invoke запросом или создавать предварительную версию адаптивной карточки для пользователей перед установкой или проверкой подлинности приложения.

На следующем рисунке представлен последовательный поток для включения и использования распаковки канала установки.

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

Чтобы подготовить приложение к распаковку ссылки нулевой установки, выполните следующие действия.

1. Присвойте свойству supportsAnonymizedPayloads значение true в схеме манифеста.

2. Настройте приложение для обработки нового 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"
   }
   

3. Ответ на полезные composeExtensions/anonymousQueryLink данные.

   1. Для сценариев, не относящихся к проверке подлинности: необходимо отправить ответ как 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"
                      }
                    ]
                  }
                 ]
               }
            }
          ]
        }
      }
      

   2. Для сценариев проверки подлинности: необходимо отправить ответ с 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
                  }
                 ]
               }
            ]
         }
      }
      

4. Предварительная проверка подлинности карта (только для проверки подлинности). Создайте предварительную версию карта, чтобы развернуть ссылки для пользователей, у которых не установлено приложение. Можно создать предварительно шаблонный карта или добавить соответствующие поля заполнителей для обновления пользователями. Пользователи могут узнать о приложении еще до его установки.

   Вы можете создать настраиваемую карта и добавить соответствующие поля. Пользователи могут заполнить необходимые сведения в соответствии с полями. На следующем рисунке показан настраиваемый предварительный просмотр карта:

   

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

   

   Примечание.

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

5. Преимущества и ограничения:

   Преимущества

   Распаковка канала нулевой установки помогает предоставить пользователям расширенные возможности, например:

   • Разворачивайте предварительные версии для ссылок, которыми пользователи обмениваются в Teams, даже до установки приложения.
   • Создайте карта приветствия для приложения, чтобы отобразить предварительный просмотр с полями заполнителей.

   Ограничения

   Ниже приведены ограничения.

   • Бот может отправить ответ только в виде result или auth в качестве значения свойства type в ответ на composeExtensions/anonymousQueryLink запрос вызова. Пользователь может записывать в журнал ошибку для всех других типов ответов, таких как silentAuth и config.

   • Бот не может отправить адаптивные карточки с универсальными действиями в ответ на composeExtensions/anonymousQueryLink запрос вызова в результате или в качестве карта предварительной проверки подлинности в авторизации.

   • Если бот выбирает отправить "type": "auth" обратно свойство с предварительной проверкой подлинности карта, Teams удаляет все кнопки действий из карта и добавляет кнопку действия входа, чтобы пользователи прошли проверку подлинности в вашем приложении.

---

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

При проверке распаковки ссылки нулевой установки не устанавливайте приложение как личное приложение. Вместо этого отправьте приложение в Teams.

Примечание.

Не запускайте тестовое приложение непосредственно из отладчика Microsoft Visual Studio.

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

1. Войдите в Центр администрирования Teams.

2. На панели слева выберите Приложения> TeamsУправление приложениями.

   

3. Выберите + Отправить новое приложение.

   

4. Выберите Добавить.

5. Выберите Открыть , чтобы отправить ZIP-файл для тестового приложения.

6. После успешной отправки приложения перейдите в разделПриложения>Teams>,созданные для вашей организации.

   

7. Запрос вызова можно протестировать 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	Манифест
Отмена распаковки канала установки.	В этом примере показано, как использовать расширение обмена сообщениями на основе поиска со страницей конфигурации. В этом примере также показано распаковка ссылки нулевой установки.	Просмотр	Просмотр	Просмотр

См. также

• Расширения для сообщений
• Адаптивные карточки
• Распаковка ссылок на вкладки и представление этапов
• Обработчики действий ботов