Spravovanie a spúšťanie poznámkových blokov v službe Fabric s rozhraniami API

Rozhranie Microsoft Fabric REST API poskytuje koncový bod služby na vytváranie, čítanie, aktualizáciu a odstraňovanie operácií položky služby Fabric. Tento článok popisuje dostupné rozhrania REST API poznámkového bloku a ich používanie.

Pomocou notebookových rozhraní API môžu dátoví inžinieri a dátoví vedci automatizovať svoje vlastné kanály a pohodlne a efektívne vytvárať CI/CD. Tieto rozhrania API tiež uľahčujú používateľom správu a manipuláciu s poznámkovými položkami služby Fabric a integráciu poznámkových blokov s inými nástrojmi a systémami. Notebooky je možné orchestrálne spravovať z Fabric pipeline a externých plánovačov prostredníctvom týchto API, čo umožňuje bezproblémovú integráciu s automatizovanými pracovnými postupmi.

Pre poznámkové bloky sú k dispozícii tieto akcie správy položiek:

Akcia	Description
Vytvoriť položku	Vytvorí poznámkový blok v pracovnom priestore.
Aktualizovať položku	Aktualizuje metaúdaje poznámkového bloku.
Aktualizácia definície položky	Aktualizuje obsah poznámkového bloku.
Odstrániť položku	Odstráni poznámkový blok.
Získať položku	Načíta metaúdaje poznámkového bloku.
Načítanie definície položky	Načíta obsah poznámkového bloku.
List item (Položka zoznamu)	Zobrazenie zoznamu všetkých položiek v pracovnom priestore.

Ďalšie informácie nájdete v téme Položky – REST API.

Pre poznámkové bloky sú k dispozícii tieto akcie plánovača úloh:

Akcia	Description
Spustenie úlohy položky na požiadanie	Spustite notebook na požiadanie s podporou parametrizácie, konfigurácie relácie (napríklad Spark/výpočtové nastavenia), výberu prostredia a runtime a výberu cieľového lakehouse.
Zrušenie inštancie úlohy položky	Zrušte beh na prácu v zápisníku.
Získať inštanciu úlohy položky	Získajte stav spustenia notebooku a získajte výstupnú hodnotu vrátenú týmto behom.

Ďalšie informácie nájdete v téme Plánovač úloh.

Poznámka

Autentifikácia princípu služby je podporovaná pre Items REST API (notebook CRUD operácie) aj Job Scheduler API (vykonávanie, monitorovanie a zrušenie). To umožňuje bezpečnú neobsluhovanú automatizáciu a scenáre CI/CD. Pridajte servisného zástupcu do pracovného priestoru s vhodnou rolou (Admin, Člen alebo Prispievateľ) na správu a vykonávanie zápisníkov.

Výstupné hodnoty z behov zápisníka

Spustenia zápisníka vykonávané cez Job Scheduler API môžu vrátiť výstupnú hodnotu, ktorú môžete použiť na podmienenú orchestráciu. Výstupná hodnota sa objavuje v exitValue poli payloadu na odpoveď Get Item Job Instance .

Zápisník môže nastaviť svoju výstupnú hodnotu tak, že zavolá mssparkutils.notebook.exit("your-value") pred dokončením behu. Výstupná hodnota je reťazec a môže zakódovať akýkoľvek výstupný signál – napríklad "success", "no_rows_processed", alebo JSON-serializovaný výsledok.

Externé orchestrátory, Fabric pipeline a ďalšie automatizačné nástroje môžu po dokončení spustenia zavolať Get Item Job Instance , aby prečítali výstupnú hodnotu a rozvetvili výsledky. Príklad:

1. Odoslať Run on demand Item Job s parametrami a nastaveniami vykonávania.
2. Poll Get Get Item Job Instance, kým status nie je Completed (alebo Failed).
3. Prečítajte exitValue si odpoveď, aby ste zistili, aký je ďalší krok vo vašom pracovnom postupe.

Tento vzor umožňuje podmienenú orchestráciu a signalizáciu na základe výsledkov vykonávania notebooku.

Komplexný príklad

Nasledujúci príklad ukazuje, ako odoslať spustenie zápisníka a získať jeho stav a výstupnú hodnotu. Pre kompletnú schému tela požiadavky, vrátane parametrov, konfigurácie relácie a výberových polí Lakehouse, pozri referenciu Job Scheduler - Run on demand Item Job API.

Krok 1: Odoslať beh

Použite endpoint Run on demand Item Job na spustenie notebooku:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks/{notebookId}/jobs/execute/instances?jobType=RunNotebook

Krok 2: Získanie stavu spustenia a výstupnej hodnoty

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks/{notebookId}/jobs/execute/instances/{jobInstanceId}?beta=true

Príklad odpovede (skrátene):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Čítajte exitValue , aby ste zistili výsledok a podľa toho rozvetvili svoju automatizačnú logiku.