Habilitar las notificaciones del ciclo de vida de elementos

Las notificaciones del ciclo de vida de los elementos proporcionan a los generadores de cargas de trabajo la capacidad de recibir notificaciones sobre los eventos de ciclo de vida de los elementos personalizados, incluso cuando la experiencia de usuario de la carga de trabajo no está en el bucle. Esta configuración permite que el elemento responda a las operaciones de elemento independientemente de cómo se iniciaron.

Visión general

Las notificaciones del ciclo de vida de los elementos son esenciales para escenarios en los que se crean, actualizan o eliminan elementos fuera de la interfaz de usuario de la carga de trabajo. Este servicio notifica a tu carga de trabajo cada vez que ocurre un evento en el ciclo de vida de un elemento, permitiéndole:

• Implementación o desmantelamiento de la infraestructura para elementos nuevos o eliminados
• Validar licencias o cuotas antes de permitir operaciones
• Sincronizar el estado con sistemas externos
• Implementación de lógica empresarial personalizada para las operaciones de artículos
• Manejo de escenarios de eliminación suave con lógica de depuración personalizada

Cuando se desencadenan las notificaciones del ciclo de vida

Las notificaciones del ciclo de vida se desencadenan para las operaciones de elementos que se originan en varios orígenes:

API públicas

Los elementos se pueden crear, actualizar o eliminar mediante las API REST públicas de Fabric sin interacción con la UI de su carga de trabajo. Por ejemplo:

• Scripts de Automatización usando la API Items
• Aplicaciones de terceros que se integran con Fabric
• Operaciones administrativas realizadas mediante programación

Tuberías de CI/CD

Los elementos se implementan a través de las funcionalidades de CI/CD de Fabric como parte de las canalizaciones de implementación automatizadas. En este escenario:

• Los elementos se crean o actualizan como parte de los flujos de trabajo de integración de Git.
• Los pipelines de implementación promueven elementos entre entornos
• No se produce ninguna interacción de la interfaz de usuario durante el proceso de implementación

Flujos de experiencia de usuario controlados por la plataforma

Incluso dentro de la interfaz de usuario Fabric, la plataforma controla determinados flujos de creación y administración. La carga de trabajo recibe notificaciones de estas operaciones para mantener la coherencia:

• Creación de elementos mediante diálogos de plataforma
• Operaciones de nivel de área de trabajo que afectan a los elementos
• Operaciones de copia o movimiento entre áreas de trabajo

Eventos de ciclo de vida

La carga de trabajo puede recibir notificaciones para los siguientes eventos de ciclo de vida:

Crear

Se desencadena cuando se crea un nuevo elemento. Ustedes pueden:

• Configuración de la infraestructura necesaria (bases de datos, recursos de proceso)
• Validación de licencias o cuotas de capacidad
• Inicializar recursos específicos del elemento
• Bloquear la operación si se produce un error en la validación o no se cumplen los requisitos previos

Actualización

Se desencadena cuando se modifican las propiedades o la definición de un elemento. Ustedes pueden:

• Actualización de la infraestructura asociada
• Validación de la nueva configuración
• Sincronización de cambios con sistemas externos
• Bloquear la operación si la actualización infringe las reglas de negocio

Eliminar

Se desencadena cuando se elimina un elemento. La solicitud incluye un deleteType campo que indica si se trata de una eliminación temporal o dura:

• Eliminación definitiva: borrado permanente - limpieza de todos los recursos asociados
• Eliminación temporal: el elemento está marcado para su eliminación, pero se puede restaurar más adelante: conserve los metadatos y recursos suficientes para admitir la restauración.

La carga de trabajo puede elegir diferentes estrategias para la eliminación temporal:

• Detener recursos de computación costosos sin perder datos
• Archivar datos críticos para un almacenamiento de menor costo
• Conservar el estado completo durante el período de recuperación

Restauración

Se desencadena cuando se restaura un elemento eliminado temporalmente anteriormente. El punto de conexión recibe la definición del elemento y debe:

• Reasignar recursos que se liberaron durante el borrado lógico
• Restaurar el estado del elemento y reanudar los servicios
• Reinicialización de los recursos de proceso o almacenamiento según sea necesario

Formato de solicitud

Fabric invoca un endpoint separado para cada evento del ciclo de vida. Cada solicitud incluye:

Parámetros de ruta de URL

La información de identificación del elemento se proporciona en la ruta de acceso de la dirección URL:

• workspaceId : el identificador del área de trabajo (UUID)
• itemType : el tipo de elemento (por ejemplo, Contoso.FinanceAnalytics.Forecast)
• itemId - El identificador de elemento (UUID)

Encabezado de autenticación

El Authorization encabezado usa el SubjectAndAppToken1.0 esquema que contiene un token de usuario delegado y un token exclusivamente para aplicaciones:

SubjectAndAppToken1.0 subjectToken="<delegated token>", appToken="<S2S token>"

Este formato de doble token permite que la carga de trabajo valide el origen de la solicitud, compruebe el contexto del usuario y llame a otros servicios. Los encabezados necesarios adicionales incluyen ActivityId, RequestIdy x-ms-client-tenant-id.

Para más información sobre cómo validar estos tokens, consulte Autenticación de puntos de conexión remotos.

Cuerpo de la solicitud

El cuerpo de la solicitud varía según la operación:

• Crear, actualizar y restaurar: el cuerpo contiene un ItemDefinition objeto con una parts matriz. Cada parte tiene un path, payload (codificado en Base64) y payloadType.
• Delete: el cuerpo contiene un deleteType campo con un valor de Hard o Soft.

La información del cuerpo de la solicitud le permite:

• Extracción de la configuración de la infraestructura durante la creación y restauración
• Comprender qué ha cambiado en las operaciones de actualización
• Tomar decisiones fundamentadas sobre las operaciones de bloqueo
• Elija la estrategia de limpieza adecuada para eliminaciones definitivas o suaves

Operaciones de bloqueo

Para las operaciones de crear y actualizar la carga de trabajo puede bloquear la operación al devolver una respuesta de error desde el endpoint del ciclo de vida. Esto es útil para:

• Validación de licencias: impedir la creación de elementos si el usuario no tiene licencias necesarias
• Aplicación de cuotas: bloquear la creación si se superan los límites de espacio de trabajo o capacidad
• Validación de configuración: rechazar las actualizaciones que crearían estados no válidos
• Directivas de seguridad: aplicar directivas organizativas en configuraciones de elementos

Al bloquear una operación:

1. Devolver un código de estado de error (por ejemplo, 400 o 403) desde el endpoint.
2. Proporcione un mensaje de error claro que explique por qué se bloqueó la operación
3. La plataforma muestra el mensaje de error al usuario.
4. La operación del elemento no se ha completado

Implementación de la gestión de notificaciones del ciclo de vida

Las notificaciones de ciclo de vida definidas en elementos personalizados no se pueden controlar directamente en Fabric. En su lugar, debe implementar un punto de conexión remoto al que llama Fabric cuando ocurre un evento del ciclo de vida. Esto le proporciona control total sobre dónde y cómo se ejecuta la lógica de control de notificaciones.

El punto de conexión remoto puede ser:

• An Azure Function: ejecución simple y sin servidor para el control ligero de notificaciones
• An Azure Container Instance: para las notificaciones que requieren entornos en tiempo de ejecución específicos
• Un servicio web personalizado : para orquestación y procesamiento complejos
• Cualquier servicio de proceso : siempre que pueda exponer un punto de conexión HTTP y controlar la notificación

Para obtener información detallada sobre cómo implementar y configurar puntos de conexión remotos, consulte Habilitación de puntos de conexión remotos.

Configuración

Para habilitar las notificaciones de ciclo de vida para el elemento personalizado, configure las notificaciones en el manifiesto del elemento.

Definir las notificaciones del ciclo de vida en el manifiesto de elemento

Agregue la configuración de notificación del ciclo de vida al manifiesto del elemento:

<Item>
    <Name>YourItemType</Name>
    <!-- Other item configuration -->
    
    <LifecycleOperationsNotifications>
        <OnCreate>true</OnCreate>
        <OnUpdate>true</OnUpdate>
        <OnDelete>true</OnDelete>
    </LifecycleOperationsNotifications>
</Item>

Configure solo los eventos que necesita controlar. Establezca el valor false en o omita el elemento si no necesita notificaciones para un tipo de evento específico.

Requisitos del punto de conexión

El endpoint de ciclo de vida debe:

• Ser accesible públicamente a través de HTTPS
• Responder dentro de un tiempo de espera razonable (recomendado: 30 segundos)
• Devolver códigos de estado HTTP adecuados
• Control de la autenticación mediante el token proporcionado

Para crear y actualizar operaciones que desea bloquear:

• Devolver el código de estado 4xx con detalles de error
• Incluir un mensaje de error amigable para el usuario en el cuerpo de la respuesta

Para las operaciones que se realizan correctamente o para las operaciones de eliminación y restauración:

• Devolver el código de estado 200 OK
• Opcionalmente, incluya información de registro o seguimiento.

Apoyo al desarrollo local

Para el desarrollo y las pruebas locales, el Kit de Herramientas de Extensibilidad de Fabric proporciona una implementación de stub integrada en el servidor de desarrollo. Esto le permite probar las notificaciones del ciclo de vida de los elementos en el equipo local sin implementar en Azure.

Funcionamiento

Al ejecutar el servidor de desarrollo local (consulte Get started with Fabric Extensibility Toolkit and Register Local Web Server), todas las notificaciones de ciclo de vida definidas en el manifiesto de elemento se redirigen automáticamente a la máquina local.

Cuando se produce un evento de ciclo de vida en modo de desarrollo:

1. El servidor de desarrollo local intercepta la notificación.
2. Los mensajes de registro aparecen en la consola local mostrando los detalles del evento.
3. Una implementación de ejemplo muestra cómo interactuar con la definición de elemento y el almacenamiento de OneLake
4. Recibe un token que se puede usar para llamar a cualquier operación de Fabric.

Esta implementación de código auxiliar proporciona:

• Retroalimentación inmediata - vea las declaraciones de registro en su consola a medida que ocurren eventos del ciclo de vida.
• Código de ejemplo : aprenda a estructurar la lógica de control de notificaciones
• Ejemplos de integración de OneLake : vea cómo acceder al almacenamiento oneLake del elemento durante las notificaciones.
• Manejo de tokens: cómo obtener y usar tokens de autenticación de Fabric
• Acceso a la definición de elemento : visualización de la carga completa de la definición de elemento

Uso del Stub de Desarrollo

Para usar el servidor de desarrollo local para las pruebas de notificación del ciclo de vida:

1. Inicie el servidor de desarrollo local siguiendo la guía de inicio rápido.
2. Registro del servidor web local mediante los pasos de registro
3. Configura las notificaciones del ciclo de vida en el manifiesto del elemento como se ha descrito anteriormente
4. Realizar operaciones de elemento (crear, actualizar, eliminar) en Fabric
5. Observe los detalles de notificación en la consola local.
6. Revise el código de ejemplo para la interacción de OneLake y el control de tokens en los registros del servidor de desarrollo.

Ejemplo de interacción de OneLake

El stub de desarrollo incluye código de ejemplo que muestra cómo interactuar con el almacenamiento OneLake del ítem.

// Example from the development stub
const tokenExchangeService = require('./tokenExchangeService');
const oneLakeClientService = require('./oneLakeClientService');

async function handleCreateWithOneLakeAccess(req) {
  const { workspaceId, itemId } = req.params;
  const { subjectToken, tenantId } = req.authContext;

  // Exchange user token for OneLake-scoped token
  const oneLakeToken = await tokenExchangeService.getTokenForScope(
    subjectToken, tenantId, oneLakeClientService.ONELAKE_SCOPE);

  // Write to the item's OneLake storage
  const filePath = oneLakeClientService.getOneLakeFilePath(
    workspaceId, itemId, 'config.json');
  const content = JSON.stringify(req.body, null, 2);
  await oneLakeClientService.writeToOneLakeFile(oneLakeToken, filePath, content);

  console.log(`Initialized item configuration in OneLake at ${filePath}`);
}

Esta experiencia de desarrollo local le permite crear y probar la lógica de notificación del ciclo de vida antes de implementarla en puntos de conexión de producción.

Ejemplo de implementación

En el ejemplo siguiente se usa Node.js y Express, en función de la implementación de referencia Fabric Extensibility Toolkit. Cada evento de ciclo de vida tiene su propio punto de conexión que Fabric llama con el cuerpo de solicitud adecuado. Para obtener detalles completos de la API, consulte la referencia de la API REST de ciclo de vida de elementos.

const express = require('express');
const { authenticateControlPlaneCall } = require('./authentication');
const router = express.Router();

// POST /workspaces/{workspaceId}/items/{itemType}/{itemId}/onCreateItem
// Request body: { definition: { parts: [{ path, payload, payloadType }] } }
router.post('/workspaces/:workspaceId/items/:itemType/:itemId/onCreateItem',
  async (req, res) => {
    const authResult = await authenticateControlPlaneCall(req, res);
    if (!authResult) return;

    const { workspaceId, itemId, itemType } = req.params;
    const { definition } = req.body;

    // Validate license before allowing creation
    const hasLicense = await checkUserLicense(req.authContext.userId);
    if (!hasLicense) {
      return res.status(403).json({
        errorCode: 'LicenseRequired',
        message: 'User does not have the required license for this item type.',
        source: 'User',
        isPermanent: true
      });
    }

    // Set up infrastructure for the new item
    await provisionResources(workspaceId, itemId, definition);

    console.log(`Created item ${itemId} of type ${itemType}`);
    res.status(200).json({});
  }
);

// POST /workspaces/{workspaceId}/items/{itemType}/{itemId}/onUpdateItem
// Request body: { definition: { parts: [{ path, payload, payloadType }] } }
router.post('/workspaces/:workspaceId/items/:itemType/:itemId/onUpdateItem',
  async (req, res) => {
    const authResult = await authenticateControlPlaneCall(req, res);
    if (!authResult) return;

    const { workspaceId, itemId } = req.params;
    const { definition } = req.body;

    // Validate the updated definition
    if (!isValidConfiguration(definition)) {
      return res.status(400).json({
        errorCode: 'InvalidConfiguration',
        message: 'Invalid configuration: required settings are missing.',
        source: 'User',
        isPermanent: true
      });
    }

    await updateResources(workspaceId, itemId, definition);

    console.log(`Updated item ${itemId}`);
    res.status(200).json({});
  }
);

// POST /workspaces/{workspaceId}/items/{itemType}/{itemId}/onDeleteItem
// Request body: { deleteType: "Hard" | "Soft" }
// Note: Subject token may not be available during delete operations.
router.post('/workspaces/:workspaceId/items/:itemType/:itemId/onDeleteItem',
  async (req, res) => {
    const authResult = await authenticateControlPlaneCall(req, res,
      { requireSubjectToken: false });
    if (!authResult) return;

    const { workspaceId, itemId } = req.params;
    const { deleteType } = req.body;

    if (deleteType === 'Hard') {
      await deleteAllResources(workspaceId, itemId);
      console.log(`Hard deleted item ${itemId}`);
    } else if (deleteType === 'Soft') {
      // Retain metadata for recovery; optionally free expensive resources
      await stopComputeResources(workspaceId, itemId);
      console.log(`Soft deleted item ${itemId}`);
    }

    res.status(200).json({});
  }
);

// POST /workspaces/{workspaceId}/items/{itemType}/{itemId}/onRestoreItem
// Request body: { definition: { parts: [{ path, payload, payloadType }] } }
// Called when a soft-deleted item is restored.
router.post('/workspaces/:workspaceId/items/:itemType/:itemId/onRestoreItem',
  async (req, res) => {
    const authResult = await authenticateControlPlaneCall(req, res,
      { requireSubjectToken: false });
    if (!authResult) return;

    const { workspaceId, itemId } = req.params;
    const { definition } = req.body;

    // Re-allocate resources freed during soft delete
    await restoreResources(workspaceId, itemId, definition);

    console.log(`Restored item ${itemId}`);
    res.status(200).json({});
  }
);

Casos de uso

Administración de infraestructura

Aprovisionar y desaprovisionar automáticamente la infraestructura en función del ciclo de vida de los elementos:

// In onCreateItem handler: Provision resources
await createSqlDatabase(itemId);
await createStorageAccount(itemId);
await createComputeCluster(itemId);

// In onDeleteItem handler (deleteType === 'Hard'): Clean up resources
await deleteSqlDatabase(itemId);
await deleteStorageAccount(itemId);
await deleteComputeCluster(itemId);

Validación de licencias y cuotas

Aplique los requisitos de licencia y capacidad en el onCreateItem controlador:

// Check user license before allowing creation
const userLicense = await getUserLicense(req.authContext.userId);
if (userLicense.tier < REQUIRED_TIER_PREMIUM) {
  return res.status(403).json({
    errorCode: 'LicenseRequired',
    message: 'Premium license required for this item type.',
    source: 'User',
    isPermanent: true
  });
}

// Check workspace capacity
const workspaceUsage = await getWorkspaceUsage(workspaceId);
if (workspaceUsage.itemCount >= workspaceUsage.maxItems) {
  return res.status(403).json({
    errorCode: 'QuotaExceeded',
    message: 'Workspace item limit reached.',
    source: 'User',
    isPermanent: false
  });
}

Sincronización de sistema externo

Mantenga los sistemas externos sincronizados con los elementos de Fabric:

// In onCreateItem handler: Sync item to external catalog
const { workspaceId, itemId, itemType } = req.params;
await externalCatalog.registerItem({
  id: itemId,
  type: itemType,
  workspaceId: workspaceId
});

// Update external monitoring
await monitoringSystem.trackItemCreated(workspaceId, itemId);

Estrategia de eliminación y restauración

Implemente diferentes estrategias de limpieza basadas en deleteTypey controle la restauración:

// In onDeleteItem handler:
const { deleteType } = req.body;

if (deleteType === 'Soft') {
  // Free expensive resources but retain data for potential recovery
  await stopExpensiveCompute(itemId);
  await archiveDataToLowCostStorage(itemId);
}

if (deleteType === 'Hard') {
  // Permanent deletion - clean up everything
  await deleteAllResources(itemId);
}

// In onRestoreItem handler:
// Re-allocate resources freed during soft delete
await restartCompute(itemId);
await restoreDataFromArchive(itemId);

Procedimientos recomendados

Responder rápidamente

Los puntos de conexión del ciclo de vida deben responder lo antes posible:

• Realizar operaciones de validación y configuración rápida sincrónicamente
• Aprovisionamiento de infraestructura de larga duración en cola para el procesamiento en segundo plano
• Devolver el éxito o el error rápidamente para evitar tiempos de espera

Controlar la idempotencia

Las operaciones de ítem pueden repetirse, por lo que el endpoint debe ser idempotente:

• Compruebe si la infraestructura ya existe antes de crearla
• Uso de identificadores únicos para realizar un seguimiento de las operaciones
• Manejar notificaciones duplicadas eficientemente

Proporcionar mensajes de error claros

Al bloquear las operaciones, proporcione mensajes de error útiles:

// Good: Structured ErrorResponse with a clear message
return res.status(403).json({
  errorCode: 'LicenseRequired',
  message: 'Cannot create item: Premium license required. Upgrade your subscription.',
  source: 'User',
  isPermanent: true
});

// Poor: Missing structured error information
return res.status(403).json({ message: 'Forbidden' });

Seguridad

• Validación del token de autenticación en cada solicitud
• Uso del token para comprobar que la operación es legítima
• No confiar en identificadores de elemento ni identificadores de área de trabajo sin validación
• Consulte Autenticación de puntos de conexión remotos para conocer los procedimientos recomendados de seguridad.

Supervisión y registro

• Registrar todas las notificaciones del ciclo de vida recibidas
• Seguimiento del éxito o fallo en el aprovisionamiento de infraestructura
• Supervisión del rendimiento y los errores del punto de conexión
• Uso de los datos de notificación para los seguimientos de auditoría

Solución de problemas

Notificaciones no recibidas

• Compruebe que la dirección URL del punto de conexión es correcta en el manifiesto
• Compruebe que el punto de conexión es accesible públicamente
• Asegúrese de que HTTPS está configurado correctamente
• Revisión de los registros de puntos de conexión para ver si hay errores

Interrupción por tiempo de espera en operaciones

• Optimizar el tiempo de respuesta del punto de conexión
• Traslado de operaciones de ejecución prolongada a trabajos en segundo plano
• Aumentar la configuración del tiempo de espera del punto de conexión si es necesario
• Revisión del rendimiento del aprovisionamiento de infraestructura

"El bloqueo no funciona"

• Verifique que está devolviendo códigos de estado 4xx para las operaciones bloqueadas.
• Compruebe que los mensajes de error se incluyen en la respuesta.
• Asegúrese de que el punto de conexión responde dentro de la ventana de tiempo de espera.
• Recuerde que no se pueden bloquear las operaciones de eliminación: la plataforma Fabric marca el elemento como eliminado independientemente de la respuesta de la carga de trabajo.

Contenido relacionado

• Autenticación de puntos de conexión remotos
• Habilitación de puntos de conexión remotos
• Definición de elemento de almacén
• Define trabajos para tu carga de trabajo
• Comience con Fabric Extensibility Toolkit
• Registrar servidor web local
• Fabric API de administración de elementos
• Visión general de CI/CD de Fabric
• Referencia de la API REST de ciclo de vida de elementos