Condividi tramite

Gestire ed eseguire notebook in Fabric con le API

  • Articolo

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.

Importante

Questa funzionalità è in anteprima.

Nota

L'autenticazione dell'entità servizio è disponibile per l'API CRUD notebook. Non è supportato per l'esecuzione dell'API notebook per il momento.

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.

Per i notebook sono disponibili queste azioni di gestione elementi sono disponibili:

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 notebook.
Ottieni elemento Ottiene i metadati di un notebook.
Ottenere una definizione di ruolo 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
Eseguire un processo elemento su richiesta Eseguire il notebook con parametrizzazione.
Annullare l’istanza di un processo elemento Annullare l'esecuzione di un processo del notebook.
Ottenere l'istanza del processo elemento Ottenere lo stato di esecuzione del notebook.

Per ulteriori informazioni, vedere Pianificatore di processi.

Esempi di utilizzo dell'API REST del notebook

Usare le istruzioni seguenti per testare gli esempi di utilizzo per API pubbliche del notebook specifiche e verificare i risultati.

Nota

Questi scenari riguardano solo esempi di utilizzo univoco del notebook. Gli esempi di API comuni degli elementi di Fabric non sono trattati qui.

Prerequisiti

L'API REST di Fabric definisce un endpoint unificato per le operazioni. Sostituire i segnaposto {WORKSPACE_ID} e {ARTIFACT_ID} con i valori appropriati quando si seguono gli esempi in questo articolo.

Creare un notebook con una definizione

Creare un elemento del notebook con un file con estensione ipynb esistente e un altro tipo di file di origine.

Richiedi

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

Il payload nella richiesta è una stringa base64 convertita dal notebook di esempio seguente.

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

Nota

È possibile modificare il lakehouse predefinito del notebook o l'ambiente collegato modificando il contenuto del notebook metadata.trident.lakehouse o metadata.trident.environment.

Ottenere un notebook con una definizione

Usare l'API seguente per ottenere il contenuto del notebook. Fabric supporta l'impostazione del formato .ipynb nella stringa di query per ottenere un notebook .ipynb.

Richiedi

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/GetDefinition?format=ipynb

Risposta

Codice di stato: 200

{
    "definition": {
        "parts": [
            {
                "path": "notebook-content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

Eseguire un notebook su richiesta

Pianificare l'esecuzione del notebook con l'API seguente. Il processo Spark inizia l'esecuzione dopo una richiesta riuscita.

Fabric supporta il passaggio di parameters nel corpo della richiesta per parametrizzare l'esecuzione del notebook. I valori vengono utilizzati dalla cella parametri del notebook.

È anche possibile usare configuration per personalizzare la sessione di Spark di esecuzione del notebook. configuration condivide lo stesso contratto con il comando magic di configurazione della sessione di Spark.

Richiedi

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

Response

Codice di stato: 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

Con location, è possibile usare Ottieni istanza processo elemento per visualizzare lo stato del processo o usare Annulla istanza processo elemento per annullare l'esecuzione del notebook corrente.

Contenuto correlato