註冊 Azure AD 應用程式以內嵌 Power BI 內容Register an Azure AD app to embed Power BI content

了解如何在 Azure Active Directory (Azure AD) 內註冊應用程式,以用來內嵌 Power BI 內容。Learn how to register an application within Azure Active Directory (Azure AD) for use with embedding Power BI content.

您可以向 Azure AD 註冊應用程式,讓您的應用程式存取 Power BI REST API。You register your application with Azure AD to allow your application access to the Power BI REST APIs. 這可讓您建立應用程式的身分識別,並指定其對於 Power BI REST 資源的權限。This will allow you to establish an identity for your application and specify permissions to Power BI REST resources.

重要

註冊 Power BI 應用程式之前,您需要有 Azure Active Directory 租用戶和組織使用者Before you register a Power BI app you need an Azure Active Directory tenant and an organizational user. 如果您尚未以租用戶中的使用者來註冊 Power BI,則無法成功完成應用程式註冊。If you haven't signed up for Power BI with a user in your tenant, the app registration will not complete successfully.

有兩種方式可以註冊您的應用程式。There are two ways to register your application. 第一種方法是使用 Power BI 應用程式註冊工具;或者,您也可以在 Azure 入口網站直接註冊。The first is with the Power BI App Registration Tool or you can do it directly within the Azure portal. 由於 Power BI 應用程式註冊工具只需填寫幾個欄位,所以算是最簡簡單的途徑。The Power BI App Registration Tool is the easiest option since there are just a few fields to fill in. 如果您要變更應用程式,請使用 Azure 入口網站。If you want to make changes to your app, use the Azure portal.

使用 Power BI 應用程式註冊工具來註冊Register with the Power BI App Registration Tool

您必須在 Azure Active Directory 中註冊應用程式,才能建立應用程式的身分識別,以及指定對於 Power BI REST 資源的權限。You need to register your application in Azure Active Directory to establish an identity for your application and specify permissions to Power BI REST resources. 當您註冊應用程式時,例如主控台應用程式或網站,您會收到識別碼,應用程式會利用此識別碼,向要求權限的使用者表明自己的身分。When you register an application, such as a console app or a web site, you receive an identifier which is used by the application to identify themselves to the users that they are requesting permissions from.

以下是使用 Power BI 應用程式註冊工具來註冊應用程式的方法:Here's how to register your application with the Power BI App Registration Tool:

  1. 請前往 dev.powerbi.com/appsGo to dev.powerbi.com/apps.
  2. 選取 [使用您的現有帳戶登入]。Select Sign in with your existing account.
  3. 提供 [應用程式名稱]。Provide an App Name.
  4. [應用程式類型] 選擇取決於您使用的應用程式類型。The App type selection will depend on the type of application you are using.

    • 若是 Web 應用程式或 Web API,請使用 [伺服器端 Web 應用程式]。Use Server-side Web app for web apps or web APIs.
    • 若是在用戶端裝置上執行的應用程式,請使用 [原生應用程式]。Use Native app for apps that run on client devices. 如果您要內嵌客戶的內容,而不論實際應用程式是什麼,您也會選擇*原生應用程式。即使是 Web 應用程式亦然。You will also choose Native app if you are embedding content for your customers regardless of what the actual application is. Even for web applications.***
  5. 輸入 [重新導向 URL] 和 [首頁 URL] 的值。Enter a value for Redirect URL and Home Page URL. 任何有效的 URL 都可運作。Any valid URL will work.

    只有當您選擇 [伺服器端 Web 應用程式] 作為應用程式類型時,才可使用 [首頁 URL]。Home Page URL is only available if you choose Server-side Web app for the applciation type.

    若是「對客戶進行內嵌」及 integrate-dashboard-web-app 範例,重新導向 URL 為 http://localhost:13526/redirectFor the embedding for your customers and integrate-dashboard-web-app samples, the redirect URL will be http://localhost:13526/redirect. 若為報表及磚範例,重新導向 URL 則為 http://localhost:13526/For the report and tile sample, the redirect URL will be http://localhost:13526/.

  6. 選擇此應用程式將能存取的 API。Choose the APIs that this application will have access to. 如需 Power BI 存取權限的詳細資訊,請參閱 Power BI Permissions (Power BI 權限)For more information about Power BI access permissions, see Power BI Permissions.

  7. 選取 [註冊應用程式]。Select Register App.

    接著會提供用戶端識別碼給您。You will then be provided with a Client ID. 如果您選取 [伺服器端 Web 應用程式],則還會收到用戶端祕密If you selected Server-side Web app, you will also receive a Client Secret. 之後若有需要,可從 Azure 入口網站中擷取用戶端識別碼The Client ID can be retrieved from the Azure portal, at a later time, if needed. 如果您遺失用戶端祕密,則必須在 Azure 入口網站中建立一個新的。If you lose the Client Secret, you will need to create a new one within the Azure portal.

現在,您可以在自訂應用程式中,使用已註冊的應用程式來與 Power BI 服務互動。You can now use the registered application as part of your custom application to interact with the Power BI service.

重要

如果要內嵌客戶的內容,您必須在 Azure 入口網站中設定其他權限。If you are embedding content for your customers, you will need to configure additional permissions within the Azure portal. 如需詳細資訊,請參閱將權限套用至應用程式For more information, see Apply permissions to your application.

使用 Azure 入口網站註冊Register with the Azure portal

註冊應用程式的另一個選項是直接在 Azure 入口網站中進行。Your other option for registering your application is to do so directly in the Azure portal. 若要註冊您的應用程式,請遵循下列步驟。To register your application, follow these steps.

  1. 接受 Microsoft Power BI API 條款Accept the Microsoft Power BI API Terms.
  2. 登入Azure 入口網站Sign into the Azure portal.
  3. 在頁面的右上角選取您的帳戶,以選擇您的 Azure AD 租用戶。Choose your Azure AD tenant by selecting your account in the top right corner of the page.
  4. 在左側導覽窗格中,選擇 [更多服務],選取 [安全性 + 識別] 下的 [應用程式註冊],然後選取 [新增應用程式註冊]。In the left-hand navigation pane, choose More Services, select App Registrations under Security + Identity and select New application registration.

  5. 遵循提示並建立新的應用程式。Follow the prompts and create a new application.

    • 若是 Web 應用程式,請提供登入 URL,也就是應用程式的基底 URL,可供使用者登入,例如 http://localhost:13526。For Web Applications, provide the Sign-On URL, which is the base URL of your app, where users can sign in e.g http://localhost:13526.
    • 若是原生應用程式,請提供 [重新導向 URI],供 Azure AD 用來傳回權杖回應。For Native Applications, provide a Redirect URI, which Azure AD uses to return token responses. 輸入您的應用程式專用的值,例如 http://myapplication/redirectEnter a value specific to your application, .e.g http://myapplication/redirect

如需如何在 Azure Active Directory 中註冊應用程式的詳細資訊,請參閱整合應用程式與 Azure Active DirectoryFor more information about how to register applications in Azure Active Directory, see Integrating applications with Azure Active Directory

如何取得用戶端識別碼How to get the client id

當您註冊應用程式時,您會收到用戶端識別碼When you register an application, you receive a Client ID. 應用程式使用用戶端識別碼,向要求權限的對象使用者識別自己的身分。The Client ID is used by the application to identify themselves to the users that they are requesting permissions from.

以下是取得用戶端識別碼的方法:Here's how to get a client id:

  1. 登入Azure 入口網站Sign into the Azure portal.
  2. 在頁面的右上角選取您的帳戶,以選擇您的 Azure AD 租用戶。Choose your Azure AD tenant by selecting your account in the top right corner of the page.
  3. 在左側導覽窗格中,選擇 [更多服務],然後選取 [應用程式註冊]。In the left-hand navigation pane, choose More Services and select App Registrations.
  4. 選取您想要擷取用戶端識別碼的應用程式。Select the application that you want to retrieve the client id for.
  5. 您會看到以 GUID 形式列出的應用程式識別碼You will see Application ID listed as a GUID. 這就是應用程式的用戶端識別碼。This is the client id for the application.

    應用程式註冊中,列為應用程式識別碼的用戶端識別碼

在 Azure AD 中將權限套用至應用程式Apply permissions to your application within Azure AD

重要

本節只適用於內嵌組織內容的應用程式。This section only applies to applications that are embedding content for your organization.

除了應用程式註冊頁面中所提供的權限之外,您還需要啟用應用程式的額外權限。You will need to enable additional permissions to your application in addition to what was provided in app registration page. 您可以透過 Azure AD 入口網站或以程式設計方式來完成這項作業。You can accomplish this through the Azure AD portal, or programmatically.

建議您登入用於內嵌的「主」帳戶,或全域管理員帳戶。You will want to be logged in with either the master account, used for embedding, or a Global admin account.

使用 Azure AD 入口網站Using the Azure AD portal

  1. 瀏覽至 Azure 入口網站內的應用程式註冊,然後選取您要用於內嵌的應用程式。Browse to App registrations within the Azure portal and select the app that you are using for embedding.

  2. 選取 [API 存取] 下方的 [必要權限]。Select Required permissions under API Access.

  3. 選取 [Windows Azure Active Directory],然後確定選取 [以登入使用者身分存取目錄]。Select Windows Azure Active Directory and then make sure Access the directory as the signed-in user is selected. 選取 [儲存]。Select Save.

  4. 在 [必要權限] 內,選取 [Power BI 服務 (Power BI)]。Within Required permissions, select Power BI Service (Power BI).

    注意

    如果您直接在 Azure AD 入口網站中建立應用程式,則 [Power BI 服務 (Power BI)] 可能不存在。If you created the app directly in the Azure AD portal, Power BI Service (Power BI) may not be present. 如果不存在,請選取 [+ 新增],然後選取 [1 選取 API]。If it is not, select + Add and then 1 Select and API. 選取 API 清單中的 [Power BI 服務],然後選取 [選取]。Select Power BI Service in the API list and select Select. 如果 [+ 新增] 內沒有 [Power BI 服務 (Power BI)],請註冊 Power BI 和至少一位使用者。If Power BI Service (Power BI) is not available within + Add, sign up for Power BI with at least one user.

  5. 選取 [委派的權限] 下方的所有權限。Select all permissions under Delegated Permissions. 您必須逐一選取它們,才能儲存所做的選擇。You will need to select them one by one in order to save the selections. 完成時,請選取 [儲存]。Select Save when done.

  6. 在 [必要權限] 內,選取 [授與權限]。Within Required permissions, select Grant Permissions.

    主帳戶需要授與權限動作,以避免收到 Azure AD 要求權限的提示。The Grant Permissions action is needed for the master account to avoid being prompted for consent by Azure AD. 若執行此動作的帳戶為全域管理員,您可將此應用程式的權限授與組織中的所有使用者。If the account performing this action is a Global Admin, you will grant permissions to all users within your organization for this application. 若執行此動作的帳戶為主帳戶而非全域管理員,您只可將此應用程式的權限授與主帳戶。If the account performing this action is the master account and is not a Global Admin, you will grant permissions only to the master account for this application.

    在必要權限對話方塊內授與權限

以程式設計方式套用權限Applying permissions programmatically

  1. 您必須取得租用戶內的現有服務主體 (使用者)。You will need to get the existing service principals (users) within your tenant. 如需如何執行這項作業的資訊,請參閱 Get servicePrincipalFor information on how to do that, see Get servicePrincipal.

    您可以呼叫沒有 {id} 的 Get servicePrincipal API,而且它將讓您取得租用戶內的所有服務主體。You can call the Get servicePrincipal api without {id} and it will get you all of the service principals within the tenant.

  2. 使用應用程式用戶端識別碼作為 appId 屬性,以檢查服務主體。Check for a service principal with you app client id as appId property.
  3. 如果您的應用程式遺失服務方案,則請建立新的服務方案。Create a new service plan if missing for your app.

    Post https://graph.microsoft.com/beta/servicePrincipals
    Authorization: Bearer ey..qw
    Content-Type: application/json
    {
    "accountEnabled" : true,
    "appId" : "{App_Client_ID}",
    "displayName" : "{App_DisplayName}"
    }
    
  4. 將應用程式權限授與 PowerBI APIGrant App Permission to PowerBI API

    Post https://graph.microsoft.com/beta/OAuth2PermissionGrants
    Authorization: Bearer ey..qw
    Content-Type: application/json
    { 
    "clientId":"{Service_Plan_ID}",
    "consentType":"AllPrincipals",
    "resourceId":"c78b2585-1df6-41de-95f7-dc5aeb7dc98e",
    "scope":"Dataset.ReadWrite.All Dashboard.Read.All Report.Read.All Group.Read Group.Read.All Content.Create Metadata.View_Any Dataset.Read.All Data.Alter_Any",
    "expiryTime":"2018-03-29T14:35:32.4943409+03:00",
    "startTime":"2017-03-29T14:35:32.4933413+03:00"
    }
    
  5. 將應用程式權限授與 AADGrant App Permission to AAD

    consentType 的值取決於執行要求的使用者。The value for consentType will depend on the user performing the request. 您可以提供 AllPrincipalsPrincipalYou can supply either AllPrincipals or Principal. AllPrincipals 只能由系統管理員用於將權限授與所有使用者。AllPrincipals can only be used by an administrator to grant permission to all users. Principal 則會用於將權限授與特定使用者。Principal is used to grant permission to a specific user.

    主帳戶需要權限授與,以避免收到 Azure AD 要求權限的提示。The permission grant is needed for the master account to avoid being prompted for consent by Azure AD.

    如果您使用現有的租用戶,且不想要代表所有租用戶使用者來授與權限,則可以將 contentType 的值替換為 Principal,以將權限授與特定使用者。If you are using an existing tenant, and not interested in granting permissions on behalf of all tenant users, you can grant permissions to a specific user by replacing the value of contentType to Principal.

    Post https://graph.microsoft.com/beta/OAuth2PermissionGrants
    Authorization: Bearer ey..qw
    Content-Type: application/json
    { 
    "clientId":"{Service_Plan_ID}",
    "consentType":"AllPrincipals",
    "resourceId":"61e57743-d5cf-41ba-bd1a-2b381390a3f1",
    "scope":"User.Read Directory.AccessAsUser.All",
    "expiryTime":"2018-03-29T14:35:32.4943409+03:00",
    "startTime":"2017-03-29T14:35:32.4933413+03:00"
    }
    

後續步驟Next steps

既然您已在 Azure AD 中註冊應用程式,就必須在應用程式中驗證使用者。Now that you have registered your application within Azure AD, you will need to authenticate users within your application. 若要深入了解,請參閱為 Power BI 應用程式驗證使用者及取得 Azure AD 存取權杖Have a look at Authenticate users and get an Azure AD access token for your Power BI app to learn more.

有其他問題嗎?More questions? 嘗試在 Power BI 社群提問Try asking the Power BI Community