認證 API 讓視覺化裝置能取得 Microsoft Entra ID（前稱 Azure AD）存取權杖，方便登入用戶進行單一登入認證。
Power BI 管理員可以透過 全域交換器啟用或停用 API。 預設設定會封鎖（停用）該 API。
此 API 僅適用於 AppSource 視覺化，不適用於私有視覺化。 正在開發的視覺化可以在發佈前先在除錯模式中測試。
支援的環境
支援下列環境：
- 網路
- 桌面
- RS 桌面
- 手機
不支援環境
以下環境尚未支援：
- RS 服務
- 嵌入式分析
- Teams
如何使用認證 API
在 capabilities.json 檔案中，為每個支援的雲端加上「AADAuthentication」權限，並附上 Microsoft Entra ID 註冊的應用程式 URI。 Fabric 會根據目前雲端所設定的受眾生成一個令牌，並將其傳送到視圖。
視覺系統接著可利用該令牌對相應受眾進行身份驗證，用於其後端服務的身份驗證。
"privileges": [
{
"name": "AADAuthentication",
"parameters": {
"COM": "https://contoso.com",
"CN": "https://contoso.cn"
}
}
]
在 pbiviz.json 檔案中，將 API 版本設定為 5.9.1 或更高：
新公開的 AcquireAADTokenService 包含兩種方法：
acquireAADToken：返回類型為
AcquireAADTokenResult的 visual 的認證憑證有效載荷，如果無法擷取則返回 null。/** * Enum representing the various clouds supported by the Authentication API. */ export const enum CloudName { COM = "COM", // Commercial Cloud CN = "CN", // China Cloud GCC = "GCC", // US Government Community Cloud GCCHIGH = "GCCHIGH", // US Government Community Cloud High DOD = "DOD", // US Department of Defense Cloud } /** * Interface representing information about the user associated with the token. */ export interface AcquireAADTokenUserInfo { userId?: string; // Unique identifier for the user tenantId?: string; // Unique identifier for the tenant } /** * Interface representing information about the fabric environment. */ export interface AcquireAADTokenFabricInfo { cloudName?: CloudName; // Name of the cloud environment } /** * Interface representing the result of acquiring a Microsoft Entra ID token. */ export interface AcquireAADTokenResult { accessToken?: string; // Access token issued by Microsoft Entra ID expiresOn?: number; // Expiration time of the access token userInfo?: AcquireAADTokenUserInfo; // Information about the user associated with the token fabricInfo?: AcquireAADTokenFabricInfo; // Information about the fabric environment }acquireAADTokenstatus：回傳與取得該代幣相關的以下特權狀態之一。
- 允許：在當前環境中，該特權是被允許的。
- NotDeclared：視覺功能部分缺少權限宣告。
- NotSupported：目前環境下不支持此特權。
- DisabledByAdmin：Fabric 管理員拒絕使用權限。
以下範例程式碼示範如何利用 API 取得 Microsoft Entra ID 令牌：
// Step 1: Check the status of AAD token acquisition
const acquireTokenStatus = await this.acquireAADTokenService.acquireAADTokenstatus();
// Step 2: Verify if acquiring the token is allowed
if (acquireTokenStatus === PrivilegeStatus.Allowed) {
// Step 3: Acquire the Microsoft Entra ID token
const acquireAADTokenResult: AcquireAADTokenResult = await this.acquireAADTokenService.acquireAADToken();
// Step 4: Confirm successful acquisition of the access token
if (acquireAADTokenResult.accessToken) {
// Step 5: Call your backend API with the obtained token
}
}
// Step 6: Handle unsuccessful AAD token acquisition
考慮事項與限制條件
若符合以下任一條件，代幣取得將被阻止：
租戶開關是關閉的。
使用者在桌面應用程式仍未登入。
ISV 並沒有預先授權 Power BI 應用程式。
AADAuthentication 驗證參數的格式無效。
這個視覺化並非 公開認可 ，也不是除錯視覺化。
視覺化的後端服務被設定為視覺化的受眾，但在消費者租戶中使用該視覺化時，未獲得對於 Graph API 的適當同意。 欲了解更多關於同意的資訊，請參閱 租戶管理員同意。