-
Notifications
You must be signed in to change notification settings - Fork 905
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #12910 from MicrosoftDocs/main
1/22/2025 PM Publish
- Loading branch information
Showing
5 changed files
with
263 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,252 @@ | ||
| --- | ||
| title: Power BI visual scanner API | ||
| description: Learn how to use the report generated by the scanner API to receive metadata about a Power BI visual. | ||
| author: mberdugo | ||
| ms.author: monaberdugo | ||
| ms.reviewer: gennadyl | ||
| ms.service: powerbi | ||
| ms.subservice: powerbi-custom-visuals | ||
| ms.topic: concept-article | ||
| ms.date: 10/10/2024 | ||
| #customer intent: As a Power BI visual developer, I want to learn how to use the scanner API to receive metadata about a Power BI visual so that I can better understand the visual and its usage. | ||
| --- | ||
|
|
||
| # Scanner API | ||
|
|
||
| The [Workspace information scanner API](/rest/api/power-bi/admin/workspace-info-post-workspace-info) is a REST API that provides metadata about Power BI reports, datasets, and visuals. The scanner API is useful for understanding what kind of information is contained in the report, who created it, what restrictions apply to it, etc. | ||
|
|
||
| If the scanner API is invoked with URI parameter `reportObjects` set to true, the reports section in the output contains information about the visuals used in each report. | ||
|
|
||
| ## Scanner output example | ||
|
|
||
| The following snippet is an example of the reports section of the scanner API output: | ||
|
|
||
| ```json | ||
| "reports": [ | ||
| { | ||
| "reportType": "PowerBIReport", | ||
| "id": "a901f1d6-0848-428a-80c0-98311dc1679b", | ||
| "name": "ContosoSales", | ||
| "datasetId": "2f9bf0f9-b840-4376-a60a-47a6ae07c775", | ||
| "createdDateTime": "2024-07-02T09:28:03.077", | ||
| "modifiedDateTime": "2024-07-02T09:32:37.63", | ||
| "modifiedBy": "[email protected]", | ||
| "createdBy": "[email protected]", | ||
| "modifiedById": "d1814d1d-a355-40b1-8d86-0101ae965820", | ||
| "createdById": "d1814d1d-a355-40b1-8d86-0101ae965820", | ||
| "sensitivityLabel": { | ||
| "labelId": "cebb6849-d26a-4cfa-8f15-030e9d5d9a65" | ||
| }, | ||
| "users": [ | ||
| { | ||
| "reportUserAccessRight": "Owner", | ||
| "emailAddress": "[email protected]", | ||
| "displayName": "Admin EM3", | ||
| "identifier": "[email protected]", | ||
| "graphId": "d1814d1d-a355-40b1-8d86-0101ae965820", | ||
| "principalType": "User", | ||
| "userType": "Member" | ||
| } | ||
| ], | ||
| "sections": [ | ||
| { | ||
| "displayName": "Page 2", | ||
| "visuals": [ | ||
| { | ||
| "visualType": "clusteredBarChart" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "displayName": "Page 1", | ||
| "visuals": [ | ||
| { | ||
| "visualType": "Sunburst1445472000808" | ||
| }, | ||
| { | ||
| "visualType": "WordCloud1447959067750" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| As you can see, the reports section contains a `sections` list. Each section contains the section name and lists the type of each visual in that section: | ||
|
|
||
| ```json | ||
| "sections": [ | ||
| { | ||
| "displayName": "Page 1", | ||
| "visuals": [ | ||
| { | ||
| "visualType": "Sunburst1445472000808" | ||
| }, | ||
| { | ||
| "visualType": "WordCloud1447959067750" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| To get information about a visual (for example, its name, whether it’s a core visual, public custom visual or private visual, certified, etc.) check the visual type against multiple data sources. Then add to the data about the visual data based on the information you find. | ||
|
|
||
| ## Core visuals | ||
|
|
||
| The following list contains the types of [Core (built-in) visuals](./power-bi-custom-visuals.md#core-power-bi-visuals): | ||
|
|
||
| ```json | ||
| "actionButton" | ||
| "animatedNumber" | ||
| "areaChart" | ||
| "barChart" | ||
| "basicShape" | ||
| "shape" | ||
| "card" | ||
| "cardVisual" | ||
| "multiRowCard" | ||
| "clusteredBarChart" | ||
| "clusteredColumnChart" | ||
| "columnChart" | ||
| "donutChart" | ||
| "funnel" | ||
| "gauge" | ||
| "hundredPercentStackedBarChart" | ||
| "hundredPercentStackedColumnChart" | ||
| "image" | ||
| "lineChart" | ||
| "lineStackedColumnComboChart" | ||
| "lineClusteredColumnComboChart" | ||
| "map" | ||
| "filledMap" | ||
| "azureMap" | ||
| "ribbonChart" | ||
| "shapeMap" | ||
| "treemap" | ||
| "pieChart" | ||
| "realTimeLineChart" | ||
| "scatterChart" | ||
| "stackedAreaChart" | ||
| "table" | ||
| "matrix" | ||
| "tableEx" | ||
| "pivotTable" | ||
| "accessibleTable" | ||
| "slicer" | ||
| "advancedSlicerVisual" | ||
| "pageNavigator" | ||
| "bookmarkNavigator" | ||
| "filterSlicer" | ||
| "textbox" | ||
| "aiNarratives" | ||
| "waterfallChart" | ||
| "scriptVisual" | ||
| "pythonVisual" | ||
| "kpi" | ||
| "keyDriversVisual" | ||
| "decompositionTreeVisual" | ||
| "qnaVisual" | ||
| "scorecard" | ||
| "rdlVisual" | ||
| "dataQueryVisual" | ||
| "debugVisual" | ||
| "heatMap" | ||
| ``` | ||
|
|
||
| If the visual type is a core visual, there's no need to look for it in other data sources, like AppSource catalog. | ||
|
|
||
| ## AppSource (public) custom visuals | ||
|
|
||
| AppSource visuals are public Custom Visuals available from [Microsoft AppSource](https://appsource.microsoft.com/marketplace/apps?product=power-bi-visuals). You can fetch visual information from the public [catalog endpoint](https://catalogapi.azure.com/offers?storefront=appsource&api-version=2018-08-01-beta&$filter=offertype+eq+%27PowerBIVisuals%27) that AppSource provides. | ||
|
|
||
| The resulting json contains a list of items and a link to the next page, `nextPageLink`. For example: | ||
|
|
||
| ```json | ||
| { | ||
| "items": [ | ||
| { | ||
| } | ||
| ], | ||
| "nextPageLink": https://catalogapi.azure.com/offers?storefront=appsource&api-version=2018-08-01-beta&$filter=offertype+eq+%27PowerBIVisuals%27&$skiptoken=W3sidG9rZW4iOiIrUklEOn4yVk53QUxkRkVIeHNhQUFBQUFCQUNBPT0jUlQ6MSNUUkM6MTg1I0lTVjoyI0lFTzo2NTU2NyNRQ0Y6OCIsInJhbmdlIjp7Im1pbiI6IjA1QzFFNzBCM0IzOTUwIiwibWF4IjoiMDVDMUU3QUIxN0U3QTYifX1d | ||
| } | ||
| ``` | ||
|
|
||
| Typically, a full list of visuals is about 3-4 pages long. For complete information about the visual, you must fetch the entire report. | ||
|
|
||
| Each item in the items list is a custom visual and contains all the information stored about it in AppSource. This document references only relevant fields: | ||
|
|
||
| ```json | ||
|
|
||
|
|
||
| "powerBIVisualId": "visualType", | ||
|
|
||
| "displayName": "Mapbox Custom Visual", | ||
|
|
||
| "publisherDisplayName": "OKVIZ Corp.", | ||
|
|
||
| "enrichedData": { | ||
|
|
||
| "tags": [ | ||
|
|
||
| "PowerBICertified" | ||
|
|
||
| ], | ||
|
|
||
| }, | ||
|
|
||
| "categoryIds": [ | ||
|
|
||
| "pbiv-other", | ||
|
|
||
| "PowerBICertified" | ||
|
|
||
| ], | ||
|
|
||
| "id": "xviz.inforiver-charts" | ||
| ``` | ||
|
|
||
| The following fields can be used to enhance information about a visual provided by Scanner API: | ||
|
|
||
| * "powerBIVisualId": used to find correct item, which should be the same as `visualType` from Scanner output | ||
|
|
||
| * "displayName": visual name | ||
|
|
||
| * Tag “PowerBICertified” means that visual is Certified | ||
|
|
||
| * "publisherDisplayName": publisher name | ||
|
|
||
| * "id" is used to calculate PDP link page: `https://appsource.microsoft.com/<locale> /product/PowerBIVisuals/<id>` | ||
|
|
||
| ## Private Custom Visuals (from a file) | ||
|
|
||
| Private visuals added to a Power BI report using the [Import a visual from a file](./import-visual.md#import-a-visual-file-from-your-local-computer-into-power-bi) option. If a visual isn't a core visual and not an AppSource visual, it’s a private visual. For private visuals, we provide only their `visualType`. | ||
|
|
||
| ## Organization visuals | ||
|
|
||
| Both AppSource visuals and private visuals can be added to the Organization’s visuals store which exists for each organization (tenant). If a private custom visual is added to an organization’s visual store, the suffix _OrgStore is added to its `visualType`. In contrast, when an AppSource visual is added directly to an organization’s visual store, it keeps its original `visualType`. | ||
|
|
||
| To determine if a public custom visual (from AppSource) is in an organization's store: | ||
|
|
||
| 1. Get the visual’s information using information from the [AppSource catalog](#appsource-public-custom-visuals). | ||
| 1. Download the organization’s visuals list (in CSV format) from **Power BI** -> **Admin Portal** -> **Organization Visuals** -> **Export**. | ||
| 1. If the visual’s `visualType` appears in the downloaded list, this visual is an organizational visual. In this case, update visual name to match the one in the CSV file. | ||
|
|
||
| > [!NOTE] | ||
| > | ||
| > * There is no difference between an AppSource custom visual and its counterpart in the organization store, including its code and version. The only difference might be in the visual name. | ||
| > * If the tenant admin downloads a custom visual *.pbiviz* file from AppSource and adds it to the organization store using Add Visual -> From File, the suffix *_OrgStore* is added and when exported, it will appear as a *Private file*. A private file visual doesn't get upgraded and is treated as a private visual in the Org Store. | ||
| Demo application to use Scanner API | ||
|
|
||
| Original code: | ||
|
|
||
| `https://github.com/microsoft/Fabric-metadata-scanning` | ||
|
|
||
| Updated code includes visual info enrichment: | ||
| `https://github.com/gennadylaventman/Fabric-metadata-scanning/tree/dev/glaventman/enrichCV` | ||
|
|
||
| ## Related content | ||
|
|
||
| [Power BI custom visuals](./power-bi-custom-visuals.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters