Skip to content

Workspaces

Workspaces are logical containers in Microsoft Fabric that hold items (pipelines, lakehouses, notebooks, etc.) and are hosted on capacities. The fabias SDK provides a complete API for workspace management, including creation, access control, and recovery.

Usage Examples

Get a Workspace

import fabias

# By name
ws = fabias.workspace("GENESIS")

# By GUID
ws = fabias.workspace("6bd19ad7-33b5-4865-b607-7378f6699a66")

# Current workspace (Fabric only)
ws = fabias.workspace()

List Workspaces

import fabias

for ws in fabias.workspaces():
    print(f"{ws.name}: {ws.id}")

Create a Workspace

import fabias

# Simple creation
new_ws = fabias.workspaces.add(
    name="Analytics",
    capacity="capacity-guid"
)

# With description
new_ws = fabias.workspaces.add(
    name="Analytics",
    capacity="capacity-guid",
    description="Analytics workspace for data engineering team"
)

Idempotent Behavior: If a workspace with the same name already exists in "Active" state, add() returns the existing workspace instead of failing. This makes automation scripts simpler.

Access Workspace Items

import fabias

ws = fabias.workspace("GENESIS")

# Get all items
items = ws.items()

# Get typed items
pipelines = ws.pipelines()
lakehouses = ws.lakehouses()
notebooks = ws.notebooks()
environments = ws.environments()

Delete a Workspace

Workspace deletion is a soft delete operation. Deleted workspaces enter a retention period during which they can be restored by Fabric administrators.

import fabias

ws = fabias.workspace("Old Workspace")
ws.delete()

# Alternative: delete by name or GUID
fabias.workspaces.delete("Old Workspace")
fabias.workspaces.delete("workspace-guid")

Retention Period:

  • Personal workspaces (My workspaces): 30 days (fixed)
  • Collaborative workspaces: 7-90 days (configurable, default 7 days)

Restore a Deleted Workspace

Requires: Fabric Administrator privileges

import fabias

# Simple restore (retains original settings)
ws = fabias.workspaces.restore("workspace-guid")

# Restore with new admin
ws = fabias.workspaces.restore(
    "workspace-guid",
    new_admin_principal_id="user-guid"
)

# Restore My workspace with new name (required for My workspaces)
ws = fabias.workspaces.restore(
    "workspace-guid",
    new_name="Restored Analytics"
)

# Alternative: using workspace object
deleted_ws = fabias.Workspace(fabias._client, workspace_id="workspace-guid")
deleted_ws.restore()

Permissions Required:

  • Fabric Administrator role
  • Tenant.ReadWrite.All delegated scope
  • Service principal authentication (admin API)

Rate Limit: 10 requests per minute

Workspace States

Workspaces can be in one of five states:

State Description
Active Normal operational workspace
Orphaned Workspace with no admin user (requires admin assignment)
Deleted Soft-deleted workspace within retention period (can be restored)
Removing Permanently deleting (occurs after retention period expires)
Not found Workspace ID doesn't belong to your tenant

Role Assignments

import fabias

ws = fabias.workspace("GENESIS")

# List all role assignments
for assignment in ws.roleAssignments():
    print(f"{assignment.principalId}: {assignment.role}")

# Add a user as workspace member
ws.roleAssignments.add(
    principalId="user-guid",
    principalType="User",
    role="Member"
)

# Available roles: Admin, Member, Contributor, Viewer

# Remove a role assignment
ws.roleAssignments.delete("user-guid")

Assign to Capacity

import fabias

ws = fabias.workspace("Analytics")
ws.setCapacity("new-capacity-guid")

Automation Best Practices

Idempotent Workspace Creation

For automation scenarios (Ansible, Azure DevOps, etc.), use this pattern to handle both new and existing workspaces:

import fabias

try:
    # Check if workspace exists
    ws = fabias.workspace("DE-Analytics")
    print("Workspace already exists")
except fabias.NotFoundError as e:
    # Check if it's deleted
    if "Deleted" in str(e):
        # Extract workspace_id from error message and restore, or fail
        raise RuntimeError(
            "Workspace exists in 'Deleted' state. "
            "Restore or permanently delete it before proceeding."
        ) from e

    # Create new workspace
    ws = fabias.workspaces.add(
        name="DE-Analytics",
        capacity=capacity_id,
        description="Data Engineering workspace"
    )
    print("Created new workspace")

Alternatively, rely on idempotent add():

import fabias

# This returns existing workspace if active, creates if not found
# Raises FabiasError if deleted (with restore instructions)
ws = fabias.workspaces.add(
    name="DE-Analytics",
    capacity=capacity_id
)

Handling Deleted Workspaces

When automation encounters a deleted workspace:

import fabias

try:
    ws = fabias.workspaces.add("Analytics", capacity="capacity-guid")
except fabias.FabiasError as e:
    if "Deleted" in str(e):
        # Option 1: Extract workspace_id and restore
        # Error message format: "... fabric.workspaces.restore('workspace-guid') ..."
        import re
        match = re.search(r"restore\('([^']+)'\)", str(e))
        if match:
            workspace_id = match.group(1)
            ws = fabias.workspaces.restore(workspace_id)
            print(f"Restored workspace {workspace_id}")
        else:
            raise  # Can't parse workspace_id
    else:
        raise  # Different error

Workspace Properties

import fabias

ws = fabias.workspace("GENESIS")

print(f"Name: {ws.name}")
print(f"ID: {ws.id}")
print(f"Capacity ID: {ws.capacityId}")
print(f"Description: {ws.description}")