Administración y ejecución de cuadernos en Fabric con API

  • Artículo

La API REST de Microsoft Fabric proporciona un punto de conexión de servicio para las operaciones de creación, lectura, actualización y eliminación (CRUD) de un elemento de Fabric. En este artículo se describen las API REST del cuaderno disponibles y su uso.

Importante

Esta característica se encuentra en versión preliminar.

Nota:

La autenticación de entidad de servicio no se admite por ahora.

Con las API de cuadernos, los ingenieros de datos y los científicos de datos pueden automatizar sus propias canalizaciones y establecer CI/CD de forma cómoda y eficaz. Estas API también facilitan a los usuarios la administración y manipulación de elementos de cuadernos de Fabric y la integración de cuadernos con otras herramientas y sistemas.

Estas acciones de administración de elementos están disponibles para los cuadernos:

Acción Descripción
Crear elemento Creación de un cuaderno dentro de un área de trabajo
Actualizar elemento Actualización de los metadatos de un cuaderno
Actualización de la definición de elementos Actualización del contenido de un cuaderno
Eliminar elemento Eliminación de un cuaderno
Obtener elemento Obtención de los metadatos de un cuaderno
Obtención de la definición de elementos Obtención del contenido de un cuaderno
Elemento de lista Enumeración de todos los elementos de un área de trabajo

Para más información, consulte Elementos: API REST.

Las siguientes acciones del programador de trabajos están disponibles para los cuadernos:

Acción Descripción
Ejecución del trabajo de elemento a petición Ejecución del cuaderno con parametrización
Cancelación de la instancia de trabajo del elemento Cancelación de la ejecución del trabajo del cuaderno
Obtención de la instancia de trabajo del elemento Obtención del estado de ejecución del cuaderno

Para más información, consulte Programador de trabajos.

Ejemplos de uso de la API REST de cuadernos

Utilice las instrucciones siguientes para probar ejemplos de uso de API públicas de cuadernos específicos y comprobar los resultados.

Nota:

Estos escenarios solo cubren ejemplos de uso únicos de cuadernos. Los ejemplos de API comunes de elementos de Fabric no se tratan aquí.

Requisitos previos

La API REST de Fabric define un punto de conexión unificado para las operaciones. Reemplace los marcadores de posición {WORKSPACE_ID} y {ARTIFACT_ID} por los valores adecuados cuando siga los ejemplos de este artículo.

Creación de un cuaderno con una definición

Cree un elemento de cuaderno con un archivo .ipynb existente:

Solicitar

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

La carga de la solicitud es una cadena base64 convertida desde el siguiente cuaderno de ejemplo.

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

Nota:

Puede cambiar el almacén de lago predeterminado del cuaderno o el entorno adjunto cambiando el contenido metadata.trident.lakehouse o metadata.trident.environment del cuaderno.

Obtención de un cuaderno con una definición

Use la siguiente API para obtener el contenido del cuaderno. Fabric le permite establecer el formato como .ipynb en la cadena de consulta para obtener un cuaderno .ipynb.

Solicitar

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

Respuesta

Código de estado: 200

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

Ejecución de un cuaderno a petición

Programe la ejecución del cuaderno con la siguiente API. El trabajo de Spark comienza a ejecutarse después de una solicitud correcta.

Fabric admite el paso parameters del cuerpo de la solicitud para parametrizar la ejecución del cuaderno. La celda de parámetros del cuaderno consume los valores.

También puede usar configuration para personalizar la sesión de Spark de la ejecución del cuaderno. configuration comparte el mismo contrato con el comando magic de configuración de sesión de Spark.

Solicitar

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

Respuesta

Código de estado: 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, puede usar Obtener instancia de trabajo de elemento para ver el estado del trabajo o usar Cancelar instancia de trabajo de elemento para cancelar la ejecución del cuaderno actual.

Contenido relacionado