Gestire ed eseguire notebook in Fabric con le API

L'API REST di Microsoft Fabric fornisce un endpoint di servizio per operazioni CRUD (Create, Read, Update, Delete) di un elemento Fabric. Questo articolo descrive le API REST del notebook disponibili e il relativo utilizzo.

Con le API del notebook, i data engineer e i data scientist possono automatizzare le proprie pipeline e stabilire CI/CD in modo pratico ed efficiente. Queste API, inoltre, semplificano agli utenti la gestione e la manipolazione degli elementi dei notebook Fabric e l'integrazione dei notebook con altri strumenti e sistemi. I notebook possono essere gestiti dalle pipeline di Fabric e dai pianificatori esterni tramite queste API, consentendo un'integrazione fluida con i flussi di lavoro automatizzati.

Per i notebook sono disponibili le seguenti azioni di gestione elementi:

Azione Descrizione
Creare elemento Crea un notebook all'interno di un'area di lavoro.
Aggiorna elemento Aggiorna i metadati di un notebook.
Aggiornare una definizione elemento Aggiorna il contenuto di un notebook.
Elimina elemento Elimina un quaderno.
Ottieni elemento Ottiene i metadati di un notebook.
Ottenere la definizione di un elemento Ottiene il contenuto di un notebook.
Elemento di elenco Elencare tutti gli elementi in un'area di lavoro.

Per ulteriori informazioni, vedere Elementi - API REST.

Per i notebook sono disponibili le azioni seguenti del Pianificatore di processi:

Azione Descrizione
Esegui operazione elemento su richiesta Eseguire un notebook su richiesta con il supporto per la parametrizzazione, la configurazione delle sessioni (ad esempio le impostazioni Spark/calcolo), la selezione dell'ambiente e del runtime e la selezione del Fabric Lakehouse di destinazione.
Annullare l’istanza di un processo elemento Annullare l'esecuzione di un processo del notebook.
Ottenere l'istanza del compito elemento Ottenere lo stato di esecuzione del notebook e recuperare il valore di uscita restituito dall'esecuzione.

Per ulteriori informazioni, vedere Pianificatore di processi.

Nota

L'autenticazione del principale del servizio è supportata sia per l'API REST di Items (operazioni CRUD del notebook) che per l'API del Job Scheduler (esecuzione, monitoraggio e annullamento). Ciò consente scenari di automazione senza supervisione e CI/CD sicuri. Aggiungere il principale del servizio all'area di lavoro con un ruolo appropriato (Amministratore, Membro o Collaboratore) per la gestione e l'esecuzione dei notebook.

Valori di uscita dalle esecuzioni del notebook

Le esecuzioni dei notebook eseguite tramite l'API di pianificazione processi (Job Scheduler API) possono restituire un codice di uscita che si può utilizzare per l'orchestrazione condizionale. Il valore di uscita appare nel campo exitValue del payload della risposta dell'istanza di Get Item Job.

Un notebook può impostare il valore di uscita chiamando mssparkutils.notebook.exit("your-value") prima del completamento dell'esecuzione. Il valore di uscita è una stringa e può codificare qualsiasi segnale di risultato, ad esempio , "success""no_rows_processed"o un risultato serializzato JSON.

Gli orchestratori esterni, le pipeline Fabric e altri strumenti di automazione possono chiamare Get Item Job Instance dopo il completamento dell'esecuzione per leggere il valore di uscita e ramificare in base ai risultati. Per esempio:

  1. Inviare un processo di esecuzione su richiesta di un elemento con parametri e impostazioni di esecuzione.
  2. Effettuare il polling dell'istanza del processo Get Item finché status non diventa Completed (o Failed).
  3. Leggere exitValue dalla risposta per determinare il passaggio successivo nel flusso di lavoro.

Questo modello abilita l'orchestrazione condizionale e la segnalazione downstream in base ai risultati dell'esecuzione del notebook.

Esempio da inizio a fine

L'esempio seguente mostra come avviare un'esecuzione di un notebook e recuperarne lo stato e il valore di uscita. Per lo schema completo del corpo della richiesta, inclusi i parametri, la configurazione della sessione e i campi di selezione di Lakehouse, vedere le informazioni di riferimento sull'API Job Scheduler - Run on demand Item Job .For the complete request body schema, including parameters, session configuration, and Lakehouse selection fields, see the Job Scheduler - Run on demand Item Job API reference.

Passaggio 1: Inviare un'esecuzione

Usare l'endpoint Esegui lavoro su richiesta per l'elemento per avviare l'esecuzione di un notebook:

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

La risposta restituisce 202 Accepted con un'intestazione Location contenente l'URL dell'istanza del processo usata per monitorare l'esecuzione.

Passaggio 2: Recuperare lo stato di esecuzione e il valore di uscita

Usare l'URL dell'intestazione Location per controllare lo stato e leggere il valore di uscita al termine dell'esecuzione:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

Risposta di esempio (abbreviata):

{
  "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"
}

Leggere exitValue per determinare il risultato e ramificare la logica di automazione di conseguenza.

  • Last updated on