Freigeben über

Verwalten und Ausführen von Notebooks in Fabric mit APIs

  • Artikel

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 der Vorschau.

Hinweis

Die Dienstprinzipal-Authentifizierung wird 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 Notebookelement mit der vorhandenen .ipynb-Datei:

Anforderung

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items

{
    "displayName":"Notebook1",
    "type":"Notebook",
    "definition" : {
        "format": "ipynb",
        "parts": [
            {
                "path": "artifact.content.ipynb",
                "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"
        },
        "trident": {
            "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"
            },
            "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.

Zugehöriger Inhalt