Skip to content

Commit

Permalink
Merged PR 229173: Update README.md
Browse files Browse the repository at this point in the history 
- Remove obsolete content (WS collection related)
- Change the description to be more general: not focused on embed only but REST APIs in general
- Provide up-to date simple examples (Get Report and Datasets, Generate Embed Token V2, Get Reports as Admin).
  • Loading branch information
@laurent-mic
laurent-mic committed Jan 12, 2022
1 parent 42aba92 commit 7f6ea65
Showing 1 changed file with 68 additions and 138 deletions.
206 changes: 68 additions & 138 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,163 +1,93 @@
# Power BI for .NET
# Power BI REST APIs for .NET

Welcome to the .NET developer community for Power BI Embedded. Here you will find resources for the .NET SDKs for Power BI Embedded.
## Overview
The Power BI REST APIs provide service endpoints for embedding, user resources management, administration and governance.

For questions or issues using the SDKs please log an issue and we will respond as quickly as possible.
For more information about Power BI REST APIs, see [Power BI REST APIs overview](https://docs.microsoft.com/rest/api/power-bi/).

For more information regarding onboarding to Power BI Embedded see our [Azure documentation](https://azure.microsoft.com/en-us/services/power-bi-embedded/).
## Power BI API library
The Microsoft.PowerBI.Api library for .NET enables you to work with Power BI REST APIs in your .NET or NET Core application.

## Issues
[Power BI Support Page](https://powerbi.microsoft.com/en-us/support/)

[Power BI Ideas](https://ideas.powerbi.com)

## Power BI Embedded Core Libraries
The `Microsoft.PowerBI.Core` package contains APIs to generate report embed tokens.

### Install from Nuget
`Install-Package Microsoft.PowerBI.Core`

### Usage: Creating a Report Embed Token
Power BI Embedded uses embed tokens, which are HMAC signed JSON Web Tokens. The tokens are signed with the access key from your Azure Power BI Embedded workspace collection.
Embed tokens are used to provide read only access to a report to embed into an application.

To create a report embed token you will need an Azure Power BI Workspace collection, access key, workspace Id & report Id
Install the [NuGet package](https://www.nuget.org/packages/Microsoft.PowerBI.Api/) directly from the Visual Studio [Package Manager console](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-powershell).

### Visual Studio Package Manager
```powershell
Install-Package Microsoft.PowerBI.Api
```
var accessKey = "{AzureAccessKey}";
var embedToken = PowerBIToken.CreateReportEmbedToken(workspaceCollection, workspaceId, reportId);
var jwt = embedToken.Generate(accessKey);

```
## Examples

### Required Claims
- ver: 0.2.0
- typ: "embed"
- wcn: {WorkspaceCollectionName}
- wid: {WorkspaceId}
- rid: {ReportId} (or did: {DatasetId})
- aud: https://analysis.windows.net/powerbi/api
- exp: Token expiration in Unix EPOCH time
Below are basic examples demonstrating some of the most common capabilities of the SDK.
Full examples including authentication are avaliable in [PowerBI-Developer-Samples](https://github.com/Microsoft/PowerBI-Developer-Samples)

### Optional Claims
- nbp: Token valid not before in Unix EPOCH time
- username: The effective username to pass to Power BI Embedded for RLS (Row level security)
- roles: The roles to pass to Power BI Embedded for RLS
- scp: The permission scopes allowed with the designated Report or Dataset
### Get the list of datasets and reports in a Power BI workspace
```C#
...
using (PowerBIClient client = new PowerBIClient(credentials))
{

Read more about [row level security](https://azure.microsoft.com/en-us/documentation/articles/power-bi-embedded-rls/) in our Azure docs.
Console.WriteLine("\r*** DATASETS ***\r");

### Token Example
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ2ZXIiOiIwLjIuMCIsIndjbiI6IlN1cHBvcnREZW1vIiwid2lkIjoiY2E2NzViMTktNmMzYy00MDAzLTg4MDgtMWM3ZGRjNmJkODA5IiwicmlkIjoiOTYyNDFmMGYtYWJhZS00ZWE5LWEwNjUtOTNiNDI4ZWRkYjE3IiwiaXNzIjoiUG93ZXJCSVNESyIsImF1ZCI6Imh0dHBzOi8vYW5hbHlzaXMud2luZG93cy5uZXQvcG93ZXJiaS9hcGkiLCJleHAiOjEzNjAwNDcwNTYsIm5iZiI6MTM2MDA0MzQ1Nn0.LgG2y0m24gg3vjQHhkXYYWKSVnGIUYT-ycA6JmTB6tg
// List of datasets in a workspace
Datasets datasets = client.Datasets.GetDatasets(groupId);

## Adding Permission Scopes to Embed Tokens
When using Embed tokens, one might want to restrict usage of the resources he gives access to. For this reason, you can generate a token with scoped permissions.
foreach(Dataset ds in datasets.Value)
{
Console.WriteLine(ds.Id + " | " + ds.Name);
}

```
var accessKey = "{AzureAccessKey}";
var scopes = {Scopes as string or array of strings};
var embedToken = PowerBIToken.CreateReportEmbedTokenWithScopes(workspaceCollection, workspaceId, reportId, scopes: scopes);
var jwt = embedToken.Generate(accessKey);
Console.WriteLine("\r*** REPORTS ***\r");

```
### Token Example - With Scopes
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ2ZXIiOiIwLjIuMCIsIndjbiI6IlN1cHBvcnREZW1vIiwid2lkIjoiY2E2NzViMTktNmMzYy00MDAzLTg4MDgtMWM3ZGRjNmJkODA5IiwicmlkIjoiOTYyNDFmMGYtYWJhZS00ZWE5LWEwNjUtOTNiNDI4ZWRkYjE3Iiwic2NwIjoiUmVwb3J0LlJlYWQiLCJpc3MiOiJQb3dlckJJU0RLIiwiYXVkIjoiaHR0cHM6Ly9hbmFseXNpcy53aW5kb3dzLm5ldC9wb3dlcmJpL2FwaSIsImV4cCI6MTM2MDA0NzA1NiwibmJmIjoxMzYwMDQzNDU2fQ.M1jkWXnkfwJeGQqh1x0vIAYB4EBKbHSZFoDB6n_LZyA
// List of reports in a workspace
Reports reports = client.Reports.GetReports(groupId);

#### Decoded
The following decoded JSON web token
**Header**
```javascript
{
"typ": "JWT",
"alg": "HS256"
foreach (Report rpt in reports.Value)
{
Console.WriteLine(rpt.Id + " | " + rpt.Name + " | DatasetID = " + rpt.DatasetId);
}
}
...
```
### Creating an Embed Token to reports and datasets
Embed tokens are used to provide access to Power BI artifacts like reports and datasets to embed into an application.
To create a report embed token you will need a Power BI Embedded capacity, and the Ids of the workspaces and artifacts to provide access to.
For more information about Power BI Embedded visit the [Power BI Embedded Analytics Playground](https://playground.powerbi.com)

**Payload**
```javascript
{
"ver": "0.2.0",
"wcn": "SupportDemo",
"wid": "ca675b19-6c3c-4003-8808-1c7ddc6bd809",
"rid": "96241f0f-abae-4ea9-a065-93b428eddb17",
"scp": "Report.Read",
"iss": "PowerBISDK",
"aud": "https://analysis.windows.net/powerbi/api",
"exp": 1360047056,
"nbf": 1360043456
}
```

## Power BI Embedded REST Client
The `Microsoft.PowerBI.Api` is a .NET REST Client to easily consume the Power BI Embedded REST services.

### Install from Nuget
`Install-Package Microsoft.PowerBI.Api`
```C#
...
using (PowerBIClient client = new PowerBIClient(credentials))
{
// Create a request for getting Embed token
var tokenRequest = new GenerateTokenRequestV2(datasets: datasets, reports: reports, targetWorkspaces: workspaces, identities: identities);

### Usage: Calling the GetReports API
As an example, to get a list or reports within your workspace you need to instantiate a `PowerBIClient` with credentials and call into the `GetReports` API.
// Get Embed token
var embedToken = client.EmbedToken.GenerateToken(tokenRequest);
}
...
```
var credentials = new TokenCredentials("{AzureAccessKey}", "AppKey");
var client = new PowerBIClient(credentials);
### Get Reports As Admin
Returns a list of reports for the organization. The caller must have administrator rights.
```C#
...
using (PowerBIClient client = new PowerBIClient(credentials))
{
Console.WriteLine("\r*** REPORTS ***\r");

var reportsResult = await client.Reports.GetReportsAsync(workspaceCollection, workspaceId);
// List of reports in the organization.
AdminReports reports = client.Reports.GetReportsAsAdmin();

foreach (AdminReport rpt in reports.Value)
{
Console.WriteLine(rpt.Id + " | " + rpt.Name);
}
}
...
```

The following APIs groups are available:

- Datasets
- Gateways
- Imports
- Reports
- Workspaces

## Power BI Embedded for JavaScript
The JavaScript SDK is underlying component for all embed scenarios. The SDK is vanilla JS but we also ship components for many popular SPA frameworks including Angular, React & Ember JS.

Visit our [JavaScript SDK](https://github.com/Microsoft/powerbi-javascript) home for more information

### Install from Nuget
`Install-Package Microsoft.PowerBI.JavaScript`

### Setup Power BI for embedding
Add the Power BI script include before your apps closing `</body>` tag

*You can optionally add the CSS reference to an ASP.NET style bundle*

`<script src="/scripts/powerbi.js"></script>`

### Setting the size of embedded components
The tile & report embed will automatically be embedded based on the size of the embed container.
To override the default size of the embeds simply add a CSS class attribute or inline styles for width & height.

# ASP.NET MVC
The `Microsoft.PowerBI.AspNet.Mvc` package is a lightweight wrapper that contains MVC HTML helpers that generate HTML markup compatible with the core JavaScript SDK.

## Install from Nuget
`Install-Package Microsoft.PowerBI.AspNet.Mvc`

## Setup your Access Token
Generate your report embed access token with the `Microsoft.PowerBI.Core` token APIs.
`@Html.PowerBIAccesstoken({{YourAccesstoken}})`

## Embed your report
`@Html.PowerBIReportFor(m => m.EmbedUrl)`

# ASP.NET WebForms
The `Microsoft.PowerBI.AspNet.WebForms` package is a lightweight wrapper that contains ASP.NET Webform controls that generate HTML markup compatible with the core JavaScript SDK.
## Install from Nuget
`Install-Package Microsoft.PowerBI.AspNet.WebForms`

## Setup your Access Token
Ensure you have the following in your view

`<powerbi:Token ID="pbiAccessToken" runat="server" />`

If you are managing access tokens yourself, make sure to provide it here

`<powerbi:Token ID="pbiAccessToken" AccessToken="{{YourAccessToken}}" runat="server" />`

## Embedding a Report

`<powerbi:Report id="pbiReport" EmbedUrl="{{EmbedUrl}}" runat="server" />`
## Additional links
- [Power BI REST APIs](https://docs.microsoft.com/rest/api/power-bi/)
- [PowerBI-Developer-Samples](https://github.com/Microsoft/PowerBI-Developer-Samples)
- [AAD Application registration](https://docs.microsoft.com/power-bi/developer/embedded/register-app?tabs=customers%2CAzure#register-an-azure-ad-app)
- [Power BI Embedded Analytics Playground](https://playground.powerbi.com)
- [PowerBI Powershell CmdLet](https://github.com/microsoft/powerbi-powershell)

0 comments on commit 7f6ea65

Please sign in to comment.