semantic-link-labs 0.8.2__py3-none-any.whl → 0.8.4__py3-none-any.whl

sempy_labs/_workspaces.py

@@ -14,6 +14,8 @@ def delete_user_from_workspace(email_address: str, workspace: Optional[str] = No
     """
     Removes a user from a workspace.
 
+    This is a wrapper function for the following API: `Groups - Delete User In Group <https://learn.microsoft.com/rest/api/power-bi/groups/delete-user-in-group`_.
+
     Parameters
     ----------
     email_address : str
@@ -45,6 +47,8 @@ def update_workspace_user(
     """
     Updates a user's role within a workspace.
 
+    This is a wrapper function for the following API: `Groups - Update Group User <https://learn.microsoft.com/rest/api/power-bi/groups/update-group-user`_.
+
     Parameters
     ----------
     email_address : str
@@ -95,6 +99,8 @@ def list_workspace_users(workspace: Optional[str] = None) -> pd.DataFrame:
     """
     A list of all the users of a workspace and their roles.
 
+    This is a wrapper function for the following API: `Workspaces - List Workspace Role Assignments <https://learn.microsoft.com/rest/api/fabric/core/workspaces/list-workspace-role-assignments`_.
+
     Parameters
     ----------
     workspace : str, default=None
@@ -142,6 +148,8 @@ def add_user_to_workspace(
     """
     Adds a user to a workspace.
 
+    This is a wrapper function for the following API: `Groups - Add Group User <https://learn.microsoft.com/rest/api/power-bi/groups/add-group-user`_.
+
     Parameters
     ----------
     email_address : str
@@ -196,6 +204,8 @@ def assign_workspace_to_capacity(capacity_name: str, workspace: Optional[str] =
     """
     Assigns a workspace to a capacity.
 
+    This is a wrapper function for the following API: `Workspaces - Assign To Capacity <https://learn.microsoft.com/rest/api/fabric/core/workspaces/assign-to-capacity`_.
+
     Parameters
     ----------
     capacity_name : str
@@ -228,6 +238,8 @@ def unassign_workspace_from_capacity(workspace: Optional[str] = None):
     """
     Unassigns a workspace from its assigned capacity.
 
+    This is a wrapper function for the following API: `Workspaces - Unassign From Capacity <https://learn.microsoft.com/rest/api/fabric/core/workspaces/unassign-from-capacity`_.
+
     Parameters
     ----------
     workspace : str, default=None
@@ -236,7 +248,6 @@ def unassign_workspace_from_capacity(workspace: Optional[str] = None):
         or if no lakehouse attached, resolves to the workspace of the notebook.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/core/workspaces/unassign-from-capacity?tabs=HTTP
     (workspace, workspace_id) = resolve_workspace_name_and_id(workspace)
 
     client = fabric.FabricRestClient()
@@ -253,6 +264,8 @@ def list_workspace_role_assignments(workspace: Optional[str] = None) -> pd.DataF
     """
     Shows the members of a given workspace.
 
+    This is a wrapper function for the following API: `Workspaces - List Workspace Role Assignments <https://learn.microsoft.com/rest/api/fabric/core/workspaces/list-workspace-role-assignments`_.
+
     Parameters
     ----------
     workspace : str, default=None

sempy_labs/admin/__init__.py

@@ -12,6 +12,7 @@ from sempy_labs.admin._basic_functions import (
     list_access_entities,
     list_workspace_access_details,
     list_items,
+    list_activity_events,
 )
 from sempy_labs.admin._domains import (
     list_domains,
@@ -50,4 +51,5 @@ __all__ = [
     "unassign_workspaces_from_capacity",
     "list_external_data_shares",
     "revoke_external_data_share",
+    "list_activity_events",
 ]

sempy_labs/admin/_basic_functions.py

@@ -1,5 +1,5 @@
 import sempy.fabric as fabric
-from typing import Optional, List, Union
+from typing import Optional, List, Union, Tuple
 from uuid import UUID
 import sempy_labs._icons as icons
 from sempy.fabric.exceptions import FabricHTTPException
@@ -7,22 +7,29 @@ from sempy_labs._helper_functions import (
     resolve_workspace_name_and_id,
     pagination,
 )
-import datetime
 import numpy as np
 import pandas as pd
 import time
+import urllib.parse
+from datetime import datetime
 
 
 def list_workspaces(
-    top: Optional[int] = 5000, skip: Optional[int] = None
+    top: Optional[int] = 5000,
+    filter: Optional[str] = None,
+    skip: Optional[int] = None,
 ) -> pd.DataFrame:
     """
     Lists workspaces for the organization. This function is the admin version of list_workspaces.
 
+    This is a wrapper function for the following API: `Admin - Groups GetGroupsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/groups-get-groups-as-admin>`_.
+
     Parameters
     ----------
     top : int, default=5000
         Returns only the first n results. This parameter is mandatory and must be in the range of 1-5000.
+    filter : str, default=None
+        Returns a subset of a results based on `Odata filter <https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptions>`_ query parameter condition.
     skip : int, default=None
         Skips the first n results. Use with top to fetch results beyond the first 5000.
 
@@ -49,6 +56,8 @@ def list_workspaces(
     url = f"/v1.0/myorg/admin/groups?$top={top}"
     if skip is not None:
         url = f"{url}&$skip={skip}"
+    if filter is not None:
+        url = f"{url}&$filter={filter}"
 
     client = fabric.PowerBIRestClient()
     response = client.get(url)
@@ -92,6 +101,8 @@ def assign_workspaces_to_capacity(
     """
     Assigns a workspace to a capacity. This function is the admin version.
 
+    This is a wrapper function for the following API: `Admin - Capacities AssignWorkspacesToCapacity <https://learn.microsoft.com/rest/api/power-bi/admin/capacities-assign-workspaces-to-capacity>`_.
+
     Parameters
     ----------
     source_capacity : str
@@ -106,27 +117,25 @@ def assign_workspaces_to_capacity(
     if isinstance(workspace, str):
         workspace = [workspace]
 
-    dfC = fabric.list_capacities()
-    dfC_filt = dfC[dfC["Display Name"] == source_capacity]
-    source_capacity_id = dfC_filt["Id"].iloc[0]
+    dfC = list_capacities()
+    dfC_filt = dfC[dfC["Capacity Name"] == source_capacity]
+    source_capacity_id = dfC_filt["Capacity Id"].iloc[0]
 
-    dfC_filt = dfC[dfC["Display Name"] == target_capacity]
-    target_capacity_id = dfC_filt["Id"].iloc[0]
+    dfC_filt = dfC[dfC["Capacity Name"] == target_capacity]
+    target_capacity_id = dfC_filt["Capacity Id"].iloc[0]
 
     if workspace is None:
-        workspaces = fabric.list_workspaces(
-            filter=f"capacityId eq '{source_capacity_id.upper()}'"
-        )["Id"].values
+        dfW = list_workspaces()
+        dfW = dfW[dfW["Capacity Id"].str.upper() == source_capacity_id.upper()]
+        workspaces = dfW["Id"].tolist()
     else:
-        dfW = fabric.list_workspaces()
-        workspaces = dfW[dfW["Name"].isin(workspace)]["Id"].values
+        dfW = list_workspaces()
+        workspaces = dfW[dfW["Name"].isin(workspace)]["Id"].tolist()
 
     workspaces = np.array(workspaces)
     batch_size = 999
     for i in range(0, len(workspaces), batch_size):
         batch = workspaces[i : i + batch_size].tolist()
-        batch_length = len(batch)
-        start_time = datetime.datetime.now()
         request_body = {
             "capacityMigrationAssignments": [
                 {
@@ -144,10 +153,6 @@ def assign_workspaces_to_capacity(
 
         if response.status_code != 200:
             raise FabricHTTPException(response)
-        end_time = datetime.datetime.now()
-        print(
-            f"Total time for assigning {str(batch_length)} workspaces is {str((end_time - start_time).total_seconds())}"
-        )
     print(
         f"{icons.green_dot} The workspaces have been assigned to the '{target_capacity}' capacity."
     )
@@ -157,8 +162,7 @@ def list_capacities() -> pd.DataFrame:
     """
     Shows the a list of capacities and their properties. This function is the admin version.
 
-    Parameters
-    ----------
+    This is a wrapper function for the following API: `Admin - Get Capacities As Admin <https://learn.microsoft.com/rest/api/power-bi/admin/get-capacities-as-admin>`_.
 
     Returns
     -------
@@ -196,14 +200,14 @@ def list_tenant_settings() -> pd.DataFrame:
     """
     Lists all tenant settings.
 
+    This is a wrapper function for the following API: `Tenants - List Tenant Settings <https://learn.microsoft.com/rest/api/fabric/admin/tenants/list-tenant-settings>`_.
+
     Returns
     -------
     pandas.DataFrame
         A pandas dataframe showing the tenant settings.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/tenants/list-tenant-settings?tabs=HTTP
-
     client = fabric.FabricRestClient()
     response = client.get("/v1/admin/tenantsettings")
 
@@ -269,7 +273,9 @@ def _list_capacities_meta() -> pd.DataFrame:
 
 def unassign_workspaces_from_capacity(workspaces: str | List[str]):
     """
-    Unassigns workspace(s) from their capacity. This function is the admin version of list_workspaces.
+    Unassigns workspace(s) from their capacity.
+
+    This is a wrapper function for the following API: `Admin - Capacities UnassignWorkspacesFromCapacity <https://learn.microsoft.com/rest/api/power-bi/admin/capacities-unassign-workspaces-from-capacity>`_.
 
     Parameters
     ----------
@@ -277,8 +283,6 @@ def unassign_workspaces_from_capacity(workspaces: str | List[str]):
         The Fabric workspace name(s).
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/power-bi/admin/capacities-unassign-workspaces-from-capacity
-
     if isinstance(workspaces, str):
         workspaces = [workspaces]
 
@@ -300,14 +304,14 @@ def list_external_data_shares():
     """
     Lists external data shares in the tenant. This function is for admins.
 
+    This is a wrapper function for the following API: `External Data Shares - List External Data Shares <https://learn.microsoft.com/rest/api/fabric/admin/external-data-shares/list-external-data-shares>`_.
+
     Returns
     -------
     pandas.DataFrame
         A pandas dataframe showing a list of external data shares in the tenant.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/external-data-shares/list-external-data-shares?tabs=HTTP
-
     df = pd.DataFrame(
         columns=[
             "External Data Share Id",
@@ -362,6 +366,8 @@ def revoke_external_data_share(
     """
     Revokes the specified external data share. Note: This action cannot be undone.
 
+    This is a wrapper function for the following API: `External Data Shares - Revoke External Data Share <https://learn.microsoft.com/rest/api/fabric/admin/external-data-shares/revoke-external-data-share`_.
+
     Parameters
     ----------
     external_data_share_id : UUID
@@ -372,8 +378,6 @@ def revoke_external_data_share(
         The Fabric workspace name.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/external-data-shares/revoke-external-data-share?tabs=HTTP
-
     (workspace, workspace_id) = resolve_workspace_name_and_id(workspace)
 
     client = fabric.FabricRestClient()
@@ -391,23 +395,23 @@ def revoke_external_data_share(
 
 def list_capacities_delegated_tenant_settings(
     return_dataframe: bool = True,
-) -> Optional[pd.DataFrame | dict]:
+) -> pd.DataFrame | dict:
     """
     Returns list of tenant setting overrides that override at the capacities.
 
+    This is a wrapper function for the following API: `Tenants - List Capacities Tenant Settings Overrides <https://learn.microsoft.com/rest/api/fabric/admin/tenants/list-capacities-tenant-settings-overrides`_.
+
     Parameters
     ----------
     return_dataframe : bool, default=True
-        If True, returns a dataframe. If False, returns a dictionary
+        If True, returns a dataframe. If False, returns a dictionary.
 
     Returns
     -------
-    pandas.DataFrame
+    pandas.DataFrame | dict
         A pandas dataframe showing a list of tenant setting overrides that override at the capacities.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/tenants/list-capacities-tenant-settings-overrides?tabs=HTTP
-
     df = pd.DataFrame(
         columns=[
             "Capacity Id",
@@ -488,7 +492,8 @@ def scan_workspaces(
     workspace: Optional[str | List[str]] = None,
 ) -> dict:
 
-    workspace = fabric.resolve_workspace_name(workspace)
+    if workspace is None:
+        workspace = fabric.resolve_workspace_name()
 
     if isinstance(workspace, str):
         workspace = [workspace]
@@ -525,14 +530,14 @@ def list_datasets() -> pd.DataFrame:
     """
     Shows a list of datasets for the organization.
 
+    This is a wrapper function for the following API: `Admin - Datasets GetDatasetsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/datasets-get-datasets-as-admin`_.
+
     Returns
     -------
     pandas.DataFrame
         A pandas dataframe showing a list of datasets for the organization.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/power-bi/admin/datasets-get-datasets-as-admin
-
     df = pd.DataFrame(
         columns=[
             "Dataset Id",
@@ -615,6 +620,8 @@ def list_item_access_details(
     """
     Returns a list of users (including groups and service principals) and lists their workspace roles.
 
+    This is a wrapper function for the following API: `Items - List Item Access Details <https://learn.microsoft.com/rest/api/fabric/admin/items/list-item-access-details`_.
+
     Parameters
     ----------
     item_name : str
@@ -632,13 +639,8 @@ def list_item_access_details(
         A pandas dataframe showing a list of users (including groups and service principals) and lists their workspace roles.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/items/list-item-access-details?tabs=HTTP
-
-    workspace = fabric.resolve_workspace_name(workspace)
-    workspace_id = fabric.resolve_workspace_id(workspace)
-    item_id = fabric.resolve_item_id(
-        item_name=item_name, type=type, workspace=workspace
-    )
+    workspace_name, workspace_id = _resolve_workspace_name_and_id(workspace)
+    item_id = _resolve_item_id(item_name=item_name, type=type, workspace=workspace_name)
 
     df = pd.DataFrame(
         columns=[
@@ -684,7 +686,9 @@ def list_access_entities(
     user_email_address: str,
 ) -> pd.DataFrame:
     """
-    Shows a list of permission details for Fabric and PowerBI items the specified user can access.
+    Shows a list of permission details for Fabric and Power BI items the specified user can access.
+
+    This is a wrapper function for the following API: `Users - List Access Entities <https://learn.microsoft.com/rest/api/fabric/admin/users/list-access-entities`_.
 
     Parameters
     ----------
@@ -694,11 +698,9 @@ def list_access_entities(
     Returns
     -------
     pandas.DataFrame
-        A pandas dataframe showing a list of permission details for Fabric and PowerBI items the specified user can access.
+        A pandas dataframe showing a list of permission details for Fabric and Power BI items the specified user can access.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/users/list-access-entities?tabs=HTTP
-
     df = pd.DataFrame(
         columns=[
             "Item Id",
@@ -738,6 +740,8 @@ def list_workspace_access_details(
     """
     Shows a list of users (including groups and Service Principals) that have access to the specified workspace.
 
+    This is a wrapper function for the following API: `Workspaces - List Workspace Access Details <https://learn.microsoft.com/rest/api/fabric/admin/workspaces/list-workspace-access-details`_.
+
     Parameters
     ----------
     workspace : str, default=None
@@ -751,10 +755,7 @@ def list_workspace_access_details(
         A pandas dataframe showing a list of users (including groups and Service Principals) that have access to the specified workspace.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/workspaces/list-workspace-access-details?tabs=HTTP
-
-    workspace_name = fabric.resolve_workspace_name(workspace)
-    workspace_id = fabric.resolve_workspace_id(workspace_name)
+    workspace_name, workspace_id = _resolve_workspace_name_and_id(workspace)
 
     df = pd.DataFrame(
         columns=[
@@ -785,6 +786,32 @@ def list_workspace_access_details(
     return df
 
 
+def _resolve_item_id(
+    item_name: str, type: str, workspace: Optional[str] = None
+) -> UUID:
+
+    workspace_name, workspace_id = _resolve_workspace_name_and_id(workspace)
+    dfI = list_items(workspace=workspace_name, type=type)
+    dfI_filt = dfI[dfI["Item Name"] == item_name]
+
+    if len(dfI_filt) == 0:
+        raise ValueError(
+            f"The '{item_name}' {type} does not exist within the '{workspace_name}' workspace."
+        )
+
+    return dfI_filt["Item Id"].iloc[0]
+
+
+def _resolve_workspace_name_and_id(workspace: str) -> Tuple[str, UUID]:
+
+    filter_condition = urllib.parse.quote(workspace)
+    dfW_filt = list_workspaces(filter=f"name eq '{filter_condition}'")
+    workspace_name = dfW_filt["Name"].iloc[0]
+    workspace_id = dfW_filt["Id"].iloc[0]
+
+    return workspace_name, workspace_id
+
+
 def list_items(
     capacity_name: Optional[str] = None,
     workspace: Optional[str] = None,
@@ -792,7 +819,9 @@ def list_items(
     type: Optional[str] = None,
 ) -> pd.DataFrame:
     """
-    Shows a list of active Fabric and PowerBI items.
+    Shows a list of active Fabric and Power BI items.
+
+    This is a wrapper function for the following API: `Items - List Items <https://learn.microsoft.com/rest/api/fabric/admin/items/list-items`_.
 
     Parameters
     ----------
@@ -813,8 +842,6 @@ def list_items(
         A pandas dataframe showing a list of active Fabric and Power BI items.
     """
 
-    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/items/list-items?tabs=HTTP
-
     url = "/v1/admin/items?"
 
     df = pd.DataFrame(
@@ -835,8 +862,7 @@ def list_items(
     )
 
     if workspace is not None:
-        workspace = fabric.resolve_workspace_name(workspace)
-        workspace_id = fabric.resolve_workspace_id(workspace)
+        workspace_name, workspace_id = _resolve_workspace_name_and_id(workspace)
         url += f"workspaceId={workspace_id}&"
     if capacity_name is not None:
         dfC = list_capacities()
@@ -886,3 +912,122 @@ def list_items(
             df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
 
     return df
+
+
+def list_activity_events(
+    start_time: str,
+    end_time: str,
+    activity_filter: Optional[str] = None,
+    user_id_filter: Optional[str] = None,
+):
+    """
+    Shows a list of audit activity events for a tenant.
+
+    This is a wrapper function for the following API: `Admin - Get Activity Events <https://learn.microsoft.com/rest/api/power-bi/admin/get-activity-events`_.
+
+    Parameters
+    ----------
+    start_time : str
+        Start date and time of the window for audit event results. Example: "2024-09-25T07:55:00".
+    end_time : str
+        End date and time of the window for audit event results. Example: "2024-09-25T08:55:00".
+    activity_filter : str, default=None
+        Filter value for activities. Example: 'viewreport'.
+    user_id_filter : str, default=None
+        Email address of the user.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of audit activity events for a tenant.
+    """
+
+    start_dt = datetime.strptime(start_time, "%Y-%m-%dT%H:%M:%S")
+    end_dt = datetime.strptime(end_time, "%Y-%m-%dT%H:%M:%S")
+
+    if not start_dt.date() == end_dt.date():
+        raise ValueError(
+            f"{icons.red_dot} Start and End Times must be within the same UTC day. Please refer to the documentation here: https://learn.microsoft.com/rest/api/power-bi/admin/get-activity-events#get-audit-activity-events-within-a-time-window-and-for-a-specific-activity-type-and-user-id-example"
+        )
+
+    df = pd.DataFrame(
+        columns=[
+            "Id",
+            "Record Type",
+            "Creation Time",
+            "Operation",
+            "Organization Id",
+            "User Type",
+            "User Key",
+            "Workload",
+            "Result Status",
+            "User Id",
+            "Client IP",
+            "User Agent",
+            "Activity",
+            "Workspace Name",
+            "Workspace Id",
+            "Object Id",
+            "Request Id",
+            "Object Type",
+            "Object Display Name",
+            "Experience",
+            "Refresh Enforcement Policy",
+        ]
+    )
+
+    tic = "%27"
+    space = "%20"
+    client = fabric.PowerBIRestClient()
+    base_url = "/v1.0/myorg/admin/activityevents"
+    conditions = []
+
+    if activity_filter is not None:
+        conditions.append(f"Activity{space}eq{space}{tic}{activity_filter}{tic}")
+    if user_id_filter is not None:
+        conditions.append(f"UserId{space}eq{space}{tic}{user_id_filter}{tic}")
+
+    filter_value = (
+        f"&$filter={f'{space}and{space}'.join(conditions)}" if conditions else ""
+    )
+
+    full_url = f"{base_url}?startDateTime={tic}{start_time}{tic}&endDateTime={tic}{end_time}{tic}{filter_value}"
+    response = client.get(full_url)
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+
+    responses = pagination(client, response)
+
+    for r in responses:
+        for i in r.get("activityEventEntities", []):
+            new_data = {
+                "Id": i.get("id"),
+                "Record Type": i.get("RecordType"),
+                "Creation Time": i.get("CreationTime"),
+                "Operation": i.get("Operation"),
+                "Organization Id": i.get("OrganizationId"),
+                "User Type": i.get("UserType"),
+                "User Key": i.get("UserKey"),
+                "Workload": i.get("Workload"),
+                "Result Status": i.get("ResultStatus"),
+                "User Id": i.get("UserId"),
+                "Client IP": i.get("ClientIP"),
+                "User Agent": i.get("UserAgent"),
+                "Activity": i.get("Activity"),
+                "Workspace Name": i.get("WorkSpaceName"),
+                "Workspace Id": i.get("WorkspaceId"),
+                "Object Id": i.get("ObjectId"),
+                "Request Id": i.get("RequestId"),
+                "Object Type": i.get("ObjectType"),
+                "Object Display Name": i.get("ObjectDisplayName"),
+                "Experience": i.get("Experience"),
+                "Refresh Enforcement Policy": i.get("RefreshEnforcementPolicy"),
+            }
+            df = pd.concat(
+                [df, pd.DataFrame(new_data, index=[0])],
+                ignore_index=True,
+            )
+
+    df["Creation Time"] = pd.to_datetime(df["Creation Time"])
+
+    return df