Verwalten und Ausführen von Notebooks in Fabric mit APIs

Die Microsoft Fabric-REST-API stellt einen Dienstendpunkt für die Erstellungs-, Lese-, Update- und Löschvorgänge (Create, Read, Update and Delete, CRUD) eines Fabric-Elements bereit. In diesem Artikel werden die verfügbaren REST-APIs des Notebooks und deren Verwendung beschrieben.

Mit den Notebook-APIs können Data Engineers und Data Scientists ihre eigenen Pipelines automatisieren und CI/CD komfortabel und effizient einrichten. Diese APIs erleichtern Benutzern auch das Verwalten und Bearbeiten von Fabric-Notebookelementen und die Integration von Notebooks in andere Tools und Systeme. Notizbücher können über diese APIs aus Fabric-Pipelines und externen Schedulern orchestriert werden und ermöglichen eine nahtlose Integration in automatisierte Workflows.

Diese Elementverwaltungsaktionen sind für Notebooks verfügbar:

Vorgang Beschreibung
Create item (Element erstellen) Erstellt ein Notebook innerhalb eines Arbeitsbereichs
Update item (Element aktualisieren) Aktualisiert die Metadaten eines Notebooks
Elementdefinition aktualisieren Aktualisiert den Inhalt eines Notebooks
Delete item (Element löschen) Löscht ein Notebook
Element abrufen Ruft die Metadaten eines Notebooks ab
Elementdefinition abrufen Ruft den Inhalt eines Notebooks ab
Listenelement Listet alle Elemente in einem Arbeitsbereich auf

Weitere Informationen finden Sie unter Elemente – REST-API.

Die folgenden Auftragsplaneraktionen sind für Notebooks verfügbar:

Vorgang Beschreibung
Auf Abruf-Auftrag ausführen Führen Sie ein Notizbuch auf Abruf aus, mit Unterstützung für Parametrisierung, Sitzungskonfiguration (z. B. Spark/Compute-Einstellungen), Umgebungs- und Ausführungszeitauswahl sowie Zielauswahl der Fabric Lakehouse.
Abbrechen der Elementauftragsinstanz Abbrechen eines Notizbuchauftrags
Aufrufen der Elementauftragsinstanz Rufen Sie den Status der Notizbuchausführung ab, und rufen Sie den von der Ausführung zurückgegebenen Ausgangswert ab.

Weitere Informationen finden Sie unter Auftragsplaner.

Hinweis

Die Dienstprinzipalauthentifizierung wird sowohl für die Items-REST-API (Notizbuch-CRUD-Vorgänge) als auch für die Auftragsplanungs-API (Ausführung, Überwachung und Abbruch) unterstützt. Dies ermöglicht sichere unbeaufsichtigte Automatisierungs- und CI/CD-Szenarien. Fügen Sie den Dienstprinzipal dem Arbeitsbereich mit einer entsprechenden Rolle (Administrator, Mitglied oder Mitwirkender) hinzu, um Notizbücher zu verwalten und auszuführen.

Ergebniswerte aus Notebook-Ausführungen

Notizbuchausführungen, die über die Auftragsplanungs-API ausgeführt werden, können einen Beendigungswert zurückgeben, den Sie für die bedingte Orchestrierung verwenden können. Der Ausgangswert wird im exitValue-Feld der Antwortnutzlast der Get-Item-Job-Instanz angezeigt.

Ein Notizbuch kann seinen Ausgangswert festlegen, indem es vor Abschluss der Ausführung mssparkutils.notebook.exit("your-value") aufruft. Der Ausgangswert ist eine Zeichenfolge und kann jedes Ergebnissignal codieren , z. B. , "success", "no_rows_processed"oder ein JSON-serialisiertes Ergebnis.

Externe Orchestratoren, Fabric-Pipelines und andere Automatisierungstools können die Get Item Job Instance aufrufen, nachdem die Ausführung abgeschlossen wurde, um den Ergebniswert zu lesen und basierend auf den Ergebnissen eine Verzweigung vorzunehmen. Beispiel:

  1. Übermitteln Sie einen "On-Demand-Elementauftrag" mit Parametern und Ausführungseinstellungen.
  2. Abfragen der Elementauftragsinstanz bis status ( Completed oder Failed).
  3. Lesen Sie exitValue aus der Antwort, um den nächsten Schritt in Ihrem Workflow zu bestimmen.

Dieses Muster ermöglicht die bedingte Orchestrierung und nachgeschaltete Signalisierung basierend auf den Ergebnissen der Notizbuchausführung.

Vollständiges Beispiel

Das folgende Beispiel zeigt, wie Sie ein Notizbuch ausführen und dessen Status- und Ausgangswert abrufen. Informationen zum vollständigen Anforderungsschema, einschließlich der Lakehouse-Auswahlfelder, der Sitzungskonfiguration und der Parameter, finden Sie in der API-Referenz für die Auftragsplanung - Auftrag bei Bedarf ausführen.

Schritt 1: Übermitteln einer Ausführung

Verwenden Sie den Endpunkt "On Demand Item Job ausführen ", um eine Notizbuchausführung zu starten:

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

Die Antwort wird mit einem 202 Accepted Header zurückgegebenLocation, der die URL der Auftragsinstanz enthält, die Sie zum Überwachen der Ausführung verwenden.

Schritt 2: Abrufen des Ausführungsstatus und des Rückgabewerts

Verwenden Sie die URL aus der Location Kopfzeile, um den Status zu überprüfen und den Ausgangswert nach Abschluss der Ausführung zu lesen:

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

Beispielantwort (gekürzt):

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

Lesen Sie exitValue , um das Ergebnis zu bestimmen und Ihre Automatisierungslogik entsprechend zu verzweigen.

  • Last updated on