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.
Wichtig
Dieses Feature befindet sich in Vorschau.
Hinweis
Die Dienstprinzipalauthentifizierung ist für die Notebook-CRUD-API verfügbar. Sie wird für die API zur Ausführung von Notebooks derzeit nicht unterstützt.
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.
Diese Elementverwaltungsaktionen sind für Notebooks verfügbar:
| Aktion | Beschreibung |
|---|---|
| Create item (Element erstellen) | Erstellt ein Notebook innerhalb eines Arbeitsbereichs |
| Update item (Element aktualisieren) | Aktualisiert die Metadaten eines Notebooks |
| Update item definition | Aktualisiert den Inhalt eines Notebooks |
| Delete item (Element löschen) | Löscht ein Notebook |
| Element abrufen | Ruft die Metadaten eines Notebooks ab |
| Get item definition | 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:
| Aktion | Beschreibung |
|---|---|
| Run on demand Item Job | Führt ein Notebook mit Parametrisierung aus |
| Cancel Item Job Instance | Bricht einen Notebookauftrag ab |
| Get Item Job Instance | Ruft den Status der Notebookausführung ab |
Weitere Informationen finden Sie unter Auftragsplaner.
Beispiele für die Verwendung von Notebook-REST-APIs
Befolgen Sie die folgenden Anweisungen, um Verwendungsbeispiele für bestimmte öffentliche APIs des Notebooks zu testen und die Ergebnisse zu überprüfen.
Hinweis
In diesen Szenarios umfassen nur Beispiele für die Verwendung von Notebooks. Allgemeine API-Beispiele für Fabric-Elemente werden hier nicht behandelt.
Voraussetzungen
Die Fabric-REST-API definiert einen einheitlichen Endpunkt für Vorgänge. Ersetzen Sie die Platzhalter {WORKSPACE_ID} und {ARTIFACT_ID} durch entsprechende Werte, wenn Sie den Beispielen in diesem Artikel befolgen.
Erstellen eines Notizbuchs mit einer Definition
Erstellen Sie ein Notebook-Element mit einer vorhandenen IPYNB-Datei und anderen Quelldateien.
Anforderung
POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items
{
"displayName":"Notebook1",
"type":"Notebook",
"definition" : {
"format": "ipynb", // Use "fabricGitSource" for source file format.
"parts": [
{
"path": "notebook-content.ipynb", // fabric source file format, .py, .scala, .sql files are supported.
"payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
"payloadType": "InlineBase64"
}
]
}
}
Die Payload in der Anforderung ist eine base64-Zeichenfolge, die aus dem folgenden Beispielnotebook konvertiert wird.
{
"nbformat": 4,
"nbformat_minor": 5,
"cells": [
{
"cell_type": "code",
"source": [
"# Welcome to your new notebook\n# Type here in the cell editor to add code!\n"
],
"execution_count": null,
"outputs": [],
"metadata": {}
}
],
"metadata": {
"language_info": {
"name": "python"
},
"dependencies": {
"environment": {
"environmentId": "6524967a-18dc-44ae-86d1-0ec903e7ca05",
"workspaceId": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
},
"lakehouse": {
"default_lakehouse": "5b7cb89a-81fa-4d8f-87c9-3c5b30083bee",
"default_lakehouse_name": "lakehouse_name",
"default_lakehouse_workspace_id": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
}
}
}
}
Hinweis
Sie können das Standardlakehouse oder die angefügte Umgebung des Notebooks ändern, indem Sie metadata.trident.lakehouse oder metadata.trident.environment für den Notebookinhalt ausführen.
Abrufen eines Notebooks mit einer Definition
Verwenden Sie die folgende API, um den Notebookinhalt abzurufen. Fabric unterstützt das Festlegen des Formats als .ipynb in der Abfragezeichenfolge, um ein .ipynb-Notebook abzurufen.
Anforderung
POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/GetDefinition?format=ipynb
Antwort
Statuscode: 200
{
"definition": {
"parts": [
{
"path": "notebook-content.ipynb",
"payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
"payloadType": "InlineBase64"
}
]
}
}
Ausführen eines Notebooks bei Bedarf
Planen Sie die Ausführung Ihres Notebooks mit der folgenden API. Der Spark-Auftrag wird nach einer erfolgreichen Anforderung ausgeführt.
Fabric unterstützt das Übergeben von parameters im Anforderungstext, um die Notebookausführung zu parametrisieren. Die Werte werden von der Notebookparameterzelle verwendet.
Sie können die Spark-Sitzung der Notebookausführung auch mit configuration personalisieren. configuration hat denselben Vertrag wie der Magic-Befehl für die Spark-Sitzungskonfiguration.
Anforderung
POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/jobs/instances?jobType=RunNotebook
{
"executionData": {
"parameters": {
"parameterName": {
"value": "new value",
"type": "string"
}
},
"configuration": {
"conf": {
"spark.conf1": "value"
},
"environment": {
"id": "<environment_id>",
"name": "<environment_name>"
},
"defaultLakehouse": {
"name": "<lakehouse-name>",
"id": "<lakehouse-id>",
"workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>"
},
"useStarterPool": false,
"useWorkspacePool": "<workspace-pool-name>"
}
}
}
Antwort
Statuscode: 202
Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60
Mit location können Sie Get Item Job Instance verwenden, um den Auftragsstatus anzuzeigen, oder Sie können Cancel Item Job Instance nutzen, um die aktuelle Notebookausführung zu beenden.