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

sempy_labs/admin/_reports.py

@@ -0,0 +1,241 @@
+import pandas as pd
+from typing import Optional
+from sempy_labs._helper_functions import (
+    _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_reports(
+    top: Optional[int] = None,
+    skip: Optional[int] = None,
+    filter: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Shows a list of reports for the organization.
+
+    This is a wrapper function for the following API: `Admin - Reports GetReportsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/reports-get-reports-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=None
+        Returns only the first n results.
+    skip : int, default=None
+        Skips the first n results.
+    filter : str, default=None
+        Returns a subset of a results based on Odata filter query parameter condition.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of reports for the organization.
+    """
+
+    columns = {
+        "Report Id": "string",
+        "Report Name": "string",
+        "Type": "string",
+        "Web URL": "string",
+        "Embed URL": "string",
+        "Dataset Id": "string",
+        "Created Date": "datetime_coerce",
+        "Modified Date": "datetime_coerce",
+        "Created By": "string",
+        "Modified By": "string",
+        "Sensitivity Label Id": "string",
+        "Users": "string",
+        "Subscriptions": "string",
+        "Workspace Id": "string",
+        "Report Flags": "int_fillna",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = "/v1.0/myorg/admin/reports?"
+    if top is not None:
+        url += f"$top={top}&"
+    if skip is not None:
+        url += f"$skip={skip}&"
+    if filter is not None:
+        url += f"$filter={filter}&"
+
+    url.rstrip("$").rstrip("?")
+    response = _base_api(request=url, client="fabric_sp")
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "Report Id": v.get("id"),
+                "Report Name": v.get("name"),
+                "Type": v.get("reportType"),
+                "Web URL": v.get("webUrl"),
+                "Embed URL": v.get("embedUrl"),
+                "Dataset Id": v.get("datasetId"),
+                "Created Date": v.get("createdDateTime"),
+                "Modified Date": v.get("modifiedDateTime"),
+                "Created By": v.get("createdBy"),
+                "Modified By": v.get("modifiedBy"),
+                "Sensitivity Label Id": v.get("sensitivityLabel", {}).get("labelId"),
+                "Users": v.get("users"),
+                "Subscriptions": v.get("subscriptions"),
+                "Workspace Id": v.get("workspaceId"),
+                "Report Flags": v.get("reportFlags"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+@log
+def _resolve_report_id(report: str | UUID) -> str:
+    if _is_valid_uuid(report):
+        return report
+    else:
+        df = list_reports()
+        df_filt = df[df["Report Name"] == report]
+        if df_filt.empty:
+            raise ValueError(f"{icons.red_dot} The '{report}' report does not exist.")
+        return df_filt["Report Id"].iloc[0]
+
+
+@log
+def list_report_users(report: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of users that have access to the specified report.
+
+    This is a wrapper function for the following API: `Admin - Reports GetDatasetUsersAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/reports-get-report-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
+    ----------
+    report : str | uuid.UUID
+        The name or ID of the report.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users that have access to the specified report.
+    """
+
+    report_id = _resolve_report_id(report)
+
+    columns = {
+        "User Name": "string",
+        "Email Address": "string",
+        "Report User Access Right": "string",
+        "Identifier": "string",
+        "Graph Id": "string",
+        "Principal Type": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = f"/v1.0/myorg/admin/reports/{report_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"),
+                "Report User Access Right": v.get("reportUserAccessRight"),
+                "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
+
+
+@log
+def list_report_subscriptions(report: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of report subscriptions along with subscriber details. This is a preview API call.
+
+    This is a wrapper function for the following API: `Admin - Reports GetReportSubscriptionsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/reports-get-report-subscriptions-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
+    ----------
+    report : str | uuid.UUID
+        The name or ID of the report.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of report subscriptions along with subscriber details. This is a preview API call.
+    """
+
+    report_id = _resolve_report_id(report)
+
+    columns = {
+        "Subscription Id": "string",
+        "Title": "string",
+        "Artifact Id": "string",
+        "Artifact Name": "string",
+        "Sub Artifact Name": "string",
+        "Artifact Type": "string",
+        "Is Enabled": "bool",
+        "Frequency": "string",
+        "Start Date": "datetime",
+        "End Date": "string",
+        "Link To Content": "bool",
+        "Preview Image": "bool",
+        "Attachment Format": "string",
+        "Users": "list",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    response = _base_api(
+        request=f"/v1.0/myorg/admin/reports/{report_id}/subscriptions",
+        client="fabric_sp",
+    )
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "Subscription Id": v.get("id"),
+                "Title": v.get("title"),
+                "Artifact Id": v.get("artifactId"),
+                "Artifact Name": v.get("artifactDisplayName"),
+                "Sub Artifact Name": v.get("subArtifactDisplayName"),
+                "Artifact Type": v.get("artifactType"),
+                "Is Enabled": v.get("isEnabled"),
+                "Frequency": v.get("frequency"),
+                "Start Date": v.get("startDate"),
+                "End Date": v.get("endDate"),
+                "Link To Content": v.get("linkToContent"),
+                "Preview Image": v.get("previewImage"),
+                "Attachment Format": v.get("attachmentFormat"),
+                "Users": v.get("users", []),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df

sempy_labs/admin/_scanner.py

@@ -0,0 +1,118 @@
+from typing import Optional, List
+from uuid import UUID
+from sempy.fabric.exceptions import FabricHTTPException
+import time
+import sempy_labs._icons as icons
+from sempy_labs.admin._basic_functions import list_workspaces
+from sempy._utils._log import log
+from sempy_labs._helper_functions import (
+    _base_api,
+    _is_valid_uuid,
+    _build_url,
+    resolve_workspace_name,
+)
+
+
+@log
+def scan_workspaces(
+    data_source_details: bool = False,
+    dataset_schema: bool = False,
+    dataset_expressions: bool = False,
+    lineage: bool = False,
+    artifact_users: bool = False,
+    workspace: Optional[str | List[str] | UUID | List[UUID]] = None,
+) -> dict:
+    """
+    Gets the scan result for the specified scan.
+
+    This is a wrapper function for the following APIs:
+        `Admin - WorkspaceInfo PostWorkspaceInfo <https://learn.microsoft.com/rest/api/power-bi/admin/workspace-info-post-workspace-info>`_.
+        `Admin - WorkspaceInfo GetScanStatus <https://learn.microsoft.com/rest/api/power-bi/admin/workspace-info-get-scan-status>`_.
+        `Admin - WorkspaceInfo GetScanResult <https://learn.microsoft.com/rest/api/power-bi/admin/workspace-info-get-scan-result>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    data_source_details : bool, default=False
+        Whether to return dataset expressions (DAX and Mashup queries). If you set this parameter to true, you must fully enable metadata scanning in order for data to be returned. For more information, see Enable tenant settings for metadata scanning.
+    dataset_schema: bool = False
+        Whether to return dataset schema (tables, columns and measures). If you set this parameter to true, you must fully enable metadata scanning in order for data to be returned. For more information, see Enable tenant settings for metadata scanning.
+    dataset_expressions : bool, default=False
+        Whether to return data source details.
+    lineage : bool, default=False
+        Whether to return lineage info (upstream dataflows, tiles, data source IDs)
+    artifact_users : bool, default=False
+        Whether to return user details for a Power BI item (such as a report or a dashboard).
+    workspace : str | List[str] | UUID | List[UUID], default=None
+        The required workspace name(s) or id(s) to be scanned. It supports a limit of 100 workspaces and only IDs in GUID format.
+
+    Returns
+    -------
+    dict
+        A json object with the scan result.
+    """
+
+    if workspace is None:
+        workspace = resolve_workspace_name()
+
+    if isinstance(workspace, str):
+        workspace = [workspace]
+
+    if len(workspace) > 100:
+        print(
+            f"{icons.yellow_dot} More than 100 workspaces where provided. Truncating to the fist 100."
+        )
+        workspace = workspace[:100]
+
+    workspace_list = []
+
+    for w in workspace:
+        if _is_valid_uuid(w):
+            workspace_list.append(w)
+        else:
+            dfW = list_workspaces(workspace=w)
+            workspace_list = (
+                workspace_list + dfW[dfW["Name"].isin(workspace)]["Id"].tolist()
+            )
+
+    url = "/v1.0/myorg/admin/workspaces/getInfo"
+    params = {}
+    params["lineage"] = lineage
+    params["datasourceDetails"] = data_source_details
+    params["datasetSchema"] = dataset_schema
+    params["datasetExpressions"] = dataset_expressions
+    params["getArtifactUsers"] = artifact_users
+
+    url = _build_url(url, params)
+
+    payload = {"workspaces": workspace_list}
+
+    response = _base_api(
+        request=url,
+        method="post",
+        payload=payload,
+        status_codes=202,
+        client="fabric_sp",
+    )
+
+    scan_id = response.json()["id"]
+    scan_status = response.json().get("status")
+
+    while scan_status not in ["Succeeded", "Failed"]:
+        time.sleep(1)
+        response = _base_api(
+            request=f"/v1.0/myorg/admin/workspaces/scanStatus/{scan_id}",
+            client="fabric_sp",
+        )
+        scan_status = response.json().get("status")
+
+    if scan_status == "Failed":
+        raise FabricHTTPException(response)
+
+    response = _base_api(
+        request=f"/v1.0/myorg/admin/workspaces/scanResult/{scan_id}",
+        client="fabric_sp",
+    )
+
+    return response.json()

sempy_labs/admin/_shared.py

@@ -0,0 +1,82 @@
+import pandas as pd
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+)
+from sempy._utils._log import log
+
+
+@log
+def list_widely_shared_artifacts(
+    api_name: str = "LinksSharedToWholeOrganization",
+) -> pd.DataFrame:
+    """
+    Returns a list of Power BI reports that are shared with the whole organization through links or a list of Power BI items (such as reports or dashboards) that are published to the web.
+
+    This is a wrapper function for the following APIs:
+    `Admin - WidelySharedArtifacts LinksSharedToWholeOrganization <https://learn.microsoft.com/rest/api/power-bi/admin/widely-shared-artifacts-links-shared-to-whole-organization>`_.
+    `Admin - WidelySharedArtifacts PublishedToWeb <https://learn.microsoft.com/rest/api/power-bi/admin/widely-shared-artifacts-published-to-web>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    api_name : str, default = "LinksSharedToWholeOrganization"
+        The name of the API to call. Either "LinksSharedToWholeOrganization" or "PublishedToWeb".
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of Power BI reports that are shared with the whole organization through links or a list of Power BI items (such as reports or dashboards) that are published to the web.
+    """
+
+    columns = {
+        "Artifact Id": "string",
+        "Artifact Name": "string",
+        "Artifact Type": "string",
+        "Access Right": "string",
+        "Share Type": "string",
+        "Sharer Name": "string",
+        "Sharer Email Address": "string",
+        "Sharer Identifier": "string",
+        "Sharer Graph Id": "string",
+        "Sharer Principal Type": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    api = (
+        "linksSharedToWholeOrganization"
+        if api_name == "LinksSharedToWholeOrganization"
+        else "publishedToWeb"
+    )
+
+    responses = _base_api(
+        request=f"/v1.0/myorg/admin/widelySharedArtifacts/{api}",
+        client="fabric_sp",
+        uses_pagination=True,
+    )
+
+    rows = []
+    for r in responses:
+        for v in r.get("ArtifactAccessEntities", []):
+            sharer = v.get("sharer", {})
+            rows.append(
+                {
+                    "Artifact Id": v.get("artifactId"),
+                    "Artifact Name": v.get("displayName"),
+                    "Artifact Type": v.get("artifactType"),
+                    "Access Right": v.get("accessRight"),
+                    "Share Type": v.get("shareType"),
+                    "Sharer Name": sharer.get("displayName"),
+                    "Sharer Email Address": sharer.get("emailAddress"),
+                    "Sharer Identifier": sharer.get("identifier"),
+                    "Sharer Graph Id": sharer.get("graphId"),
+                    "Sharer Principal Type": sharer.get("principalType"),
+                }
+            )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    return df

sempy_labs/admin/_sharing_links.py

@@ -0,0 +1,110 @@
+from sempy._utils._log import log
+from sempy_labs._helper_functions import (
+    _base_api,
+    _is_valid_uuid,
+)
+import sempy_labs._icons as icons
+from typing import List
+
+
+@log
+def remove_all_sharing_links(sharing_link_type: str = "OrgLink"):
+    """
+    Deletes all organization sharing links for all Fabric items in the tenant. This action cannot be undone.
+
+    This is a wrapper function for the following API: `Sharing Links - Remove All Sharing Links <https://learn.microsoft.com/rest/api/fabric/admin/sharing-links/remove-all-sharing-links>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    sharing_link_type : str, default='OrgLink'
+        Specifies the type of sharing link that is required to be deleted. Additional sharing link types may be added over time.
+    """
+
+    payload = {"sharingLinkType": sharing_link_type}
+
+    _base_api(
+        request="/v1/admin/items/removeAllSharingLinks",
+        client="fabric_sp",
+        lro_return_status_code=True,
+        status_codes=[200, 202],
+        method="post",
+        payload=payload,
+    )
+
+    print(
+        f"{icons.green_dot} All organization sharing links for all Fbric items in the tenant have been deleted."
+    )
+
+
+@log
+def remove_sharing_links(items: List[dict], sharing_link_type: str = "OrgLink"):
+    """
+    Deletes all organization sharing links for the specified Fabric items. This action cannot be undone.
+
+    This is a wrapper function for the following API: `Sharing Links - Bulk Remove Sharing Links <https://learn.microsoft.com/rest/api/fabric/admin/sharing-links/bulk-remove-sharing-links>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    items : List[dict]
+        A list of dictionaries, each representing an item. The 'item' and 'workspace' accepts either name or ID. Examples:
+
+        [
+            {
+                "item": "MyReport",
+                "type": "Report",
+                "workspace": "Workpsace 1",
+            },
+            {
+                "item": "MyReport2",
+                "type": "Report",
+                "workspace": "Workspace 2",
+            },
+        ]
+
+        [
+            {
+                "item": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a",
+                "type": "Report",
+                "workspace": "Workspace 1",
+            },
+            {
+                "item": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c",
+                "type": "Notebook",
+                "workspace": "476fcafe-b514-495d-b13f-ca9a4f0b1d8f",
+            },
+        ]
+
+    sharing_link_type : str, default='OrgLink'
+        Specifies the type of sharing link that is required to be deleted. Additional sharing link types may be added over time.
+    """
+
+    from sempy_labs.admin._items import _resolve_item_id
+
+    payload = {"items": [], "sharingLinkType": sharing_link_type}
+
+    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:
+            item_id = _resolve_item_id(item=item, type=type, workspace=workspace)
+            payload["items"].append({"id": item_id, "type": type})
+
+    _base_api(
+        request="/v1/admin/items/bulkRemoveSharingLinks",
+        client="fabric_sp",
+        method="post",
+        payload=payload,
+        lro_return_status_code=True,
+        status_codes=[200, 202],
+    )
+
+    print(
+        f"{icons.green_dot} Organizational sharing links for all specified items have been deleted."
+    )

sempy_labs/admin/_tags.py

@@ -0,0 +1,131 @@
+from .._helper_functions import (
+    _base_api,
+    _is_valid_uuid,
+)
+from uuid import UUID
+from sempy_labs._tags import list_tags
+import sempy_labs._icons as icons
+from typing import List
+from sempy._utils._log import log
+
+
+@log
+def resolve_tag_id(tag: str | UUID):
+
+    if _is_valid_uuid(tag):
+        tag_id = tag
+    else:
+        df = list_tags()
+        df[df["Tag Name"] == tag]
+        if df.empty:
+            raise ValueError(f"{icons.red_dot} The '{tag}' tag does not exist.")
+        tag_id = df.iloc[0]["Tag Id"]
+
+    return tag_id
+
+
+@log
+def create_tags(tags: str | List[str]):
+    """
+    Creates a new tag or tags.
+
+    This is a wrapper function for the following API: `Tags - Bulk Create Tags <https://learn.microsoft.com/rest/api/fabric/admin/tags/bulk-create-tags>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    tags : str | List[str]
+        The name of the tag or tags to create.
+    """
+
+    if isinstance(tags, str):
+        tags = [tags]
+
+    # Check the length of the tags
+    for tag in tags:
+        if len(tag) > 40:
+            raise ValueError(
+                f"{icons.red_dot} The '{tag}' tag name is too long. It must be 40 characters or less."
+            )
+
+    # Check if the tags already exist
+    df = list_tags()
+    existing_names = df["Tag Name"].tolist()
+    existing_ids = df["Tag Id"].tolist()
+
+    available_tags = [
+        tag for tag in tags if tag not in existing_names and tag not in existing_ids
+    ]
+    unavailable_tags = [
+        tag for tag in tags if tag in existing_names or tag in existing_ids
+    ]
+
+    print(f"{icons.warning} The following tags already exist: {unavailable_tags}")
+    if not available_tags:
+        print(f"{icons.info} No new tags to create.")
+        return
+
+    payload = [{"displayName": name} for name in available_tags]
+
+    for tag in tags:
+        _base_api(
+            request="/v1/admin/bulkCreateTags",
+            client="fabric_sp",
+            method="post",
+            payload=payload,
+            status_codes=201,
+        )
+
+    print(f"{icons.green_dot} The '{available_tags}' tag(s) have been created.")
+
+
+@log
+def delete_tag(tag: str | UUID):
+    """
+    Deletes a tag.
+
+    This is a wrapper function for the following API: `Tags - Delete Tag <https://learn.microsoft.com/rest/api/fabric/admin/tags/delete-tag>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    tag : str | uuid.UUID
+        The name or ID of the tag to delete.
+    """
+
+    tag_id = resolve_tag_id(tag)
+
+    _base_api(request=f"/v1/admin/tags/{tag_id}", client="fabric_sp", method="delete")
+
+    print(f"{icons.green_dot} The '{tag}' tag has been deleted.")
+
+
+@log
+def update_tag(name: str, tag: str | UUID):
+    """
+    Updates the name of a tag.
+
+    This is a wrapper function for the following API: `Tags - Update Tag <https://learn.microsoft.com/rest/api/fabric/admin/tags/update-tag>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    name : str
+        The new name of the tag.
+    tag : str | uuid.UUID
+        The name or ID of the tag to update.
+    """
+
+    tag_id = resolve_tag_id(tag)
+
+    _base_api(
+        request=f"/v1/admin/tags/{tag_id}",
+        client="fabric_sp",
+        method="patch",
+        payload={"displayName": name},
+    )
+
+    print(f"{icons.green_dot} The '{tag}' tag has been renamed to '{name}'.")