Fabric REST API— Shortcuts

3 min readMar 28, 2024

This is the first post in a series where I’ll go into Fabric REST API, starting with OneLake shortcuts. This blog post describes the available OneLake shortcut REST APIs and their usage.

Shortcut REST API usage examples

Use the following instructions to test usage examples for specific shortcut public APIs and verify the results.

+--------+--------+---------------------------------------------------+
| Method | Action |                    Description                    |
+--------+--------+---------------------------------------------------+
| POST   | Create | Creates a shortcut with a specified connection_id |
| DELETE | Delete | Deletes a shortcut                                |
| GET    | Get    | Gets a shortcut defition                          |
| GET    | List   | Lists shortcuts                                   |
+--------+--------+---------------------------------------------------+

Prerequisites

These are the prerequisites to make the examples work:

Create a Fabric workspace if you don’t have one.
Create a Fabric lakehouse if you don’t have one.
Create a Cloud storage connection: this cannot be automated yet, so you need to manually create a Cloud connection to the appropiate ADLS Gen2 and obtain the ID.
Create an ADLS Gen2 on Azure and put some data on it.

Once those are created, replace the placeholders {workspace_id}, {lakehouse_name}, {connection_id} and {storage_account_name} with appropriate values when you follow the examples below.

sc.addPyFile('https://gist.githubusercontent.com/murggu/09d7befcb157011c340c51cb5d4af42f/raw/3e8bd0deeb40f3f7487e01c49580d989f057957e/invoke_fabric_api.py')
from invoke_fabric_api import *

# Set up parameters
workspace_id = mssparkutils.runtime.context['currentWorkspaceId'] #<workspace_id>
lakehouse_id = mssparkutils.lakehouse.get("<lakehouse_name>").id
connection_id = "<connection_id>"

storage_account = "<storage_account_name>"

Note: if you find any issues importing the invoke_fabric_api.py , go here > click on Raw > replace the URL.

Create shortcut

Create an ADLS Gen2 and OneLake shortcut using ADLS Gen2 and OneLake as a target. Fabric supports you setting the {shortcut_conflict_policy} which defines the action to take (Abort by default or GenerateUniqueName) when a shortcut with the same name and path already exists.

For creating shortcuts to other targets you will need to change just the request body and create a new external connection. See request payload examples for Amazon S3 and Dataverse .

Create a shortcut to ADLS Gen2 (Files section): Create a shortcut to ADLS Gen2 within the Files section of the lakehouse. Change the subpath below accordingly.

method = "post"
shortcut_conflict_policy = "Abort"
uri = f"workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts?shortcutConflictPolicy={shortcut_conflict_policy}"

payload = {
  "path": "Files/",
  "name": "adlsgen2_files_sc",
  "target": {
    "adlsGen2": {
      "location": "https://<storage_account>.dfs.core.windows.net/",
      "subpath": "/sampledata",
      "connectionId": connection_id
    }
  }
}

invoke_fabric_api_request(method, uri, payload)

Create a shortcut to ADLS Gen2 (Tables section): Create a shortcut to ADLS Gen2 within the Tables section of the lakehouse. Ensure the data pointed by the subpath is in Delta Lake format.

method = "post"
shortcut_conflict_policy = "GenerateUniqueName"
uri = f"workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts?shortcutConflictPolicy={shortcut_conflict_policy}"

payload = {
  "path": "Tables",
  "name": "adlsgen2_tables_sc",
  "target": {
    "adlsGen2": {
      "location": "https://<storage_account>.dfs.core.windows.net/",
      "subpath": "/sampledata/covid",
      "connectionId": connection_id
    }
  }
}

invoke_fabric_api_request(method, uri, payload)

Create shortcut OneLake (Tables section): Create a shortcut to OneLake within the Tables section of the lakehouse.

method = "post"
shortcut_conflict_policy = "GenerateUniqueName"
uri = f"workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts?shortcutConflictPolicy={shortcut_conflict_policy}"

payload = {
  "path": "Tables",
  "name": "onelake_tables_sc",
  "target": {
     "oneLake": {
      "workspaceId": workspace_id,
      "itemId": lakehouse_id,
      "path": "Files/adlsgen2_files_sc/covid"
      }
  }
}

invoke_fabric_api_request(method, uri, payload)

Delete shortcut

Use the following endpoint to delete a shortcut:

method = "delete"
uri = f"workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts/Tables/onelake_tables_sc"

invoke_fabric_api_request(method, uri)

Get shortcut

To get the definition of a specific shortcut, use:

method = "get"
uri = f"workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts/Tables/adlsgen2_tables_sc_1"

invoke_fabric_api_request(method, uri)

List shortcuts

To list shortcuts from an item, use:

method = "get"
uri = f"workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts"

invoke_fabric_api_request(method, uri)

Considerations

External connections: manual setup and ID retrieval is needed before creating a shortcut using Fabric REST API endpoint.
Shortcuts within the Tables section of the lakehouse must target data in Delta Lake format. If not, it will go to the Unidentified area.
Shortcuts API rate limit is 200 requests per minute, per operation, per user.
There is not a batch API endpoint to create multiple shortcuts at once.
The above listed Fabric REST API endpoints use the Power BI audience to obtain the Bearer token. You can also use OneLake REST API endpoints, with Storage audience.

Are you missing any shortcut API examples? If so, please put a comment.

References: