Добавление диалогового окна в шаблоны адаптивных карточек (предварительная версия)

Вы можете улучшить ответы адаптивных карточек в декларативных агентах для Microsoft 365 Copilot, добавив модальные диалоговые окна. Эти всплывающие диалоговые окна могут содержать пользовательские HTML / JavaScript или отображать мини-приложения на основе iframe, например веб-страницы, видео YouTube или контент Microsoft Stream, в сфокусированном интерактивном интерфейсе.

В этой статье описывается, как использовать Action.OpenUrlDialog (доступно в схеме адаптивной карточки версии 1.5) для запуска модальных диалоговых окон из шаблонов адаптивных карточек и как настроить проверку подлинности пользователей.

Примечание

Сейчас OpenUrlDialog это действие находится в предварительном просмотре.

Необходимые условия

Чтобы использовать Action.OpenUrlDialog, вам потребуются следующие предварительные условия:

  • Схема адаптивной карточки версии 1.5
  • Манифест подключаемого модуля API версии 2.3
  • Библиотека Microsoft TeamsJS (для сценариев проверки подлинности)

Определение шаблона адаптивной карточки

Чтобы воспользоваться модальным действием диалогового окна:

В следующем примере показана схема для Action.OpenUrlDialog.

"actions": [
     {
         "type": "Action.OpenUrlDialog",
         "title": "OpenDialogWithDimension",
         "url": "${url}",
         "dialogHeight": "large",
         "dialogWidth": "600px",
         "dialogTitle": "task module"
     }
    ]

Справочные сведения о схеме см. в Action.OpenUrlDialog.

Настройка размера диалогового окна

Используйте свойства dialogHeight и dialogWidth для установки высоты и ширины диалогового окна. Эти значения динамически корректируются в зависимости от разрешения экрана пользователя и размера окна.

Вы можете указать:

  • Предопределенные размеры - small, medium, или large.
  • Пользовательские значения пикселей, например, 400px, 600px.

Совет

Для точного управления используйте значения в пикселях. Предопределенные размеры считаются относительными к доступному пространству на экране.

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

Изображение диалогового окна для пользователей для ввода сведений о клиенте

Настройка проверки подлинности

Чтобы обеспечить безопасный доступ к API из диалогового окна, настройте проверку подлинности с помощью одного из следующих методов:

  • Microsoft Entra ID,
  • OAuth 2.0 (предварительная версия)

Настройка Microsoft Entra ID

Чтобы использовать аутентификацию Entra ID для аутентификации API, используйте один из следующих подходов:

  • Настройте проверку подлинности на основе идентификаторов Entra, OAuth 2.0 или API с помощью Майкрософт в качестве поставщика удостоверений.
  • Используйте другого поставщика удостоверений и зарегистрируйте приложение в Entra ID.

Настройка проверки подлинности на основе единого входа

Настройте единый вход (SSO), чтобы пользователи могли получать доступ к API без необходимости выполнять вход несколько раз.

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

  1. Обновите приложение Microsoft Entra ID.
    • Настройте URI идентификатора приложения.
    • Настройка областей и параметров согласия.
    • Выполните предварительную авторизацию доверенных клиентских приложений, чтобы избежать повторных запросов на согласие.
  2. Реализация логики получения и проверки маркеров.
    • Используйте getAuthToken() метод из библиотеки TeamsJS, чтобы получить маркер доступа.
    • Отправьте маркер на свой сервер в заголовке Authorization.
    • Проверьте маркер на стороне сервера.
  3. Обновите манифест приложения.
    • Добавьте свойство webApplicationInfo в манифест приложения, чтобы включить единый вход.
    • Добавьте домен содержимого диалогового окна в свойство 'validDomains манифеста приложения.

Обновите приложение Microsoft Entra ID

Чтобы настроить области и авторизовать доверенные клиентские приложения, обновите приложение Microsoft Entra ID следующим образом:

  1. Добавьте URI API к свойству identifierUris манифеста приложения. Используйте следующий формат URI: 'api://fully-qualified-domain-name.com/{AppID}, как показано в следующем примере.

    "identifierUris": [
    "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db"
    ],
    
  2. Определите область для API и пользователей, которые могут дать согласие на использование этой области. В разделе "Области", определенные этим API, Центра администрирования Microsoft Entra выберите + Добавить область.

    Снимок экрана: поля для добавления области

    1. Введите имя области. Это поле обязательно к заполнению.
    2. Выберите пользователя, который может предоставить согласие для этой области. По умолчанию выбран параметр "Только для администраторов".
    3. Введите отображаемое имя согласия администратора. Это поле обязательно к заполнению.
    4. Введите описание для согласия администратора. Это поле обязательно к заполнению.
    5. Введите отображаемое имя согласия пользователя.
    6. Введите описание для описания согласия пользователя.
    7. В поле "Штат " выберите параметр "Включено " для состояния.
    8. Нажмите кнопку "Добавить область".
  3. Создайте авторизованные идентификаторы клиентов для приложений, которые требуется предварительно авторизовать. Это позволяет пользователю приложения получать доступ к настроенным вами областям приложений (разрешениям) без необходимости дополнительного согласия. Так как пользователи приложений не будут иметь возможности отклонить согласие, предварительно авторизуйте только те клиентские приложения, которым вы доверяете.

    1. В разделе "Авторизованное клиентское приложение" Центра администрирования Microsoft Entra выберите + Добавить клиентское приложение.

      Снимок экрана с выделенной кнопкой

    2. Введите идентификатор клиента Microsoft 365 для приложений, которые необходимо авторизовать.

Реализация логики получения и проверки маркеров

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

Чтобы текущий пользователь приложения мог получить доступ к приложению, код на стороне клиента должен позвонить в Teams, чтобы получить маркер доступа. Обновите код на стороне клиента, чтобы использовать getAuthToken() его для запуска проверки данных, как показано в следующем примере.

// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
     return new Promise((resolve, reject) => {
         display("1. Get auth token from Microsoft Teams");

         microsoftTeams.authentication.getAuthToken().then((result) => {
             display(result);
             resolve(result);
         }).catch((error) => {
             reject("Error getting token: " + error);
         });
     });
 }

Когда Teams получает маркер доступа, он кэширует маркер для повторного использования при необходимости. Маркер используется при getAuthToken() вызове без необходимости повторного вызова Microsoft Entra ID до истечения срока действия маркера.

При звонке getAuthToken() и для разрешений на уровне пользователя требуется согласие пользователя, вошедший в систему пользователь видит диалоговое окно Microsoft Entra, и ему необходимо дать первоначальное согласие один раз.

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

  • Если администратор предоставил согласие от имени клиента, пользователям приложения не нужно запрашивать согласие. Это означает, что пользователи приложения не видят диалогового окна согласия и могут беспрепятственно получить доступ к приложению.
  • Если ваше приложение Microsoft Entra зарегистрировано в том же клиенте, у которого вы запрашиваете проверку подлинности в Teams, у пользователя приложения нельзя попросить согласие, и он сразу же получит маркер доступа. Пользователи приложения дают согласие на эти разрешения только в том случае, если приложение Microsoft Entra зарегистрировано в другом клиенте.
  • Поскольку пользователи должны предоставить согласие на доступ к API, а согласие требуется только один раз для каждого пользователя, дополнительное согласие не требуется для диалоговых окон.

Обновите манифест приложения

Настройте свойство webApplicationInfo в файле манифеста приложения, чтобы включить единый вход. Это помогает пользователям агента беспрепятственно получать доступ к нему. В следующей таблице перечислены свойства свойства webApplicationInfo .

Свойство Описание
id Введите идентификатор приложения (GUID), созданный в Microsoft Entra ID.
ресурс Введите URI поддомена вашего приложения и URI идентификатора приложения, созданные в Microsoft Entra ID при создании области.
"webApplicationInfo": {
  "id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
  "resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
 }

Укажите домен URL-адреса, который нужно отобразить, в диалоговом окне свойства validDomains манифеста приложения, как показано в следующем примере.

"validDomains": [
     "contoso.com",
     "mysite.someplace.com",
     "othersite.someplace.com"
 ]

Настройка OAuth 2.0 (предварительная версия)

Для агентов, использующих OAuth 2.0 с Microsoft Entra ID или другими поставщиками удостоверений, используйте authentication.authenticate() функцию в библиотеке TeamsJS для запуска потока проверки подлинности.

Включение авторизации OAuth 2.0 для подключаемого модуля API в диалоговых окнах:

  • Настройте приложение для использования Microsoft Entra ID в качестве поставщика удостоверений.
  • Внесите изменения в код, чтобы запустить поток проверки подлинности и обработать маркер.

Настройте приложение для использования Microsoft Entra ID в качестве поставщика удостоверений

Чтобы настроить приложение для использования Microsoft Entra ID:

  • На портале Azure перейдите к регистрации приложения.
  • В разделе " Проверка подлинности" в разделе "URI перенаправления " добавьте URL-адрес перенаправления в конечную точку проверки подлинности. Используйте следующий формат для URL перенаправления: https://<hostname>/auth/simple-start.

Инициация потока проверки подлинности и обработка маркера

Большинство поставщиков удостоверений не разрешают размещать содержимое в iframe. Это означает, что вам нужна страница для размещения поставщика удостоверений, который Copilot отображает во всплывающем окне. Используйте authentication.authenticate() функцию библиотеки TeamsJS для запуска этой страницы при нажатии кнопки "Адаптивная карточка".

Примечание

URL-адрес, на authenticate() который выполняется передача, является начальной страницей процесса проверки подлинности. Он должен совпадать с тем, что вы зарегистрировали на портале Azure. Поток проверки подлинности должен начинаться на странице в вашем домене. Не забудьте указать этот домен в свойстве validDomains в манифесте.

import { authentication } from "@microsoft/teams-js";

authentication.authenticate({
     url: window.location.origin + "/auth/simple-start",
     width: 600,
     height: 535
 })
.then((result) => {
     console.log("Login succeeded: " + result);
     let data = localStorage.getItem(result);
     localStorage.removeItem(result);
     let tokenResult = JSON.parse(data);
     showIdTokenAndClaims(tokenResult.idToken);
     getUserProfile(tokenResult.accessToken);
 })
.catch((reason) => {
     console.log("Login failed: " + reason);
     handleAuthError(reason);
 });

Всплывающая страница перенаправляет поставщика удостоверений, чтобы пользователь мог выполнить вход. Агент вызывает службу авторизации Microsoft Entra и передает сведения о пользователе и приложении, чтобы пользователь мог пройти проверку подлинности в Entra ID. Затем Entra ID вызывает страницу обратного вызова, которую вы указали.

app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
     let state = _guid(); // _guid() is a helper function in the sample
     localStorage.setItem("simple.state", state);
     localStorage.removeItem("simple.error");

     // Go to the Azure AD authorization endpoint
     let queryParams = {
         client_id: "{{appId}}",
         response_type: "id_token token",
         response_mode: "fragment",
         scope: "https://graph.microsoft.com/User.Read openid",
         redirect_uri: window.location.origin + "/auth/simple-end",
         nonce: _guid(),
         state: state,
         // The context object is populated by Teams; the loginHint attribute
         // is used as hinting information
         login_hint: context.user.loginHint,
     };

     let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
     window.location.assign(authorizeEndpoint);
 });

Определите успешность или неудачу запроса на проверку подлинности на основе сведений, возвращенных Entra ID, и вызовите либо authentication.notifySuccess() или .authentication.notifyFailure() Если вход выполнен успешно, пользователь получает доступ к ресурсам службы.