Fabric API - Connection

A Fabric connection is created in the Dashboard and used in services as self.microsoft.fabric[name]. This page covers the connection's fields, its tokens, and the invoke and ping methods.

Dashboard fields

Under Cloud → Microsoft Fabric:

What the app registration needs

An admin does three things once:

1. Enables the tenant setting "Service principals can call Fabric public APIs" under Tenant settings → Developer settings in the Fabric admin portal
2. Adds the app registration to each workspace the connection should reach, as a Contributor for writing or a Viewer for reading only
3. Enables the Livy endpoint tenant setting on the same page, for run_spark and the Spark sessions it runs on - query does not need it

Tokens

The connection signs in with the client credentials grant - it posts the client ID and secret to https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/token and gets a token back. It gets four tokens, because the Fabric API, OneLake storage, the SQL analytics endpoint and eventhouses are separate services:

Each token is obtained when first needed and replaced a minute before it expires. When Fabric rejects a token anyway, e.g. after the secret was rotated, the connection gets a new one and repeats the request once.

invoke

conn.invoke(method, path, params=None, data=None)

Calls any endpoint of the Fabric API with the connection's token.

Returns the parsed JSON response, or nothing when there is no body. An error status code raises an exception with the code and the response text.

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class Invoke(Service):

    def handle(self):

        workspace_id = '262ddd3d-3d0d-4495-b80f-6dddda1e23a1'

        conn = self.microsoft.fabric['Zato Fabric']

        # Every item of one type in a workspace, through the API's own filter.
        path = f'/workspaces/{workspace_id}/items'
        params = {'type': 'Eventstream'}

        response = conn.invoke('GET', path, params=params)

        names = []
        for item in response['value']:
            names.append(item['displayName'])

        self.response.payload = {'eventstreams': names}

{"eventstreams": ["occupancy-events"]}

conn.get(path, params), conn.post(path, data, params), conn.patch(path, data, params) and conn.delete(path, params) are the same call with the method filled in. conn.invoke_raw takes the same parameters as invoke and returns the whole response object.

ping

conn.ping()

Obtains a token and lists the workspaces the app registration can see. The Ping button in the Dashboard calls it. Returns nothing and raises an exception when the token or the listing fails.

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class Ping(Service):

    def handle(self):

        conn = self.microsoft.fabric['Zato Fabric']
        conn.ping()

        self.response.payload = {'connection': conn.name}

See also

Learn more