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.

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. Los cuadernos pueden ser orquestados mediante canalizaciones de Fabric y programadores externos a través de estas API, lo que permite una integración sin problemas con flujos de trabajo automatizados.

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

Acción Descripción
Crear elemento Crea un cuaderno en 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 Elimina un cuaderno
Obtener elemento Obtener los metadatos de un cuaderno
Obtención de la definición de elementos Obtiene el 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 Ejecute un cuaderno a petición con compatibilidad con la parametrización, la configuración de sesión (como la configuración de Spark/compute), la selección del entorno y el entorno de ejecución y la selección de Fabric Lakehouse de destino.
Cancelación de la instancia de trabajo del elemento Cancelar una ejecución de trabajo de notebook.
Obtener instancia de trabajo del elemento Obtenga el estado de ejecución del notebook y recupere el valor de salida proporcionado por la ejecución.

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

Nota:

La autenticación de entidad de servicio se admite tanto para la API REST de elementos (operaciones CRUD de notebooks) como para la API del Job Scheduler (ejecución, supervisión y cancelación). Esto permite la automatización desatendida segura y los escenarios de CI/CD. Agregue la entidad de servicio al área de trabajo con un rol adecuado (administrador, miembro o colaborador) para administrar y ejecutar cuadernos.

Valores de salida de ejecuciones de notebooks

Las ejecuciones de notebooks realizadas a través de la API del Programador de Tareas pueden devolver un valor de salida que se puede usar para la orquestación condicional. El valor de salida aparece en el campo exitValue de la carga de respuesta del Get Item Job Instance.

Un cuaderno puede establecer su valor de salida llamando a mssparkutils.notebook.exit("your-value") antes de que se complete la ejecución. El valor de salida es una cadena y puede codificar cualquier señal de resultado, por ejemplo, "success", "no_rows_processed"o un resultado serializado por JSON.

Los orquestadores externos, las canalizaciones de Fabric y otras herramientas de automatización pueden llamar a Get Item Job Instance después de completar la ejecución para leer el valor de salida y ramificar en función de los resultados. Por ejemplo:

  1. Envíe un trabajo de elemento ejecutable bajo demanda con parámetros y ajustes de ejecución.
  2. Consulte Obtener instancia de trabajo de elemento hasta status que sea Completed (o Failed).
  3. Lea exitValue de la respuesta para determinar el siguiente paso del flujo de trabajo.

Este patrón habilita la orquestación condicional y la señalización posterior en función de los resultados de ejecución de notebooks.

Ejemplo integral

En el ejemplo siguiente se muestra cómo enviar una ejecución de cuaderno y recuperar su estado y valor de salida. Para obtener el esquema completo del cuerpo de la solicitud, incluidos los parámetros, la configuración de sesión y los campos de selección de Lakehouse, consulte la referencia de Job Scheduler - Run on demand Item Job API.

Paso 1: Iniciar una ejecución

Utiliza el punto de conexión Ejecutar trabajo de elemento bajo demanda para iniciar un cuaderno:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

La respuesta devuelve 202 Accepted con un Location encabezado que contiene la dirección URL de la instancia de trabajo que se usa para supervisar la ejecución.

Paso 2: Recuperar el estado de ejecución y el valor de salida

Use la dirección URL del Location encabezado para comprobar el estado y leer el valor de salida una vez completada la ejecución:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

Respuesta de ejemplo (abreviada):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Lea exitValue para determinar el resultado y bifurcar la lógica de automatización en consecuencia.

  • Last updated on