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

sempy_labs/admin/_external_data_share.py

@@ -0,0 +1,100 @@
+from uuid import UUID
+import sempy_labs._icons as icons
+import pandas as pd
+from sempy_labs.admin._basic_functions import _resolve_workspace_name_and_id
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+from sempy._utils._log import log
+
+
+@log
+def list_external_data_shares() -> pd.DataFrame:
+    """
+    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.
+    """
+
+    columns = {
+        "External Data Share Id": "string",
+        "Paths": "string",
+        "Creater Principal Id": "string",
+        "Creater Principal Name": "string",
+        "Creater Principal Type": "string",
+        "Creater Principal UPN": "string",
+        "Recipient UPN": "string",
+        "Status": "string",
+        "Expiration Time UTC": "datetime",
+        "Workspace Id": "string",
+        "Item Id": "string",
+        "Invitation URL": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    response = _base_api(request="/v1/admin/items/externalDataShares")
+
+    rows = []
+    for i in response.json().get("value", []):
+        cp = i.get("creatorPrincipal", {})
+        rows.append(
+            {
+                "External Data Share Id": i.get("id"),
+                "Paths": [i.get("paths", [])],
+                "Creater Principal Id": cp.get("id"),
+                "Creater Principal Name": cp.get("displayName"),
+                "Creater Principal Type": cp.get("type"),
+                "Creater Principal UPN": cp.get("userDetails", {}).get(
+                    "userPrincipalName"
+                ),
+                "Recipient UPN": i.get("recipient", {}).get("userPrincipalName"),
+                "Status": i.get("status"),
+                "Expiration Time UTC": i.get("expirationTimeUtc"),
+                "Workspace Id": i.get("workspaceId"),
+                "Item Id": i.get("itemId"),
+                "Invitation URL": i.get("invitationUrl"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+@log
+def revoke_external_data_share(
+    external_data_share_id: UUID, item_id: UUID, workspace: str | UUID
+):
+    """
+    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.UUID
+        The external data share ID.
+    item_id : uuid.UUID, default=None
+        The Item ID
+    workspace : str | uuid.UUID
+        The Fabric workspace name or id.
+    """
+    (workspace, workspace_id) = _resolve_workspace_name_and_id(workspace)
+
+    _base_api(
+        request=f"/v1/admin/workspaces/{workspace_id}/items/{item_id}/externalDataShares/{external_data_share_id}/revoke",
+        method="post",
+    )
+
+    print(
+        f"{icons.green_dot} The '{external_data_share_id}' external data share for the '{item_id}' item within the '{workspace}' workspace has been revoked."
+    )

sempy_labs/admin/_git.py

@@ -0,0 +1,72 @@
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+)
+import pandas as pd
+from sempy_labs.admin._basic_functions import list_workspaces
+from sempy._utils._log import log
+
+
+@log
+def list_git_connections() -> pd.DataFrame:
+    """
+    Shows a list of Git connections.
+
+    This is a wrapper function for the following API: `Workspaces - List Git Connections <https://learn.microsoft.com/rest/api/fabric/admin/workspaces/list-git-connections>`_.
+
+    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 Git connections.
+    """
+
+    columns = {
+        "Workspace Id": "string",
+        "Organization Name": "string",
+        "Owner Name": "string",
+        "Project Name": "string",
+        "Git Provider Type": "string",
+        "Repository Name": "string",
+        "Branch Name": "string",
+        "Directory Name": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    responses = _base_api(
+        request="/v1/admin/workspaces/discoverGitConnections",
+        client="fabric_sp",
+        uses_pagination=True,
+    )
+
+    rows = []
+    for r in responses:
+        for v in r.get("value", []):
+            git = v.get("gitProviderDetails", {})
+            rows.append(
+                {
+                    "Workspace Id": v.get("workspaceId"),
+                    "Organization Name": git.get("organizationName"),
+                    "Owner Name": git.get("ownerName"),
+                    "Project Name": git.get("projectName"),
+                    "Git Provider Type": git.get("gitProviderType"),
+                    "Repository Name": git.get("repositoryName"),
+                    "Branch Name": git.get("branchName"),
+                    "Directory Name": git.get("directoryName"),
+                }
+            )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        dfW = list_workspaces()
+        df = pd.merge(
+            df, dfW[["Id", "Name"]], left_on="Workspace Id", right_on="Id", how="left"
+        )
+        new_col_name = "Workspace Name"
+        df = df.rename(columns={"Name": new_col_name})
+        df.insert(1, new_col_name, df.pop(new_col_name))
+
+        df = df.drop(columns=["Id"])
+
+    return df

sempy_labs/admin/_items.py

@@ -0,0 +1,265 @@
+import pandas as pd
+from typing import Optional, Tuple
+from uuid import UUID
+import sempy_labs._icons as icons
+from sempy_labs.admin._basic_functions import (
+    _resolve_workspace_name_and_id,
+)
+from sempy_labs.admin._capacities import (
+    _resolve_capacity_name_and_id,
+)
+from sempy_labs._helper_functions import (
+    _is_valid_uuid,
+    _build_url,
+    _base_api,
+    _create_dataframe,
+)
+from sempy._utils._log import log
+
+
+@log
+def _resolve_item_id(
+    item: str,
+    type: Optional[str] = None,
+    workspace: Optional[str | UUID] = None,
+) -> UUID:
+    if _is_valid_uuid(item):
+        item_id = item
+
+    else:
+        workspace_id = _resolve_workspace_name_and_id(workspace)[1]
+        dfI = list_items(workspace=workspace_id, type=type)
+        dfI_filt = dfI[dfI["Item Name"] == item]
+
+        if len(dfI_filt) == 0:
+            raise ValueError(
+                f"The '{item}' {type} does not exist within the '{workspace}' workspace or is not of type '{type}'."
+            )
+
+        item_id = dfI_filt["Item Id"].iloc[0]
+
+    return item_id
+
+
+@log
+def _resolve_item_name_and_id(
+    item: str,
+    type: Optional[str] = None,
+    workspace: Optional[str | UUID] = None,
+    **kwargs,
+) -> Tuple[str, UUID]:
+    if "item_name" in kwargs:
+        print(
+            "The 'item_name' parameter has been deprecated. Please replace this parameter with 'item' from the function going forward."
+        )
+        item = item_name
+        del kwargs["item_name"]
+
+    dfI = list_items(workspace=workspace, type=type, item=item)
+
+    if len(dfI) > 1:
+        raise ValueError(
+            f"There are more than 1 item with the name '{item}'. Please specify the 'type' and/or 'workspace' to be more precise."
+        )
+
+    try:
+        item_name = dfI["Item Name"].iloc[0]
+        item_id = dfI["Item Id"].iloc[0]
+    except Exception:
+        raise ValueError(
+            f"The '{item}' {type} does not exist within the '{workspace}' workspace or is not of type '{type}'."
+        )
+
+    return item_name, item_id
+
+
+@log
+def list_items(
+    capacity: Optional[str | UUID] = None,
+    workspace: Optional[str | UUID] = None,
+    state: Optional[str] = None,
+    type: Optional[str] = None,
+    item: Optional[str | UUID] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """
+    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>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    capacity : str | uuid.UUID, default=None
+        The capacity name or id.
+    workspace : str | uuid.UUID, default=None
+        The Fabric workspace name or id.
+        Defaults to None which looks into all the workspaces.
+    state : str, default=None
+        The item state.
+    type : str, default=None
+        The item type.
+    item : str | UUID, default=None
+        Item id or name to filter the list.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of active Fabric and Power BI items.
+    """
+    if "capacity_name" in kwargs:
+        print(
+            "The 'capacity_name' parameter has been deprecated. Please replace this parameter with 'capacity' from the function going forward."
+        )
+        capacity = kwargs["capacity_name"]
+        del kwargs["capacity_name"]
+
+    columns = {
+        "Item Id": "string",
+        "Item Name": "string",
+        "Type": "string",
+        "Description": "string",
+        "State": "string",
+        "Last Updated Date": "string",
+        "Creator Principal Id": "string",
+        "Creator Principal Display Name": "string",
+        "Creator Principal Type": "string",
+        "Creator User Principal Name": "string",
+        "Workspace Id": "string",
+        "Capacity Id": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    params = {}
+    url = "/v1/admin/items"
+
+    if capacity is not None:
+        params["capacityId"] = _resolve_capacity_name_and_id(capacity)[1]
+
+    if workspace is not None:
+        params["workspaceId"] = _resolve_workspace_name_and_id(workspace)[1]
+
+    if state is not None:
+        params["state"] = state
+
+    if type is not None:
+        params["type"] = type
+
+    url = _build_url(url, params)
+
+    responses = _base_api(request=url, client="fabric_sp", uses_pagination=True)
+
+    rows = []
+    for r in responses:
+        for v in r.get("itemEntities", []):
+            rows.append(
+                {
+                    "Item Id": v.get("id"),
+                    "Type": v.get("type"),
+                    "Item Name": v.get("name"),
+                    "Description": v.get("description"),
+                    "State": v.get("state"),
+                    "Last Updated Date": v.get("lastUpdatedDate"),
+                    "Creator Principal Id": v.get("creatorPrincipal", {}).get("id"),
+                    "Creator Principal Display Name": v.get("creatorPrincipal", {}).get(
+                        "displayName"
+                    ),
+                    "Creator Principal Type": v.get("creatorPrincipal", {}).get("type"),
+                    "Creator User Principal Name": v.get("creatorPrincipal", {})
+                    .get("userDetails", {})
+                    .get("userPrincipalName"),
+                    "Workspace Id": v.get("workspaceId"),
+                    "Capacity Id": v.get("capacityId"),
+                }
+            )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    if item is not None:
+        if _is_valid_uuid(item):
+            df = df[df["Item Id"] == item]
+        else:
+            df = df[df["Item Name"] == item]
+
+    return df
+
+
+@log
+def list_item_access_details(
+    item: str | UUID,
+    type: str,
+    workspace: Optional[str | UUID] = None,
+) -> pd.DataFrame:
+    """
+    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>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    item : str
+        Name or id of the Fabric item.
+    type : str
+        Type of Fabric item.
+    workspace : str | uuid.UUID, default=None
+        The Fabric workspace name or id.
+        Defaults to None which resolves to the workspace of the attached lakehouse
+        or if no lakehouse attached, resolves to the workspace of the notebook.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users (including groups and service principals) and lists their workspace roles.
+    """
+
+    (workspace_name, workspace_id) = _resolve_workspace_name_and_id(workspace)
+    (item_name, item_id) = _resolve_item_name_and_id(
+        item=item, type=type, workspace=workspace_name
+    )
+
+    columns = {
+        "User Id": "string",
+        "User Name": "string",
+        "User Type": "string",
+        "User Principal Name": "string",
+        "Item Name": "string",
+        "Item Type": "string",
+        "Item Id": "string",
+        "Permissions": "string",
+        "Additional Permissions": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    response = _base_api(
+        request=f"/v1/admin/workspaces/{workspace_id}/items/{item_id}/users?type={type}",
+        client="fabric_sp",
+    )
+
+    rows = []
+    for v in response.json().get("accessDetails", []):
+        rows.append(
+            {
+                "User Id": v.get("principal", {}).get("id"),
+                "User Name": v.get("principal", {}).get("displayName"),
+                "User Type": v.get("principal", {}).get("type"),
+                "User Principal Name": v.get("principal", {})
+                .get("userDetails", {})
+                .get("userPrincipalName"),
+                "Item Type": v.get("itemAccessDetails", {}).get("type"),
+                "Permissions": v.get("itemAccessDetails", {}).get("permissions"),
+                "Additional Permissions": v.get("itemAccessDetails", {}).get(
+                    "additionalPermissions"
+                ),
+                "Item Name": item_name,
+                "Item Id": item_id,
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    return df

sempy_labs/admin/_labels.py

@@ -0,0 +1,211 @@
+from typing import Literal, List
+from uuid import UUID
+import sempy_labs._icons as icons
+from sempy_labs.admin._basic_functions import (
+    _resolve_workspace_name_and_id,
+)
+from sempy_labs.admin._items import (
+    list_items,
+)
+from sempy_labs._helper_functions import (
+    _is_valid_uuid,
+    _base_api,
+)
+from sempy._utils._log import log
+
+
+@log
+def bulk_set_labels(
+    items: List[dict],
+    label_id: UUID,
+    assignment_method: Literal["Standard", "Priviledged"] = "Standard",
+):
+    """
+    Sets sensitivity labels on Fabric items.
+
+    Note: Please use the sempy_labs.graph.resolve_sensitivity_label_id function to retrieve label IDs.
+
+    This is a wrapper function for the following API: `Labels - Bulk Set Labels <https://learn.microsoft.com/rest/api/fabric/admin/labels/bulk-set-labels>`_.
+
+    Parameters
+    ----------
+    items : List[dict]
+        A list of dictionaries containing the item details.
+
+        Example 1:
+        items = [
+            {
+            "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a",
+            "type": "Dashboard"
+            },
+            {
+            "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c",
+            "type": "Report"
+            },
+            {
+            "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542e",
+            "type": "SemanticModel"
+            },
+        ]
+
+        Example 2:
+        items = [
+            {
+            "id": "Dashboard 1",
+            "type": "Dashboard",
+            "workspace": "Sales Workspace"
+            },
+            {
+            "id": "Sales Report",
+            "type": "Report",
+            "workspace": "Sales Workspace"
+            },
+            {
+            "id": "KPI Model",
+            "type": "SemanticModel",
+            "workspace": "Workspace 2"
+            },
+        ]
+
+    label_id : uuid.UUID
+        The label ID, which must be in the user's label policy.
+    assignment_method : Literal["Standard", "Priviledged"], default="Standard"
+        Specifies whether the assigned label was set by an automated process or manually. Additional tenant setting property types may be added over time.
+    """
+
+    if assignment_method not in ["Standard", "Priviledged"]:
+        raise ValueError("assignment_method must be either 'Standard' or 'Priviledged'")
+
+    payload = {"items": []}
+    df = list_items()
+
+    for i in items:
+        item = i.get("item")
+        type = i.get("type")
+        workspace = i.get("workspace")
+        if _is_valid_uuid(item):
+            payload["items"].append(
+                {
+                    "id": item,
+                    "type": type,
+                }
+            )
+        else:
+            workspace_id = _resolve_workspace_name_and_id(workspace)[1]
+            df_filtered = df[
+                (df["Item Name"] == item)
+                & (df["Type"] == type)
+                & (df["Workspace Id"] == workspace_id)
+            ]
+            if df_filtered.empty:
+                raise ValueError(
+                    f"The item '{item}' of type '{type}' does not exist in workspace '{workspace}'."
+                )
+            else:
+                payload["items"].append(
+                    {
+                        "id": df_filtered["Item Id"].iloc[0],
+                        "type": type,
+                    }
+                )
+
+    payload["labelId"] = label_id
+    payload["assignmentMethod"] = assignment_method
+
+    _base_api(request="/v1/admin/items/bulkSetLabels", method="post", payload=payload)
+
+    print(
+        f"{icons.green_dot} Labels have been successfully set on the specified items."
+    )
+
+
+@log
+def bulk_remove_labels(
+    items: List[dict],
+):
+    """
+    Removes sensitivity labels from Fabric items.
+
+    This is a wrapper function for the following API: `Labels - Bulk Remove Labels <https://learn.microsoft.com/rest/api/fabric/admin/labels/bulk-remove-labels>`_.
+
+    Parameters
+    ----------
+    items : List[dict]
+        A list of dictionaries containing the item details.
+
+        Example 1:
+        items = [
+            {
+            "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a",
+            "type": "Dashboard"
+            },
+            {
+            "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c",
+            "type": "Report"
+            },
+            {
+            "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542e",
+            "type": "SemanticModel"
+            },
+        ]
+
+        Example 2:
+        items = [
+            {
+            "id": "Dashboard 1",
+            "type": "Dashboard",
+            "workspace": "Sales Workspace"
+            },
+            {
+            "id": "Sales Report",
+            "type": "Report",
+            "workspace": "Sales Workspace"
+            },
+            {
+            "id": "KPI Model",
+            "type": "SemanticModel",
+            "workspace": "Workspace 2"
+            },
+        ]
+    """
+
+    payload = {"items": []}
+    df = list_items()
+
+    for i in items:
+        item = i.get("item")
+        type = i.get("type")
+        workspace = i.get("workspace")
+        if _is_valid_uuid(item):
+            payload["items"].append(
+                {
+                    "id": item,
+                    "type": type,
+                }
+            )
+        else:
+            workspace_id = _resolve_workspace_name_and_id(workspace)[1]
+            df_filtered = df[
+                (df["Item Name"] == item)
+                & (df["Type"] == type)
+                & (df["Workspace Id"] == workspace_id)
+            ]
+            if df_filtered.empty:
+                raise ValueError(
+                    f"The item '{item}' of type '{type}' does not exist in workspace '{workspace}'."
+                )
+            else:
+                payload["items"].append(
+                    {
+                        "id": df_filtered["Item Id"].iloc[0],
+                        "type": type,
+                    }
+                )
+
+    _base_api(
+        request="/v1/admin/items/bulkRemoveLabels", method="post", payload=payload
+    )
+
+    print(
+        f"{icons.green_dot} Labels have been successfully removed from the specified items."
+    )