fabric-api 1.0.0__tar.gz

fabric_api-1.0.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: fabric-api
+Version: 1.0.0
+Summary: Power BI and Fabric REST API wrapper for automating operations
+License: MIT
+Author: Bernardo Rufino
+Author-email: contact@bernardorufino.com
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: Office365-REST-Python-Client (==2.4.1)
+Requires-Dist: azure-identity (>=1.24.0,<2)
+Requires-Dist: azure-kusto-data (>=6.0.1,<7.0.0)
+Requires-Dist: ipykernel
+Requires-Dist: numpy (==2.1.3)
+Requires-Dist: openpyxl (==3.1.5)
+Requires-Dist: pandas (==2.2.3)
+Requires-Dist: pyodbc (==5.2.0)
+Requires-Dist: python-dotenv (==1.0.1)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: sqlalchemy (==2.0.44)
+Description-Content-Type: text/markdown
+
+# Power BI & Fabric API Wrapper
+
+Python wrapper for the Power BI REST API and Microsoft Fabric API, designed to automate workspace management, dataset operations, report handling, dataflows, and more.
+
+## Installation
+
+This is a **private package**. You must be granted access to the repository before installing.
+
+### Install from GitHub (recommended)
+
+```shell
+pip install git+https://github.com/Bernardo-Rufino/powerbi-api.git
+```
+
+To install a specific version/tag:
+
+```shell
+pip install git+https://github.com/Bernardo-Rufino/powerbi-api.git@v1.0.0
+```
+
+If the repo is private, authenticate using a [Personal Access Token (PAT)](https://github.com/settings/tokens):
+
+```shell
+pip install git+https://ghp_YOUR_TOKEN@github.com/Bernardo-Rufino/powerbi-api.git
+```
+
+### Install for local development
+
+```shell
+git clone https://github.com/Bernardo-Rufino/powerbi-api.git
+cd powerbi-api
+pip install -e .
+```
+
+### Granting access to others
+
+1. Go to the repository on GitHub
+2. **Settings → Collaborators → Add people**
+3. The invited user installs the package using their own PAT (as shown above)
+
+---
+
+## Prerequisites
+
+- Python >= 3.10
+- An Azure app registration with a client ID and client secret
+
+## Setting Up
+
+1. **Install the package** (see above)
+
+2. **Set up credentials** — choose one of the two options:
+
+    **Option A – `.env` file** (local development): copy the example and fill in your values:
+
+    ```shell
+    cp utils/.env.example utils/.env
+    ```
+
+    Then edit `utils/.env`:
+
+    ```shell
+    TENANT_ID='<YOUR_TENANT_ID>'
+    CLIENT_ID='<YOUR_CLIENT_ID>'
+    CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
+    CLIENT_ID_SHAREPOINT='<YOUR_SHAREPOINT_CLIENT_ID>'
+    CLIENT_SECRET_SHAREPOINT='<YOUR_SHAREPOINT_CLIENT_SECRET>'
+    AZURE_SUBSCRIPTION_ID='<YOUR_AZURE_SUBSCRIPTION_ID>'
+    AZURE_RESOURCE_GROUP_ID='<YOUR_AZURE_RESOURCE_GROUP_ID>'
+    ```
+
+    **Option B – environment variables** (CI/CD, Docker, etc.): if the variables are already set in the environment, the `.env` file is skipped automatically — no extra setup needed.
+
+3. **Authenticate**:
+
+    ```python
+    from powerbi_api import Auth
+
+    auth = Auth(TENANT_ID, CLIENT_ID, CLIENT_SECRET)
+    token = auth.get_token()            # Power BI API
+    fabric_token = auth.get_token('fabric')  # Fabric API
+    ```
+
+## Modules
+
+### Auth
+
+Authentication via Azure service principal or interactive user login.
+
+| Method | Description |
+|---|---|
+| `get_token(service='pbi')` | Get a bearer token for Power BI (`pbi`) or Fabric (`fabric`) APIs using a service principal. |
+| `get_token_for_user(service='pbi')` | Get a bearer token via interactive user login. Supports `pbi`, `fabric`, and `azure` services. |
+
+### Workspace
+
+Manage Power BI workspaces, users, and permissions.
+
+| Method | Description |
+|---|---|
+| `list_workspaces(...)` | List all workspaces the user has access to, with optional filters. |
+| `get_workspace_details(workspace_id)` | Get details for a specific workspace. |
+| `list_users(workspace_id)` | List all users in a workspace. |
+| `list_reports(workspace_id)` | List all reports in a workspace. |
+| `add_user(user_principal_name, workspace_id, access_right, user_type)` | Add a user or service principal to a workspace. |
+| `update_user(user_principal_name, workspace_id, access_right)` | Update a user's role on a workspace. |
+| `remove_user(user_principal_name, workspace_id)` | Remove a user from a workspace. |
+| `batch_update_user(user, workspaces_list)` | Batch update a user across multiple workspaces. |
+
+### Dataset
+
+Manage datasets, permissions, and execute DAX queries.
+
+| Method | Description |
+|---|---|
+| `list_datasets(workspace_id)` | List all datasets in a workspace. |
+| `get_dataset_details(workspace_id, dataset_id)` | Get details of a specific dataset. |
+| `execute_query(workspace_id, dataset_id, query)` | Execute a DAX query against a dataset. |
+| `list_users(workspace_id, dataset_id)` | List users with access to a dataset. |
+| `add_user(user_principal_name, workspace_id, dataset_id, access_right)` | Grant a user access to a dataset. |
+| `update_user(user_principal_name, workspace_id, dataset_id, access_right)` | Update a user's access to a dataset. |
+| `remove_user(user_principal_name, workspace_id, dataset_id)` | Remove a user's access to a dataset. |
+| `list_dataset_related_reports(workspace_id, dataset_id)` | List all reports linked to a dataset. |
+| `export_dataset_related_reports(workspace_id, dataset_id)` | Export all reports linked to a dataset as `.pbix` files. |
+
+### Report
+
+Retrieve report metadata, definitions, visuals, and report-level measures.
+
+| Method | Description |
+|---|---|
+| `list_reports(workspace_id)` | List all reports in a workspace. |
+| `get_report_metadata(workspace_id, report_id)` | Get metadata for a specific report. |
+| `get_report_name(workspace_id, report_id)` | Get a report's display name. |
+| `list_report_pages(workspace_id, report_id)` | List all pages in a report. |
+| `get_report_json_pages_and_visuals(json_data, workspace_id, report_id)` | Parse a PBIR-Legacy report JSON and extract pages and visual details into a DataFrame. |
+| `get_legacy_report_json(workspace_id, report_id, operations)` | Get and decode the full report definition for PBIR-Legacy reports. |
+| `export_report(workspace_id, report_id, ...)` | Export a report as a `.pbix` file. |
+| `get_report_measures(workspace_id, report_id, operations)` | Extract report-level measures and generate a DAX Query View script. Supports both PBIR and PBIR-Legacy formats. |
+
+### Dataflow
+
+Manage Power BI and Fabric dataflows, including Gen2.
+
+| Method | Description |
+|---|---|
+| `list_dataflows(workspace_id, type='pbi')` | List dataflows in a workspace. Use `type='fabric'` for Fabric API. |
+| `get_dataflow_details(workspace_id, dataflow_id)` | Get details of a specific dataflow. |
+| `create_dataflow(workspace_id, dataflow_content)` | Create a new Power BI dataflow. |
+| `delete_dataflow(workspace_id, dataflow_id, type='pbi')` | Delete a dataflow. Use `type='fabric'` for Fabric API. |
+| `export_dataflow_json(workspace_id, dataflow_id, dataflow_name)` | Export a dataflow definition as JSON. |
+| `get_dataflow_gen2_definition(workspace_id, dataflow_id)` | Get the definition of a Dataflow Gen2. |
+| `create_dataflow_gen2_from_definition(workspace_id, display_name, definition)` | Create a Dataflow Gen2 from a definition. |
+| `update_dataflow_gen2_from_definition(workspace_id, dataflow_id, display_name, definition)` | Update an existing Dataflow Gen2. |
+
+### Capacity
+
+Monitor and manage Power BI and Fabric capacities.
+
+| Method | Description |
+|---|---|
+| `list_powerbi_capacities()` | List all Power BI capacities the user has access to. |
+| `list_fabric_capacities(azure_subscription_id, azure_resource_group)` | List Fabric capacities for a given Azure subscription. |
+| `assign_workspace_to_capacity(workspace_id, capacity_id)` | Assign a workspace to a capacity. |
+
+### Operations
+
+Track long-running Fabric API operations.
+
+| Method | Description |
+|---|---|
+| `get_operation_state(operation_id)` | Get the current state of a long-running operation. |
+| `get_operation_result(operation_id)` | Get the result of a completed operation. |
+
+### Admin
+
+Power BI Admin API operations.
+
+| Method | Description |
+|---|---|
+| `get_report_users_as_admin(report_id)` | List users with access to a report (admin endpoint). |
+
+### KQLDatabase
+
+Query Kusto (KQL) databases in Microsoft Fabric.
+
+| Method | Description |
+|---|---|
+| `query_kql_database(kql_query, sort_by)` | Execute a KQL query and return results as a DataFrame. |
+
+### Lakehouse
+
+Query SQL databases (Lakehouse) via ODBC.
+
+| Method | Description |
+|---|---|
+| `execute_query(query)` | Execute a SQL query against a lakehouse database. |
+
+## Limitations
+
+- The Power BI REST API has a **200 requests per hour** rate limit.
+- Not all users can be updated via the API. See Microsoft docs: [Dataset permissions](https://learn.microsoft.com/en-us/power-bi/developer/embedded/datasets-permissions#get-and-update-dataset-permissions-with-apis).
+

fabric_api-1.0.0/README.md

@@ -0,0 +1,202 @@
+# Power BI & Fabric API Wrapper
+
+Python wrapper for the Power BI REST API and Microsoft Fabric API, designed to automate workspace management, dataset operations, report handling, dataflows, and more.
+
+## Installation
+
+This is a **private package**. You must be granted access to the repository before installing.
+
+### Install from GitHub (recommended)
+
+```shell
+pip install git+https://github.com/Bernardo-Rufino/powerbi-api.git
+```
+
+To install a specific version/tag:
+
+```shell
+pip install git+https://github.com/Bernardo-Rufino/powerbi-api.git@v1.0.0
+```
+
+If the repo is private, authenticate using a [Personal Access Token (PAT)](https://github.com/settings/tokens):
+
+```shell
+pip install git+https://ghp_YOUR_TOKEN@github.com/Bernardo-Rufino/powerbi-api.git
+```
+
+### Install for local development
+
+```shell
+git clone https://github.com/Bernardo-Rufino/powerbi-api.git
+cd powerbi-api
+pip install -e .
+```
+
+### Granting access to others
+
+1. Go to the repository on GitHub
+2. **Settings → Collaborators → Add people**
+3. The invited user installs the package using their own PAT (as shown above)
+
+---
+
+## Prerequisites
+
+- Python >= 3.10
+- An Azure app registration with a client ID and client secret
+
+## Setting Up
+
+1. **Install the package** (see above)
+
+2. **Set up credentials** — choose one of the two options:
+
+    **Option A – `.env` file** (local development): copy the example and fill in your values:
+
+    ```shell
+    cp utils/.env.example utils/.env
+    ```
+
+    Then edit `utils/.env`:
+
+    ```shell
+    TENANT_ID='<YOUR_TENANT_ID>'
+    CLIENT_ID='<YOUR_CLIENT_ID>'
+    CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
+    CLIENT_ID_SHAREPOINT='<YOUR_SHAREPOINT_CLIENT_ID>'
+    CLIENT_SECRET_SHAREPOINT='<YOUR_SHAREPOINT_CLIENT_SECRET>'
+    AZURE_SUBSCRIPTION_ID='<YOUR_AZURE_SUBSCRIPTION_ID>'
+    AZURE_RESOURCE_GROUP_ID='<YOUR_AZURE_RESOURCE_GROUP_ID>'
+    ```
+
+    **Option B – environment variables** (CI/CD, Docker, etc.): if the variables are already set in the environment, the `.env` file is skipped automatically — no extra setup needed.
+
+3. **Authenticate**:
+
+    ```python
+    from powerbi_api import Auth
+
+    auth = Auth(TENANT_ID, CLIENT_ID, CLIENT_SECRET)
+    token = auth.get_token()            # Power BI API
+    fabric_token = auth.get_token('fabric')  # Fabric API
+    ```
+
+## Modules
+
+### Auth
+
+Authentication via Azure service principal or interactive user login.
+
+| Method | Description |
+|---|---|
+| `get_token(service='pbi')` | Get a bearer token for Power BI (`pbi`) or Fabric (`fabric`) APIs using a service principal. |
+| `get_token_for_user(service='pbi')` | Get a bearer token via interactive user login. Supports `pbi`, `fabric`, and `azure` services. |
+
+### Workspace
+
+Manage Power BI workspaces, users, and permissions.
+
+| Method | Description |
+|---|---|
+| `list_workspaces(...)` | List all workspaces the user has access to, with optional filters. |
+| `get_workspace_details(workspace_id)` | Get details for a specific workspace. |
+| `list_users(workspace_id)` | List all users in a workspace. |
+| `list_reports(workspace_id)` | List all reports in a workspace. |
+| `add_user(user_principal_name, workspace_id, access_right, user_type)` | Add a user or service principal to a workspace. |
+| `update_user(user_principal_name, workspace_id, access_right)` | Update a user's role on a workspace. |
+| `remove_user(user_principal_name, workspace_id)` | Remove a user from a workspace. |
+| `batch_update_user(user, workspaces_list)` | Batch update a user across multiple workspaces. |
+
+### Dataset
+
+Manage datasets, permissions, and execute DAX queries.
+
+| Method | Description |
+|---|---|
+| `list_datasets(workspace_id)` | List all datasets in a workspace. |
+| `get_dataset_details(workspace_id, dataset_id)` | Get details of a specific dataset. |
+| `execute_query(workspace_id, dataset_id, query)` | Execute a DAX query against a dataset. |
+| `list_users(workspace_id, dataset_id)` | List users with access to a dataset. |
+| `add_user(user_principal_name, workspace_id, dataset_id, access_right)` | Grant a user access to a dataset. |
+| `update_user(user_principal_name, workspace_id, dataset_id, access_right)` | Update a user's access to a dataset. |
+| `remove_user(user_principal_name, workspace_id, dataset_id)` | Remove a user's access to a dataset. |
+| `list_dataset_related_reports(workspace_id, dataset_id)` | List all reports linked to a dataset. |
+| `export_dataset_related_reports(workspace_id, dataset_id)` | Export all reports linked to a dataset as `.pbix` files. |
+
+### Report
+
+Retrieve report metadata, definitions, visuals, and report-level measures.
+
+| Method | Description |
+|---|---|
+| `list_reports(workspace_id)` | List all reports in a workspace. |
+| `get_report_metadata(workspace_id, report_id)` | Get metadata for a specific report. |
+| `get_report_name(workspace_id, report_id)` | Get a report's display name. |
+| `list_report_pages(workspace_id, report_id)` | List all pages in a report. |
+| `get_report_json_pages_and_visuals(json_data, workspace_id, report_id)` | Parse a PBIR-Legacy report JSON and extract pages and visual details into a DataFrame. |
+| `get_legacy_report_json(workspace_id, report_id, operations)` | Get and decode the full report definition for PBIR-Legacy reports. |
+| `export_report(workspace_id, report_id, ...)` | Export a report as a `.pbix` file. |
+| `get_report_measures(workspace_id, report_id, operations)` | Extract report-level measures and generate a DAX Query View script. Supports both PBIR and PBIR-Legacy formats. |
+
+### Dataflow
+
+Manage Power BI and Fabric dataflows, including Gen2.
+
+| Method | Description |
+|---|---|
+| `list_dataflows(workspace_id, type='pbi')` | List dataflows in a workspace. Use `type='fabric'` for Fabric API. |
+| `get_dataflow_details(workspace_id, dataflow_id)` | Get details of a specific dataflow. |
+| `create_dataflow(workspace_id, dataflow_content)` | Create a new Power BI dataflow. |
+| `delete_dataflow(workspace_id, dataflow_id, type='pbi')` | Delete a dataflow. Use `type='fabric'` for Fabric API. |
+| `export_dataflow_json(workspace_id, dataflow_id, dataflow_name)` | Export a dataflow definition as JSON. |
+| `get_dataflow_gen2_definition(workspace_id, dataflow_id)` | Get the definition of a Dataflow Gen2. |
+| `create_dataflow_gen2_from_definition(workspace_id, display_name, definition)` | Create a Dataflow Gen2 from a definition. |
+| `update_dataflow_gen2_from_definition(workspace_id, dataflow_id, display_name, definition)` | Update an existing Dataflow Gen2. |
+
+### Capacity
+
+Monitor and manage Power BI and Fabric capacities.
+
+| Method | Description |
+|---|---|
+| `list_powerbi_capacities()` | List all Power BI capacities the user has access to. |
+| `list_fabric_capacities(azure_subscription_id, azure_resource_group)` | List Fabric capacities for a given Azure subscription. |
+| `assign_workspace_to_capacity(workspace_id, capacity_id)` | Assign a workspace to a capacity. |
+
+### Operations
+
+Track long-running Fabric API operations.
+
+| Method | Description |
+|---|---|
+| `get_operation_state(operation_id)` | Get the current state of a long-running operation. |
+| `get_operation_result(operation_id)` | Get the result of a completed operation. |
+
+### Admin
+
+Power BI Admin API operations.
+
+| Method | Description |
+|---|---|
+| `get_report_users_as_admin(report_id)` | List users with access to a report (admin endpoint). |
+
+### KQLDatabase
+
+Query Kusto (KQL) databases in Microsoft Fabric.
+
+| Method | Description |
+|---|---|
+| `query_kql_database(kql_query, sort_by)` | Execute a KQL query and return results as a DataFrame. |
+
+### Lakehouse
+
+Query SQL databases (Lakehouse) via ODBC.
+
+| Method | Description |
+|---|---|
+| `execute_query(query)` | Execute a SQL query against a lakehouse database. |
+
+## Limitations
+
+- The Power BI REST API has a **200 requests per hour** rate limit.
+- Not all users can be updated via the API. See Microsoft docs: [Dataset permissions](https://learn.microsoft.com/en-us/power-bi/developer/embedded/datasets-permissions#get-and-update-dataset-permissions-with-apis).

fabric_api-1.0.0/powerbi_api/__init__.py

@@ -0,0 +1,12 @@
+from .auth import Auth
+from .workspace import Workspace
+from .dataset import Dataset
+from .report import Report
+from .dataflow import Dataflow
+from .capacity import Capacity
+from .admin import Admin
+from .operations import Operations
+from .kql import KQLDatabase
+from .lakehouse import Lakehouse
+
+__version__ = "1.0.0"

fabric_api-1.0.0/powerbi_api/admin.py

@@ -0,0 +1,42 @@
+import requests
+import json
+from typing import Dict
+
+class Admin:
+
+    def __init__(self, token: str):
+        """
+        Initialize variables for Power BI Admin API interactions.
+
+        Args:
+            token (str): The bearer token for authorization.
+        """
+        self.main_url = 'https://api.powerbi.com/v1.0/myorg/admin'
+        self.token = token
+        self.headers = {'Authorization': f'Bearer {self.token}'}
+        
+
+    def get_report_users_as_admin(self, report_id: str) -> Dict:
+        """
+        Retrieves a list of users with access to a specific report as an administrator.
+
+        Args:
+            report_id (str): The ID of the report to get users for.
+
+        Returns:
+            Dict: A dictionary containing the status message and content (list of users).
+        """
+        request_url = f'{self.main_url}/reports/{report_id}/users'
+        
+        r = requests.get(url=request_url, headers=self.headers)
+
+        status = r.status_code
+        response = json.loads(r.content)
+
+        if status == 200:
+            return {'message': 'Success', 'content': response.get('value', [])}
+        else:
+            error_message = response.get('error', {}).get('message', 'Unknown error')
+            return {'message': {'error': error_message, 'status_code': status}, 'content': ''}
+
+

fabric_api-1.0.0/powerbi_api/auth.py

@@ -0,0 +1,75 @@
+from azure.identity import ClientSecretCredential, InteractiveBrowserCredential, TokenCachePersistenceOptions
+
+class Auth:
+
+    def __init__(self, tenant_id: str, client_id: str, client_secret: str):
+        """
+        Initialize variables.
+
+        Args:
+            tenant_id (str, optional): tenant ID.
+            client_id (str, optional): client ID (app registration).
+            client_secret (str, optional): client secret/credentials (app registration).
+        """
+        self.tenant_id = tenant_id
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+    def get_token(self, service: str = 'pbi') -> str:
+        """
+        Generates the bearer token to be used on Power BI or Fabric REST API requests.
+
+        Authenticates using a service principal (app account).
+
+        Args:
+            service (str, optional): which service to get token to: pbi or fabric.
+
+        Returns:
+            str: token for authorization.
+        """
+        if service == 'pbi':
+            scope = 'https://analysis.windows.net/powerbi/api/.default'
+        elif service == 'fabric':
+            scope = 'https://api.fabric.microsoft.com/.default'
+        else:
+            raise ValueError("Invalid service specified. Choose 'pbi' or 'fabric'.")
+
+        auth = ClientSecretCredential(
+                    authority = 'https://login.microsoftonline.com/',
+                    tenant_id = self.tenant_id,
+                    client_id = self.client_id,
+                    client_secret = self.client_secret)
+
+        response = auth.get_token(scope)
+        access_token = response.token
+
+        return access_token
+
+    def get_token_for_user(self, service: str = 'pbi') -> str:
+        """
+        Generates the bearer token to be used on Microsoft REST API requests.
+
+        Authenticates interactively (user account).
+
+        Args:
+            service (str, optional): which service to get token to: pbi, fabric or azure.
+
+        Returns:
+            str: token for authorization.
+        """
+        if service == 'pbi':
+            scope = 'https://analysis.windows.net/powerbi/api/.default'
+        elif service == 'fabric':
+            scope = 'https://api.fabric.microsoft.com/.default'
+        elif service == 'azure':
+            scope = 'https://management.azure.com/.default'
+        else:
+            raise ValueError("Invalid service specified. Choose 'pbi', 'fabric' or'azure'.")
+
+        auth = InteractiveBrowserCredential(cache_persistence_options=TokenCachePersistenceOptions())
+
+        response = auth.get_token(scope)
+        access_token = response.token
+
+        return access_token
+