將對話方塊新增至 [調適型卡片] 範本 (預覽)

您可以新增強制回應對話方塊,以增強 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 驗證,請使用下列其中一種方法:

  • 使用 Microsoft 做為身分識別提供者,設定 Entra ID、OAuth 2.0 或 API 金鑰型驗證。
  • 使用其他身份提供商並在 Entra ID 中註冊您的應用程序。

設定 SSO 型驗證

設定單一登入 (SSO) ,以允許使用者存取 API,而不需要多次登入。

若要啟用 SSO:

  1. 更新 Microsoft Entra ID 應用程式。
    • 設定應用程式識別碼 URI。
    • 設定範圍和同意設定。
    • 預先授權信任的用戶端應用程式,以避免重複的同意提示。
  2. 實作權杖擷取與驗證邏輯。
    • 使用 TeamsJS 程式庫中的方法 getAuthToken() 來擷取存取權杖。
    • 在 Authorization 標頭中將權杖傳送至您的伺服器。
    • 在伺服器端驗證權杖。
  3. 更新應用程式資訊清單。
    • 將 webApplicationInfo 屬性新增至應用程式資訊清單以啟用 SSO。
    • 將對話方塊內容的網域新增至應用程式資訊清單的 'validDomains 屬性。

更新 Microsoft Entra ID 應用程式

若要設定範圍並授權信任的用戶端應用程式,請更新您的 Microsoft Entra ID 應用程式,如下所示:

  1. 將 API URI 新增至應用程式資訊清單的 identifierUriis 屬性。 針對 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 的範圍,以及誰可以同意範圍。 在 Microsoft Entra 系統管理中心 [此 API 定義的範圍] 區段中,選取 [+ 新增範圍]。

    要新增範圍之欄位的螢幕擷取畫面

    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 屬性以啟用 SSO。 這有助於客服專員使用者順暢地存取您的客服專員。 下表列出 webApplicationInfo 屬性的屬性。

屬性 描述
id 輸入您在 Microsoft Entra ID 中建立的應用程式識別碼 (GUID) 。
資源 輸入您應用程式的子網域 URI,以及您在建立範圍時在 Microsoft Entra ID 中建立的應用程式識別碼 URI。
"webApplicationInfo": {
  "id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
  "resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
 }

在應用程式資訊清單的 validDomains 屬性對話方塊中,指定您想要轉譯之 URL 的網域,如下列範例所示。

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

OAuth 2.0 安裝程式 (預覽)

對於搭配使用 OAuth 2.0 搭配 Microsoft Entra ID 或其他身分識別提供者的代理程式,請使用 authentication.authenticate() TeamsJS 程式庫中的函數來啟動驗證流程。

若要為 API 外掛程式對話方塊啟用 OAuth 2.0 授權:

  • 將應用程式設定為使用 Microsoft Entra ID 做為身分識別提供者。
  • 變更程式碼以啟動驗證流程並處理權杖。

將應用程式設定為使用 Microsoft Entra ID 做為身分識別提供者

若要設定您的應用程式以使用 Microsoft Entra ID:

  • 在 Azure 入口網站中,移至您的應用程式註冊。
  • 在 [驗證] 底下的 [ 重新導向 URI ] 區段中,將重新導向 URL 新增至您的驗證端點。 針對重新導向 URL 使用下列格式: https://<hostname>/auth/simple-start。

起始驗證流程並處理權杖

大部分的識別提供者不允許將內容放置在 iframe 中。 這表示您需要一個頁面來託管 Copilot 在快顯視窗內顯示的身分識別提供者。 使用 TeamsJS 文件庫的函數,在 authentication.authenticate() 選取 [調適型卡片] 按鈕時啟動此頁面。

注意

您傳遞至 authenticate() 的 URL 是驗證流程的起始頁面。 它應該符合您在 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()。 如果登入成功,使用者就可以存取服務資源。