Add function to cancel item job instance

src/sempy_labs/__init__.py

@@ -44,6 +44,7 @@
     create_item_schedule_cron,
     create_item_schedule_daily,
     create_item_schedule_weekly,
+    cancel_item_job_instance,
 )
 from ._delta_analyzer import (
     delta_analyzer,
@@ -529,6 +530,7 @@
     "bind_semantic_model_to_gateway",
     "list_semantic_model_errors",
     "list_item_job_instances",
+    "cancel_item_job_instance",
     "list_item_schedules",
     "list_skus",
     "list_skus_for_capacity",

src/sempy_labs/_job_scheduler.py

@@ -12,6 +12,8 @@
 )
 from uuid import UUID
 import sempy_labs._icons as icons
+import time
+from sempy.fabric.exceptions import FabricHTTPException
 
 
 @log
@@ -527,3 +529,91 @@ def create_item_schedule_weekly(
     print(
         f"{icons.green_dot} The schedule for the '{item_name}' {type.lower()} has been created."
     )
+
+
+@log
+def cancel_item_job_instance(
+    item: str | UUID,
+    job_instance_id: UUID,
+    type: Optional[str] = None,
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Cancel an item's job instance.
+
+    This is a wrapper function for the following API: `Job Scheduler - Cancel Item Job Instance <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/cancel-item-job-instance>`_.
+
+    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 | uuid.UUID
+        The item name or ID.
+    job_instance_id : uuid.UUID
+        The job instance ID.
+    type : str, default=None
+        The item `type <https://learn.microsoft.com/rest/api/fabric/core/items/list-items?tabs=HTTP#itemtype>`_. If specifying the item name as the item, the item type is required.
+    workspace : str | uuid.UUID, default=None
+        The Fabric workspace name or ID used by the lakehouse.
+        Defaults to None which resolves to the workspace of the attached lakehouse
+        or if no lakehouse attached, resolves to the workspace of the notebook.
+    """
+
+    (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
+    )
+
+    try:
+        response = _base_api(
+            request=f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/instances/{job_instance_id}/cancel",
+            method="post",
+            status_codes=[200, 202],
+            client="fabric_sp",
+        )
+    except FabricHTTPException as e:
+        if (
+            e.status_code == 400
+            and e.response.json().get("errorCode") == "JobAlreadyCompleted"
+        ):
+            # If Job Instance is already completed, skip the rest of the process and output the Job Instance details.
+            print(
+                f"{icons.green_dot} The Job Instance '{job_instance_id}' of '{item_name}' {type.lower()} within the '{workspace_name}' workspace has been already cancelled."
+            )
+
+            return _get_item_job_instance(
+                url=f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/instances/{job_instance_id}"
+            )
+        else:
+            print(
+                f"{icons.red_dot} An error occurred while cancelling '{job_instance_id}' of '{item_name}' {type.lower()} within the '{workspace_name}' workspace: {e}"
+            )
+            raise
+
+    print(
+        f"{icons.in_progress} The cancellation of Job Instance '{job_instance_id}' of '{item_name}' {type.lower()} within the '{workspace_name}' workspace has been initiated."
+    )
+
+    status_url = response.headers.get("Location").split("fabric.microsoft.com")[1]
+    status = None
+    while status not in ["Completed", "Failed", "Cancelled"]:
+        response = _base_api(request=status_url)
+        status = response.json().get("status")
+        time.sleep(3)
+
+    df = _get_item_job_instance(url=status_url)
+
+    # Check what is the final status of the Job Instance.
+    if status in ["Completed", "Failed", "Cancelled"]:
+        print(
+            f"{icons.green_dot} The Job Instance '{job_instance_id}' of '{item_name}' {type.lower()} within the '{workspace_name}' workspace has been cancelled successfully."
+        )
+    else:
+        print(
+            f"Latest status of Job Instance '{job_instance_id}' of '{item_name}' {type.lower()} within the '{workspace_name}' workspace: {status}"
+        )
+        print(
+            f"{icons.red_dot} The cancellation of Job Instance '{job_instance_id}' of '{item_name}' {type.lower()} within the '{workspace_name}' workspace has failed."
+        )
+
+    return df