Administración y ejecución de cuadernos en Fabric con API
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 está disponible para la API CURD de Notebook. Por ahora, no se admite para ejecutar la API de cuadernos.
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"
},
"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:
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"
},
"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>"
}
}
}
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.