Fabric Hook

Hooks for authenticating and making requests against the Microsoft Fabric REST API.

class scamander.providers.fabric.hooks.fabric_hook.FabricAsyncHook(*, fabric_conn_id: str = 'fabric_default', scopes: str | None = None)

Bases: FabricHook

Interact with Microsoft Fabric asynchronously.

Parameters:

fabric_conn_id – Airflow Connection ID that contains the connection

async async_get_headers() → dict[str, str]

Form of auth headers based on OAuth token.

Returns:

dict: Headers with the authorization token.

async async_get_item_run_details(workspace_id: str, item_id: str, item_run_id: str, job_type: str | None = None, use_notebook_beta_endpoints: bool = False) → dict

Get run details of the item instance.

Parameters:

  • workspace_id – The workspace Id in which the item is located.

  • item_id – The item Id.

  • item_run_id – The Id of the item run instance.

  • job_type – The job type. Only used when use_notebook_beta_endpoints is True.

  • use_notebook_beta_endpoints – When True and job_type is “RunNotebook”, polls the notebook-specific beta endpoint which returns exitValue in the response properties.

Returns:

The item run details payload from the API.

async async_get_refresh_details(group_id: str, dataset_id: str, request_id: str) → dict | None

Get the refresh history entry of a Power BI dataset refresh.

Requires a hook created with scopes=POWERBI_SCOPES.

Parameters:
Returns:

The refresh history entry, or None if it is not (yet) in the history.

async cancel_item_run(workspace_id: str, item_id: str, item_run_id: str) → None

Cancel the item run.

Parameters:

  • workspace_id – The workspace Id in which the item is located.

  • item_id – The item Id.

  • item_run_id – The Id of the item run.

class scamander.providers.fabric.hooks.fabric_hook.FabricHook(*, fabric_conn_id: str = 'fabric_default', max_retries: int = 5, retry_delay: int = 1, scopes: str | None = None)

Bases: BaseHook

A hook to interact with Microsoft Fabric. This hook uses OAuth token generated from the refresh token, client ID and tenant ID specified in the connection.

Parameters:

fabric_conn_id – Airflow Connection ID that contains the connection information for the Fabric account used for authentication.

get_headers() → dict[str, str]

Form of auth headers based on OAuth token.

Returns:

dict: Headers with the authorization token.

get_item_details(workspace_id: str, item_id: str) → dict

Get details of the item.

Parameters:

  • workspace_id – The ID of the workspace in which the item is located.

  • item_id – The ID of the item.

Returns:

The details of the item.

get_item_run_details(location: str) → dict

Get details of the item run instance.

Parameters:

location – The location URL of the item instance, obtained from the Location header returned by run_fabric_item().

Returns:

The item run details payload from the API.

refresh_dataset(group_id: str, dataset_id: str) → str

Start a refresh of a Power BI dataset (semantic model).

Requires a hook created with scopes=POWERBI_SCOPES.

Parameters:

  • group_id – The workspace Id.

  • dataset_id – The dataset Id.

Returns:

The request Id of the refresh, matching requestId in the refresh history.

Raises:

PowerBIDatasetRefreshException – If the refresh could not be started.

run_fabric_item(workspace_id: str, item_id: str, job_type: str, job_params: dict | None = None, execution_data: dict | None = None, use_notebook_beta_endpoints: bool = False) → str

Submit a Fabric item job and return the Location URL of the job instance.

Parameters:

  • workspace_id – The workspace Id in which the item is located.

  • item_id – The item Id. Refer to: https://learn.microsoft.com/rest/api/fabric/admin/items/list-items?tabs=HTTP#itemtype

  • job_type – The job type (e.g. “RunNotebook”, “Pipeline”).

  • job_params – Optional dict of notebook parameters keyed by name, each with ‘value’ and ‘type’ keys (e.g. {“p1”: {“value”: “v1”, “type”: “string”}}). Sent as executionData.parameters.

  • execution_data – Optional dict to use as executionData directly, overrides job_params.

  • use_notebook_beta_endpoints – When True and job_type is “RunNotebook”, use the notebook-specific beta endpoint which returns exitValue.

Returns:

The Location header value (job instance URL) from the response.

run_fabric_item_and_wait(workspace_id: str, item_id: str, job_type: str, job_params: dict | None = None, execution_data: dict | None = None, check_interval: int = 60, timeout: int = 604800, context: dict | None = None, xcom_key: str = 'fabric_job_instance') → dict

Submit a Fabric item job, wait for it to complete, and optionally push the result to XCom.

Parameters:

  • workspace_id – The workspace Id in which the item is located.

  • item_id – The item Id.

  • job_type – The job type path segment (e.g. “RunNotebook”, “Execute”, “DefaultJob”).

  • job_params – See run_fabric_item().

  • execution_data – See run_fabric_item().

  • check_interval – Seconds to wait between status polls.

  • timeout – Maximum seconds to wait before raising.

  • context – Airflow task context dict. When provided, the final job instance payload is pushed to XCom so downstream tasks can access it.

  • xcom_key – XCom key to use when pushing results (default: "fabric_job_instance").

Returns:

Final job instance payload from the API, including exitValue for notebooks.

Raises:

FabricRunItemException – If the job fails, is cancelled, or times out.

wait_for_item_run_status(location: str, target_status: str, check_interval: int = 60, timeout: int = 604800) → dict

Poll until the item run reaches a terminal status and return its final details.

Parameters:

  • location – The location URL of the item instance retrieved from the header of item run API.

  • target_status – The expected successful terminal status (e.g. Completed). Used only to determine the return path; failure states always raise.

  • check_interval – Seconds to wait between status polls.

  • timeout – Maximum seconds to wait before raising.

Returns:

Final item run details payload from the API.

Raises:

FabricRunItemException – If the run does not reach target_status within timeout seconds, or if it ends in a failure state.

exception scamander.providers.fabric.hooks.fabric_hook.FabricRunItemException

Bases: AirflowException

An exception that indicates a item run failed to complete.

class scamander.providers.fabric.hooks.fabric_hook.FabricRunItemStatus

Bases: object

Fabric item run operation statuses.

exception scamander.providers.fabric.hooks.fabric_hook.PowerBIDatasetRefreshException

Bases: AirflowException

An exception that indicates a dataset refresh failed to start or complete.

class scamander.providers.fabric.hooks.fabric_hook.PowerBIRefreshStatus

Bases: object

Power BI dataset refresh statuses. Unknown means the refresh is still running.

scamander.providers.fabric.hooks.fabric_hook.update_conn(conn_id, refresh_token: str, session=None)

Persist a rotated OAuth refresh token back onto the Airflow connection.

Parameters:

  • conn_id – The Airflow connection ID to update.

  • refresh_token – The new refresh token issued by the token endpoint.

  • session – SQLAlchemy session, injected by provide_session().