semantic-link-labs 0.12.8__py3-none-any.whl

sempy_labs/admin/__init__.py

@@ -0,0 +1,170 @@
+from ._users import (
+    list_access_entities,
+    list_user_subscriptions,
+)
+from ._workspaces import (
+    add_user_to_workspace,
+    delete_user_from_workspace,
+    restore_deleted_workspace,
+    list_orphaned_workspaces,
+)
+from ._artifacts import (
+    list_unused_artifacts,
+)
+from ._shared import (
+    list_widely_shared_artifacts,
+)
+from ._datasets import (
+    list_datasets,
+    list_dataset_users,
+)
+from ._apps import (
+    list_apps,
+    list_app_users,
+)
+from ._reports import (
+    list_reports,
+    list_report_users,
+    list_report_subscriptions,
+)
+from ._activities import (
+    list_activity_events,
+)
+from ._scanner import (
+    scan_workspaces,
+)
+from ._capacities import (
+    patch_capacity,
+    list_capacities,
+    get_capacity_assignment_status,
+    get_capacity_state,
+    list_capacity_users,
+    get_refreshables,
+)
+from ._tenant import (
+    list_tenant_settings,
+    delete_capacity_tenant_setting_override,
+    update_tenant_setting,
+    update_capacity_tenant_setting_override,
+    list_workspaces_tenant_settings_overrides,
+    list_capacity_tenant_settings_overrides,
+    list_capacities_delegated_tenant_settings,
+    list_domain_tenant_settings_overrides,
+)
+from ._basic_functions import (
+    assign_workspaces_to_capacity,
+    unassign_workspaces_from_capacity,
+    list_workspaces,
+    list_workspace_access_details,
+    list_modified_workspaces,
+    list_workspace_users,
+)
+from ._domains import (
+    list_domains,
+    list_domain_workspaces,
+    assign_domain_workspaces,
+    assign_domain_workspaces_by_capacities,
+    create_domain,
+    update_domain,
+    delete_domain,
+    resolve_domain_id,
+    unassign_domain_workspaces,
+    unassign_all_domain_workspaces,
+)
+from ._items import (
+    list_item_access_details,
+    list_items,
+)
+from ._external_data_share import (
+    list_external_data_shares,
+    revoke_external_data_share,
+)
+from ._git import (
+    list_git_connections,
+)
+from ._dataflows import (
+    export_dataflow,
+)
+from ._tags import (
+    list_tags,
+    create_tags,
+    delete_tag,
+)
+from ._tenant_keys import (
+    list_tenant_keys,
+    rotate_tenant_key,
+)
+from ._sharing_links import (
+    remove_all_sharing_links,
+    remove_sharing_links,
+)
+from ._labels import (
+    bulk_set_labels,
+    bulk_remove_labels,
+)
+
+__all__ = [
+    "list_items",
+    "list_workspace_access_details",
+    "list_access_entities",
+    "list_item_access_details",
+    "list_datasets",
+    "list_workspaces",
+    "assign_workspaces_to_capacity",
+    "list_capacities",
+    "list_tenant_settings",
+    "list_domains",
+    "list_domain_workspaces",
+    "assign_domain_workspaces",
+    "assign_domain_workspaces_by_capacities",
+    "create_domain",
+    "update_domain",
+    "delete_domain",
+    "resolve_domain_id",
+    "unassign_domain_workspaces",
+    "unassign_all_domain_workspaces",
+    "list_capacities_delegated_tenant_settings",
+    "unassign_workspaces_from_capacity",
+    "list_external_data_shares",
+    "revoke_external_data_share",
+    "list_activity_events",
+    "list_modified_workspaces",
+    "list_git_connections",
+    "list_reports",
+    "get_capacity_assignment_status",
+    "scan_workspaces",
+    "get_capacity_state",
+    "list_apps",
+    "list_app_users",
+    "list_dataset_users",
+    "list_report_users",
+    "patch_capacity",
+    "list_workspace_users",
+    "list_widely_shared_artifacts",
+    "delete_capacity_tenant_setting_override",
+    "update_tenant_setting",
+    "update_capacity_tenant_setting_override",
+    "list_workspaces_tenant_settings_overrides",
+    "list_capacity_tenant_settings_overrides",
+    "list_capacities_delegated_tenant_settings",
+    "list_domain_tenant_settings_overrides",
+    "list_unused_artifacts",
+    "add_user_to_workspace",
+    "delete_user_from_workspace",
+    "restore_deleted_workspace",
+    "list_orphaned_workspaces",
+    "list_capacity_users",
+    "list_user_subscriptions",
+    "list_report_subscriptions",
+    "get_refreshables",
+    "export_dataflow",
+    "list_tags",
+    "create_tags",
+    "delete_tag",
+    "list_tenant_keys",
+    "rotate_tenant_key",
+    "remove_all_sharing_links",
+    "remove_sharing_links",
+    "bulk_set_labels",
+    "bulk_remove_labels",
+]

sempy_labs/admin/_activities.py

@@ -0,0 +1,167 @@
+import pandas as pd
+from typing import Optional
+from dateutil.parser import parse as dtparser
+from sempy._utils._log import log
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+import sempy_labs._icons as icons
+
+
+@log
+def list_activity_events(
+    start_time: str,
+    end_time: str,
+    activity_filter: Optional[str] = None,
+    user_id_filter: Optional[str] = None,
+    return_dataframe: bool = True,
+) -> pd.DataFrame | dict:
+    """
+    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>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    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.
+    return_dataframe : bool, default=True
+        If True the response is a pandas.DataFrame. If False returns the original Json. Default True
+
+    Returns
+    -------
+    pandas.DataFrame | dict
+        A pandas dataframe or json showing a list of audit activity events for a tenant.
+    """
+    start_dt = dtparser(start_time)
+    end_dt = dtparser(end_time)
+
+    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"
+        )
+
+    columns = {
+        "Id": "string",
+        "Record Type": "string",
+        "Creation Time": "datetime",
+        "Operation": "string",
+        "Organization Id": "string",
+        "User Type": "string",
+        "User Key": "string",
+        "Workload": "string",
+        "Result Status": "string",
+        "User Id": "string",
+        "Client IP": "string",
+        "User Agent": "string",
+        "Activity": "string",
+        "Workspace Name": "string",
+        "Workspace Id": "string",
+        "Object Id": "string",
+        "Request Id": "string",
+        "Object Type": "string",
+        "Object Display Name": "string",
+        "Experience": "string",
+        "Refresh Enforcement Policy": "string",
+        "Is Success": "bool",
+        "Activity Id": "string",
+        "Item Name": "string",
+        "Dataset Name": "string",
+        "Report Name": "string",
+        "Capacity Id": "string",
+        "Capacity Name": "string",
+        "App Name": "string",
+        "Dataset Id": "string",
+        "Report Id": "string",
+        "Artifact Id": "string",
+        "Artifact Name": "string",
+        "Report Type": "string",
+        "App Report Id": "string",
+        "Distribution Method": "string",
+        "Consumption Method": "string",
+        "Artifact Kind": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    response_json = {"activityEventEntities": []}
+    url = f"/v1.0/myorg/admin/activityevents?startDateTime='{start_time}'&endDateTime='{end_time}'"
+
+    conditions = []
+    if activity_filter is not None:
+        conditions.append(f"Activity eq '{activity_filter}'")
+    if user_id_filter is not None:
+        conditions.append(f"UserId eq '{user_id_filter}'")
+
+    if conditions:
+        url += f"&$filter={f' and '.join(conditions)}"
+
+    responses = _base_api(request=url, client="fabric_sp", uses_pagination=True)
+
+    rows = []
+    for r in responses:
+        if return_dataframe:
+            for i in r.get("activityEventEntities", []):
+                rows.append(
+                    {
+                        "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"),
+                        "Is Success": i.get("IsSuccess"),
+                        "Activity Id": i.get("ActivityId"),
+                        "Item Name": i.get("ItemName"),
+                        "Dataset Name": i.get("DatasetName"),
+                        "Report Name": i.get("ReportName"),
+                        "Capacity Id": i.get("CapacityId"),
+                        "Capacity Name": i.get("CapacityName"),
+                        "App Name": i.get("AppName"),
+                        "Dataset Id": i.get("DatasetId"),
+                        "Report Id": i.get("ReportId"),
+                        "Artifact Id": i.get("ArtifactId"),
+                        "Artifact Name": i.get("ArtifactName"),
+                        "Report Type": i.get("ReportType"),
+                        "App Report Id": i.get("AppReportId"),
+                        "Distribution Method": i.get("DistributionMethod"),
+                        "Consumption Method": i.get("ConsumptionMethod"),
+                        "Artifact Kind": i.get("ArtifactKind"),
+                    }
+                )
+        else:
+            response_json["activityEventEntities"].extend(
+                r.get("activityEventEntities")
+            )
+
+    if return_dataframe:
+        if rows:
+            df = pd.DataFrame(rows, columns=list(columns.keys()))
+            _update_dataframe_datatypes(dataframe=df, column_map=columns)
+        return df
+    else:
+        return response_json

sempy_labs/admin/_apps.py

@@ -0,0 +1,145 @@
+import pandas as pd
+from typing import Optional
+from sempy_labs._helper_functions import (
+    _build_url,
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+    _is_valid_uuid,
+)
+from uuid import UUID
+import sempy_labs._icons as icons
+from sempy._utils._log import log
+
+
+@log
+def list_apps(
+    top: Optional[int] = 1000,
+    skip: Optional[int] = None,
+) -> pd.DataFrame:
+    """
+    Shows a list of apps in the organization.
+
+    This is a wrapper function for the following API: `Admin - Apps GetAppsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/apps-get-apps-as-admin>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    top : int, default=1000
+        Returns only the first n results.
+    skip : int, default=None
+        Skips the first n results.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of apps in the organization.
+    """
+
+    columns = {
+        "App Name": "string",
+        "App Id": "string",
+        "Description": "string",
+        "Published By": "string",
+        "Last Update": "datetime_coerce",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    params = {}
+    url = "/v1.0/myorg/admin/apps"
+
+    params["$top"] = top
+
+    if skip is not None:
+        params["$skip"] = skip
+
+    url = _build_url(url, params)
+    response = _base_api(request=url, client="fabric_sp")
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "App Name": v.get("name"),
+                "App Id": v.get("id"),
+                "Description": v.get("description"),
+                "Published By": v.get("publishedBy"),
+                "Last Update": v.get("lastUpdate"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+@log
+def _resolve_app_id(app: str | UUID) -> str:
+    if _is_valid_uuid(app):
+        return app
+    else:
+        df = list_apps()
+        df_filt = df[df["App Name"] == app]
+        if df_filt.empty:
+            raise ValueError(f"{icons.red_dot} The '{app}' app does not exist.")
+        return df_filt["App Id"].iloc[0]
+
+
+@log
+def list_app_users(app: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of users that have access to the specified app.
+
+    This is a wrapper function for the following API: `Admin - Apps GetAppUsersAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/apps-get-app-users-as-admin>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    app : str | uuid.UUID
+        The name or ID of the app.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users that have access to the specified app.
+    """
+
+    app_id = _resolve_app_id(app)
+
+    columns = {
+        "User Name": "string",
+        "Email Address": "string",
+        "App User Access Right": "string",
+        "Identifier": "string",
+        "Graph Id": "string",
+        "Principal Type": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = f"/v1.0/myorg/admin/apps/{app_id}/users"
+    response = _base_api(request=url, client="fabric_sp")
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "User Name": v.get("displayName"),
+                "Email Address": v.get("emailAddress"),
+                "App User Access Right": v.get("appUserAccessRight"),
+                "Identifier": v.get("identifier"),
+                "Graph Id": v.get("graphId"),
+                "Principal Type": v.get("principalType"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df

sempy_labs/admin/_artifacts.py

@@ -0,0 +1,65 @@
+import pandas as pd
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+from uuid import UUID
+from typing import Optional
+from sempy_labs.admin._basic_functions import _resolve_workspace_name_and_id
+from sempy._utils._log import log
+
+
+@log
+def list_unused_artifacts(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
+    """
+    Returns a list of datasets, reports, and dashboards that have not been used within 30 days for the specified workspace.
+
+    This is a wrapper function for the following API: `Admin - Groups GetUnusedArtifactsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/groups-get-unused-artifacts-as-admin>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of datasets, reports, and dashboards that have not been used within 30 days for the specified workspace.
+    """
+
+    (_, workspace_id) = _resolve_workspace_name_and_id(workspace)
+
+    columns = {
+        "Artifact Name": "string",
+        "Artifact Id": "string",
+        "Artifact Type": "string",
+        "Artifact Size in MB": "string",
+        "Created Date Time": "datetime",
+        "Last Accessed Date Time": "datetime",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    responses = _base_api(
+        request=f"/v1.0/myorg/admin/groups/{workspace_id}/unused",
+        client="fabric_sp",
+        uses_pagination=True,
+    )
+
+    rows = []
+    for r in responses:
+        for i in r.get("unusedArtifactEntities", []):
+            rows.append(
+                {
+                    "Artifact Name": i.get("displayName"),
+                    "Artifact Id": i.get("artifactId"),
+                    "Artifact Type": i.get("artifactType"),
+                    "Artifact Size in MB": i.get("artifactSizeInMB"),
+                    "Created Date Time": i.get("createdDateTime"),
+                    "Last Accessed Date Time": i.get("lastAccessedDateTime"),
+                }
+            )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df