取得存取權杖

8 分鐘

當您取得存取權杖時，應用程式一律必須內嵌 Power BI 內容，以及取得 Azure AD 權杖。當您使用「針對您的客戶」案例時，應用程式會使用 Azure AD 權杖來產生內嵌權杖。

具體來說：

「針對您的組織」案例的存取權杖是 Azure AD 權杖，其中包含您的應用程式用來識別授與權限的宣告。
「針對您的客戶」案例的存取權杖是內嵌權杖，其中表示有關 Power BI 內容的事實，以及您的應用程式存取這些權杖的方式。您的應用程式會使用 Power BI REST API 作業來產生內嵌權杖，其中需要 Azure AD 權杖。

取得 Azure AD 權杖

使用 Microsoft 驗證程式庫 (MSAL) 來開發透過 Microsoft 身分識別平台取得 Azure AD 權杖的應用程式邏輯。 MSAL 支援不同的應用程式架構和平台，包括 .NET、JavaScript、JAVA、Python、Android 和 iOS。

提示

開發 ASP.NET Core Web 應用程式時，建議使用 Microsoft 身分識別 Web 驗證程式庫。此程式庫是一組稱為 Microsoft.Identity.Web 的套件。您可以從 NuGet 或 Visual Studio 加以安裝。

共有不同的技術，可以使用 MSAL 來取得 Azure AD 權杖。有些方法需要使用者透過網頁瀏覽器進行互動，而其他方法則不需要使用者互動。一般而言，您選擇取得 Azure AD 令牌的方法取決於應用程式是公用用戶端應用程式 (，例如桌面應用程式或行動應用程式) 或機密用戶端應用程式 (，例如 Web 應用程式) 。內嵌案例也會影響您的選擇。

這不是本單元用來描述取得 Azure AD 令牌的技術。如需詳細資訊，請參閱使用 Microsoft 驗證程式庫 (MSAL) 取得與快取權杖。

提示

當內嵌設定工具範例應用程式符合您的應用程式需求時，請考慮複製範例程式碼以取得 Azure AD 權杖。

若要允許您的應用程式取得 Azure AD 權杖，其組態檔應包含下列設定：

TenantId - 僅對服務主體為必要項。其是您的 Azure AD TenantID。
ClientId - 必要。其是您的 Azure AD 應用程式 ApplicationID (ClientID)。
ClientSecret 或 ClientCertificate - 僅對服務主體為必要項。
PbiUsername - 僅對主要使用者帳戶為必要項。
PbiPassword - 僅對主要使用者帳戶為必要項。

重要

無論使用憑證、用戶端密碼或主要使用者帳號憑證，您都必須採取步驟來保護其免於未經授權的存取和使用。我們建議使用 Azure Key Vault，以保護雲端中的密碼編譯金鑰、憑證和秘密。

取得內嵌權杖

使用 Microsoft Power BI REST API 的 GenerateTokenRequestV2 作業來要求內嵌權杖。還有其他相關作業可針對其他 Power BI 內容類型產生內嵌權杖。所有 API 作業都需要 Azure AD 權杖。

提示

開發 .NET 應用程式時，建議安裝 Microsoft.PowerBI.Api 套件。您可以從 NuGet 或 Visual Studio 加以安裝。

請考量下列程式碼，示範如何產生內嵌權杖。該權杖包含工作區中所有報表和資料集的宣告，並允許應用程式使用者建立或編輯報表。具體來說，其會執行下列動作：

連線至 Power BI。
宣告名為 reportTokenRequests 的變數，以儲存報表令牌要求。
列舉工作區中的所有報表，建立 EmbeddedReport 物件的清單 (使用協助程式類別)。每個物件都會描述報表的識別碼、名稱和內嵌 URL。應用程式需要報表標識元才能產生令牌。您必須將名稱呈現給功能表中的使用者，而且需要內嵌URL才能內嵌報表。此程式碼會將允許報表編輯的報表權杖要求新增至 reportTokenRequests 變數。
宣告名為 datasetTokenRequests 的變數，以儲存資料集權杖要求。
列舉工作區中的所有資料集，建立 EmbeddedDataset 物件的清單 (使用協助程式類別)。每個物件都會描述資料集的識別碼、名稱和內嵌 URL。應用程式需要資料集的識別碼才能產生權杖。可能需要名稱才能將它呈現給功能表中的使用者，而且需要內嵌 URL 才能內嵌數據集。程式碼會將資料集權杖要求新增至 datasetTokenRequests 變數。
產生工作區權杖要求 (當使用者建立報表時必要)，其會新增至 workspaceRequests 變數。
使用 GenerateTokenRequestV2 方法將報表權杖要求、資料集權杖要求和工作區權杖要求組合在一起。
使用 GenerateTokenAsync 來產生內嵌權杖。
將內嵌權杖儲存在字串變數中。

// Connect to Power BI
var client = GetPowerBiClient();

// Get reports in the workspace
var reports = (await client.Reports.GetReportsInGroupAsync(_workspaceId)).Value;

var reportList = new List<EmbeddedReport>();
var reportTokenRequests = new List<GenerateTokenRequestV2Report>();

foreach (var report in reports)
{
    reportList.Add(new EmbeddedReport
    {
        Id = report.Id.ToString(),
        Name = report.Name,
        EmbedUrl = report.EmbedUrl
    });

    reportTokenRequests.Add(new GenerateTokenRequestV2Report(report.Id, allowEdit: true));
}

// Get datasets in the workspace
var datasets = (await client.Datasets.GetDatasetsInGroupAsync(_workspaceId)).Value;

var datasetList = new List<EmbeddedDataset>();
var datasetTokenRequests = new List<GenerateTokenRequestV2Dataset>();

foreach (var dataset in datasets)
{
    datasetList.Add(new EmbeddedDataset
    {
        Id = dataset.Id.ToString(),
        Name = dataset.Name,
        EmbedUrl = dataset.QnaEmbedURL
    });

    datasetTokenRequests.Add(new GenerateTokenRequestV2Dataset(dataset.Id));
}

// Generate token request for the workspace
var workspaceRequests = new GenerateTokenRequestV2TargetWorkspace[] {
    new GenerateTokenRequestV2TargetWorkspace(_workspaceId)
};

// Bundle token requests for reports, datasets, and the workspace
var tokenRequest = new GenerateTokenRequestV2(
    reports: reportTokenRequests,
    datasets: datasetTokenRequests,
    targetWorkspaces: workspaceRequests
);

// Generate the embed token
string embedToken = (await client.EmbedToken.GenerateTokenAsync(tokenRequest)).Token;

應用程式應將 embedToken 變數值輸出至內嵌 HTML 頁面。用戶端邏輯接著可以使用內嵌權杖，將內容內嵌在 div 元素中。

注意

若要了解如何內嵌 Power BI 內容，請逐步完成內嵌 Power BI 內容課程模組。

若要允許您的應用程式取得內嵌權杖，其組態檔應包含可內嵌內容的詳細資料。其可以包含特定的 ReportID 和 DatasetID，或是更常見的資料，像是包含可內嵌內容的工作區 GroupID。

如需詳細資訊，請參閱內嵌權杖 - 產生權杖。

重新整理存取權杖

存取權杖具有到期時間。產生權杖後，應用程式使用者就會具有有限的時間，與使用權杖的 Power BI 內容互動。為了提供應用程式使用者持續體驗，您的應用程式應在到期之前，使用 Power BI 用戶端 API 來重新整理存取權杖。

注意

若要了解用戶端 API，請逐步完成將內容與 Power BI 用戶端 API 整合課程模組。

如需詳細資訊，請參閱重新整理存取令牌。

探索其他資源

若要深入瞭解，watch Azure AD 安全性的 Power BI 開發人員指南影片系列。本系列包含六部影片，涵蓋深入理論。 Ted Pattison 所屬 Microsoft 的 Power BI Customer Advisory Team (CAT) 成員，並是製作本部影片系列的人員。

繼續

取得存取權杖

取得 Azure AD 權杖

取得內嵌權杖

重新整理存取權杖

探索其他資源

意見反應