您可以新增強制回應對話方塊,以增強 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結構描述。
下列範例顯示 的 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:
- 更新 Microsoft Entra ID 應用程式。
- 設定應用程式識別碼 URI。
- 設定範圍和同意設定。
- 預先授權信任的用戶端應用程式,以避免重複的同意提示。
- 實作權杖擷取與驗證邏輯。
- 使用 TeamsJS 程式庫中的方法
getAuthToken()來擷取存取權杖。 - 在 Authorization 標頭中將權杖傳送至您的伺服器。
- 在伺服器端驗證權杖。
- 使用 TeamsJS 程式庫中的方法
- 更新應用程式資訊清單。
- 將 webApplicationInfo 屬性新增至應用程式資訊清單以啟用 SSO。
- 將對話方塊內容的網域新增至應用程式資訊清單的 'validDomains 屬性。
更新 Microsoft Entra ID 應用程式
若要設定範圍並授權信任的用戶端應用程式,請更新您的 Microsoft Entra ID 應用程式,如下所示:
將 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" ],定義 API 的範圍,以及誰可以同意範圍。 在 Microsoft Entra 系統管理中心 [此 API 定義的範圍] 區段中,選取 [+ 新增範圍]。
- 輸入範圍名稱。 此為必要欄位。
- 選取可同意此範圍的使用者。 預設選項為 [僅限系統管理員]。
- 輸入管理員同意顯示名稱。 此為必要欄位。
- 輸入系統管理員同意的描述。 此為必要欄位。
- 輸入 使用者同意顯示名稱。
- 輸入使用者同意描述的描述。
- 在 [狀態 ] 欄位中,針對狀態選取 [已啟用 ] 選項。
- 選取 [新增範圍]。
為您要預先授權的應用程式建立授權用戶端識別碼。 這可讓應用程式使用者存取您) 設定的應用程式範圍 (權限,而不需要額外同意。 因為應用程式使用者沒有機會拒絕同意,所以只預先授權您信任的用戶端應用程式。
在 Microsoft Entra 系統管理中心 [授權的用戶端應用程式] 區段中,選取 [+ 新增用戶端應用程式]。
輸入您要授權之應用程式的 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()。 如果登入成功,使用者就可以存取服務資源。