Automatická synchronizace SQL Analytics Endpointu v Microsoft Fabric

tl;dr Fabric Lakehouse má SQL Analytics Endpoint (SAE), který ti umožní se dotazovat na tvoje data přes T-SQL. Endpoint čte delta tabulky, které jsou uloženy jako parquet a delta log soubory. SAE sedí nad touto vrstvou, čte metadata, a publikuje user-friendly SQL vrstvu. Rozdíl mezi zápisem do Lakehousu a vystavěním těch samotných dat může být pár vteřin až minut. Toto zpoždění můžeš poznat, pokud hned po zápisu aktualizuješ třeba Power BI semantický model. Abys tomu zabránil, můžeš zavolat Fabric REST API’s Refresh SQL Endpoint Metadata endpoint.

Disclaimer: Tento článek popisuje chování v rámci Microsoft Fabric Lakehouse položky a jeho SQL Analytics Endpointem. Zároveň pro tento případ nepoužívám built-in lakehouse sql analytics endpoint semantický model.

Pokud chceš jenom zkopírovat kód, klikni sem.

Co je SQL Analytics Endpoint

V Microsoft Fabricu, když používáš Lakehouse, se ti automaticky k němu vytvoří jeden SQL Analytics Endpoint (na každý Lakehouse). Je to rozhraní pouze pro čtení (databázové views si ale vytvořit můžeš), které ti umožní dotazovat Delta tabulky pomocí T-SQL. Tenhle endpoint není určený na správu Lakehousu, slouží hlavně ke konzumaci dat v BI řešeních.

Protože SQL Analytics Endpoint (SAE) běží nad Lakehousem, platí pro něj pár omezení. V SAE uvidíš jen data v Delta formátu, tedy Delta tabulky, a navíc může docházet k drobnému zpoždění mezi zápisem dat do Lakehousu a jejich zobrazením přes SAE.

Synchronizace dat mezi Lakehousem a SQL Analytics Endpointem

Když je SAE aktivní (po 15 minutách nečinnosti se bere jako neaktivní), prochází metadata Lakehousu a automaticky je synchronizuje do SQL vrstvy pro čtení. Není to ale hnedka, může vziknout krátké zpoždění od pár sekund po pár minut.

Pokud máš workflow, které hned po zápisu dat do Lakehousu používá tahle nová data v externím semantickém modelu (ne v tom vestavěném lakehouse SAE semantickém modelu), můžeš na tohle zpoždění narazit při obnově semantického modelu v Power BI v režimu Import.

Abys tomu předešel a neměl v datech nesoulad, můžeš udělat několik věcí:

• Probudit SAE tím, že proti němu pustíš dotaz, a chvíli počkat, než doběhne synchronizace.

• Ručně kliknout na Refresh v SQL Analytics Endpoint exploreru.

• Programově obnovit SAE přes Fabric REST API.

Pokud máš ve Fabricu naplánovanou datovou pipelinu, programová/automatická varianta je většinou nejlepší, protože chceš mít celý proces automatizovaný a ne u každého refreshe sedět a klikat.

Automatická obnova Lakehouse SQL Analytics Endpointu přes Fabric REST API

Nejjednodušší způsob, jak synchronizovat a obnovit metadata, je použít endpoint Fabric REST API s názvem Refresh Sql Endpoint Metadata.

Celé si to můžeš zautomatizovat tak, že API request zavoláš buď v datové pipelině, například pomocí Web nebo Notebook aktivity, anebo pokud používáš notebooky pro orchestraci, zavoláš notebook z jiného notebooku.

Aby to fungovalo, potřebuješ tahle oprávnění:

• Volající musí mít ve workspace roli Contributor nebo vyšší.

• Volajícím může být uživatel, Service Principal nebo Managed Identity.

• Alternativně můžeš použít delegovaná oprávnění se scopem Item.ReadWrite.All.

Samotné volání potřebuje tyto identifikátory:

• ID workspace, ve kterém je Lakehouse.

• ID SQL Analytics Endpointu.

• Alternativně: ID Lakehousu

Pokud to chceš spouštět jen pro jeden Lakehouse, ukážu ti, jak tyhle hodnoty jednoduše vytáhneš z URL v Power BI nebo Fabric službě.

Najdi svůj workspace a Lakehouse, a pak klikni na položku nebo ikonu SQL Analytics Endpointu:

SQL Analytics Endpoint icon

Pak získáš odkaz v tomto tvaru (buď s prefixem powerbi, nebo fabric.microsoft):

https://app.powerbi.com/groups/185e12d5-de32-4fd9-894e-c0df0ec58cbd/mirroredwarehouses/fb50503a-5ee8-4b3d-873b-18d72d78313e

https://app.fabric.microsoft.com/groups/185e12d5-de32-4fd9-894e-c0df0ec58cbd/mirroredwarehouses/fb50503a-5ee8-4b3d-873b-18d72d78313e

• Workspace Id

  • group - 185e12d5-de32-4fd9-894e-c0df0ec58cbd

• Lakehouse SQL Analytics Endpoint

  • mirroredwarehouses - fb50503a-5ee8-4b3d-873b-18d72d78313e

Abys získal Idčko Lakehousu (ikdyž to tady vyloženě nepotřebujeme), můžeš se přepnout ze SAE do Lakehouse nahoře takto:

Přepni do lakehousu

.../lakehouses/c0a542d2-c97d-4bf1-94cd-573b7fc55e56

• Lakehouse Id

  • lakehouses - c0a542d2-c97d-4bf1-94cd-573b7fc55e56

Volání REST API endpointu Refresh Sql Endpoint Metadata

Doporučuju tenhle krok spouštět jako poslední aktivitu před refreshem semantického modelu. Jinak řečeno, nejdřív nech doběhnout všechny zapisovací kroky a teprve potom zavolej endpoint.

V notebooku, použij non-Spark Python:

Vyber správný jazyk

Vlož následující:

import requests
import json

# Authenticate with Microsoft Fabric API
token = notebookutils.credentials.getToken("https://api.fabric.microsoft.com")

# Configuration
workspace = "<workspace_id>"
lakehouse_sql_endpoint = "<sql_analytics_endpoint_id>"

# API request headers
shared_headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Request body with timeout configuration
json_body = {
    "timeout": {
        "timeUnit": "Minutes",
        "value": 2
    }
}

# Refresh SQL Analytics Endpoint metadata
sync_sql_analytics_endpoint = requests.post(
    f"https://api.fabric.microsoft.com/v1/workspaces/{workspace}/sqlEndpoints/{lakehouse_sql_endpoint}/refreshMetadata",
    headers=shared_headers,
    json=json_body
)

# Display the response
display(sync_sql_analytics_endpoint.json())

V rychlosti ti příblížím pár částí kódu:

notebookutils.credentials.getToken("https://api.fabric.microsoft.com")

Tohle je vestavěná funkce, která ti vrátí bearer token pro daný scope (v tomhle případě Fabric API). Díky tomu nemusíš hned řešit vytváření service principalu a nastavování delegovaných oprávnění. Pokud máš ve workspace roli Contributor nebo vyšší, tohle volání ti projde. Když taková práva nemáš, musíš použít service principal a správně ho nakonfigurovat.

json_body = {
    "timeout": {
        "timeUnit": "Minutes",
        "value": 2
    }
}

Tohle je povinné tělo požadavku, které nastavuje timeout pro tuhle operaci.

sync_sql_analytics_endpoint = requests.post(
    f"https://api.fabric.microsoft.com/v1/workspaces/{workspace}/sqlEndpoints/{lakehouse_sql_endpoint}/refreshMetadata",
    headers=shared_headers,
    json=json_body
)

Tohle je část, která skutečně spustí synchronizaci. Endpoint podporuje dlouhotrvající operace. Prakticky to funguje tak, že požadavek odstartuje operaci, která běží delší dobu na pozadí a služba sleduje, kdy se dokončí. Můžeš tedy dostat kód 202 Accepted, což znamená, že operace byla spuštěna, a následně kód 200 OK s výsledným tělem odpovědi.

Výsledné tělo obsahuje všechny Delta tabulky, jejich stav synchronizace a několik časových razítek.

API Result

Pokud u tabulky vidíš stav Success, znamená to, že tam byla nějaká nesynchronizovaná data a tímhle voláním se úspěšně sesynchronizovala. Stav NotRun znamená, že se pro danou tabulku nic nespouštělo, typicky proto, že od poslední synchronizace nepřibyla žádná nová data a nebylo co dělat. Stav Failure značí, že se při synchronizaci něco pokazilo.

Více o stavech a ofiko dokumentaci k API najdeš tady:

https://learn.microsoft.com/en-us/rest/api/fabric/sqlendpoint/items/refresh-sql-endpoint-metadata