Habilitar notificações do ciclo de vida do item

As notificações do ciclo de vida do item fornecem aos construtores de carga de trabalho a capacidade de receber notificações sobre eventos de ciclo de vida para itens personalizados, mesmo quando a UX da carga de trabalho não está no loop. Essa configuração permite que seu item responda às operações de item, independentemente de como elas foram iniciadas.

Visão geral

As notificações do ciclo de vida do item são essenciais para cenários em que os itens são criados, atualizados ou excluídos fora da interface do usuário da carga de trabalho. Esse serviço notifica sua carga de trabalho sempre que ocorrer um evento de ciclo de vida de item, permitindo que você:

• Configurar ou desativar a infraestrutura para itens criados ou removidos
• Validar licenças ou cotas antes de permitir operações
• Sincronizar o estado com sistemas externos
• Implementar lógica de negócios personalizada para operações de itens
• Gerenciar cenários de exclusão suave com lógica personalizada de limpeza

Quando as notificações do ciclo de vida são ativadas

As notificações do ciclo de vida são disparadas para operações de item originadas de várias fontes:

APIs públicas

Os itens podem ser criados, atualizados ou excluídos por meio das APIs REST públicas do Fabric sem nenhuma interação com a interface do usuário da carga de trabalho. Por exemplo:

• Scripts de automação usando a API de Itens
• Aplicativos de terceiros que se integram ao Fabric
• Operações administrativas executadas programaticamente

CI/CD Pipelines

Os itens são implantados por meio das funcionalidades de CI/CD do Fabric como parte de pipelines de implantação automatizados. Neste cenário:

• Os itens são criados ou atualizados como parte dos fluxos de trabalho de integração do Git
• Pipelines de implantação promovem itens entre ambientes
• Nenhuma interação de interface do usuário ocorre durante o processo de implantação

Fluxos de experiência do usuário controlados pela plataforma

Mesmo dentro da interface do usuário Fabric, a plataforma controla determinados fluxos de criação e gerenciamento. Sua carga de trabalho recebe notificações para essas operações para manter a consistência:

• Criação de item por meio de diálogos da plataforma
• Operações no nível do workspace que afetam itens
• Operações de cópia ou movimentação entre espaços de trabalho

Eventos de ciclo de vida

Sua carga de trabalho pode receber notificações para os seguintes eventos de ciclo de vida:

Criar

Acionado quando um novo item é criado. É possível:

• Configurar a infraestrutura necessária (bancos de dados, recursos de computação)
• Validar licenças ou cotas de capacidade
• Inicializar recursos específicos do item
• Bloquear a operação se a validação falhar ou os pré-requisitos não forem atendidos

Atualização

Disparado quando a definição ou as propriedades de um item são modificadas. É possível:

• Atualizar a infraestrutura associada
• Validar a nova configuração
• Sincronizar alterações com sistemas externos
• Bloquear a operação se a atualização violar as regras de negócios

excluir

Disparado quando um item é excluído. A solicitação inclui um deleteType campo que indica se é uma exclusão dura ou reversível:

• Exclusão permanente: remover de forma irreversível – limpar todos os recursos associados
• Exclusão reversível: o item está marcado para exclusão, mas pode ser restaurado posteriormente – reter metadados e recursos suficientes para dar suporte à restauração

Sua carga de trabalho pode escolher estratégias diferentes para exclusão reversível:

• Suspender recursos computacionais caros enquanto retém os dados
• Arquivar dados críticos para armazenamento de menor custo
• Manter o estado completo para o período de recuperação

Restaurar

Disparado quando um item excluído temporariamente é restaurado. O ponto de extremidade recebe a definição do item e deve:

• Realocar recursos que foram liberados durante a exclusão suave
• Restaurar o estado do item e retomar os serviços
• Reinicializar recursos de computação ou armazenamento conforme necessário

Formato de solicitação

Fabric chama um endpoint separado para cada evento do ciclo de vida. Cada solicitação inclui:

Parâmetros de caminho de URL

As informações de identificação do item são fornecidas no caminho da URL:

• workspaceId - O ID do workspace (UUID)
• itemType - O tipo de item (por exemplo, Contoso.FinanceAnalytics.Forecast)
• itemId - O ID do item (UUID)

Cabeçalho de autenticação

O Authorization cabeçalho usa o SubjectAndAppToken1.0 esquema, que contém um token de usuário delegado e um token somente de aplicativo:

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

Esse formato de token duplo permite que sua carga de trabalho valide a origem da solicitação, verifique o contexto do usuário e chame outros serviços. Cabeçalhos extras necessários incluem ActivityId, RequestIde x-ms-client-tenant-id.

Para obter detalhes sobre como validar esses tokens, consulte Authenticate Remote Endpoints.

Corpo da solicitação

O corpo da solicitação varia de acordo com a operação:

• Criar, Atualizar e Restaurar: o corpo contém um ItemDefinition objeto com uma parts lista. Cada parte tem um path, payload (codificado em Base64) e payloadType.
• Excluir: o corpo contém um deleteType campo com um valor de Hard ou Soft.

As informações no corpo da solicitação permitem que você:

• Extrair configuração para configuração de infraestrutura durante a criação e restauração
• Entender o que mudou nas operações de atualização
• Tomar decisões informadas sobre operações de bloqueio
• Escolha a estratégia de limpeza apropriada para exclusões difíceis versus temporárias

Operações de bloqueio

Para operações de criação e atualização, seu processamento pode bloquear a operação retornando uma resposta de erro do ponto de extremidade do ciclo de vida. Isso é útil para:

• Validação de licença: impedir a criação do item se o usuário não tiver licenças necessárias
• Imposição de cota: Bloquear a criação se os limites de espaço de trabalho ou capacidade forem excedidos
• Validação de configuração: rejeitar atualizações que criariam estados inválidos
• Políticas de segurança: impor políticas organizacionais em configurações de item

Quando você bloqueia uma operação:

1. Retornar um código de status de erro (por exemplo, 400 ou 403) a partir do endpoint
2. Forneça uma mensagem de erro clara explicando por que a operação foi bloqueada
3. A plataforma exibe sua mensagem de erro para o usuário
4. A operação do item não foi concluída

Implementando o gerenciamento de notificações do ciclo de vida

As notificações do ciclo de vida definidas em itens personalizados não podem ser tratadas diretamente no Fabric. Em vez disso, você precisa implementar um ponto de extremidade remoto que o Fabric chama quando ocorre um evento de ciclo de vida. Isso fornece controle total sobre onde e como a lógica de tratamento de notificação é executada.

O ponto de extremidade remoto pode ser:

• An Azure Function – Execução simples e sem servidor para manipulação de notificação leve
• Uma Instância de Contêiner do Azure – Para notificações que exigem ambientes de tempo de execução específicos
• Um serviço Web personalizado – Para orquestração e processamento complexos
• Qualquer serviço de computação – contanto que ele possa expor um ponto de extremidade HTTP e manipular a notificação

Para obter informações detalhadas sobre como implementar e configurar pontos de extremidade remotos, consulte Habilitar pontos de extremidade remotos.

Configuração

Para habilitar notificações de ciclo de vida para seu item personalizado, configure as notificações no manifesto do item.

Definir notificações de ciclo de vida no manifesto do item

Adicione a configuração de notificação do ciclo de vida ao manifesto do item:

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

Configure apenas os eventos que você precisa manipular. Defina o valor como false ou omita o elemento se você não precisar de notificações para um tipo de evento específico.

Requisitos de ponto de extremidade

O ponto de extremidade do ciclo de vida deve:

• Ser publicamente acessível via HTTPS
• Responder dentro de um tempo limite razoável (recomendado: 30 segundos)
• Retornar códigos de status HTTP apropriados
• Gerenciar a autenticação usando o token fornecido

Para criar e atualizar operações que você deseja bloquear:

• Retornar código de status 4xx com detalhes de erro
• Incluir uma mensagem de erro amigável no corpo da resposta

Para operações bem-sucedidas ou para operações de exclusão e restauração:

• Retornar código de status 200 OK
• Opcionalmente, inclua informações de log ou de acompanhamento.

Suporte ao desenvolvimento local

Para desenvolvimento e teste local, o Kit de Ferramentas de Extensibilidade do Fabric fornece uma implementação interna de stub no servidor de desenvolvimento. Isso permite que você teste as notificações do ciclo de vida do item em seu computador local sem implantar no Azure.

Como funciona

Quando você executa o servidor de desenvolvimento local (consulte Introdução ao Fabric Extensibility Toolkit e Registrar Servidor Web Local), todas as notificações de ciclo de vida definidas no manifesto do item são redirecionadas automaticamente para seu computador local.

Quando um evento de ciclo de vida ocorre no modo de desenvolvimento:

1. A notificação é interceptada pelo servidor de desenvolvimento local
2. As mensagens de log aparecem no console local exibindo os detalhes do evento
3. Uma implementação de exemplo demonstra como interagir com a definição de item e o armazenamento do OneLake
4. Você recebe um token que pode ser usado para chamar qualquer operação de Fabric

Esta implementação provisória fornece:

• Feedback imediato – Veja as declarações de log em seu console à medida que ocorrem eventos de ciclo de vida
• Código de exemplo – Saiba como estruturar sua lógica de tratamento de notificação
• Exemplos de integração do OneLake – Veja como acessar o armazenamento do OneLake do item durante as notificações
• Token handling - Entenda como obter e usar tokens de autenticação Fabric
• Acesso à definição de item – Exibir o conteúdo completo da definição de item

Usando o Stub de Desenvolvimento

Para usar o servidor de desenvolvimento local para o teste de notificação do ciclo de vida:

1. Inicie o servidor de desenvolvimento local seguindo o guia de início rápido
2. Registrar seu servidor Web local usando as etapas de registro
3. Configurar notificações do ciclo de vida no manifesto do item, conforme descrito acima
4. Executar operações de item (criar, atualizar, excluir) no Fabric
5. Observe os detalhes da notificação no console local
6. Examine o código de exemplo para a interação do OneLake e o tratamento de tokens nos logs do servidor de desenvolvimento

Exemplo de interação do OneLake

O stub de desenvolvimento inclui um código de exemplo que mostra como interagir com o armazenamento OneLake associado ao item.

// 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}`);
}

Essa experiência de desenvolvimento local permite que você crie e teste sua lógica de notificação do ciclo de vida antes de implantar em pontos de extremidade de produção.

Exemplo de implementação

O exemplo a seguir usa Node.js e Express, com base na implementação de referência Fabric Extensibility Toolkit. Cada evento de ciclo de vida tem seu próprio endpoint que o Fabric chama com o corpo da solicitação apropriado. Para obter detalhes completos da API, consulte a referência da API REST do ciclo de vida do item.

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

Gestão de Infraestrutura

Provisione e desprovisione automaticamente a infraestrutura com base no ciclo de vida do item:

// 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);

Validação de licença e cota

Implemente requisitos de licenciamento e capacidade no onCreateItem manipulador:

// 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
  });
}

Sincronização externa do sistema

Mantenha os sistemas externos sincronizados com itens 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);

Excluir e restaurar estratégia

Implemente diferentes estratégias de limpeza com base deleteTypee manipule a restauração:

// 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);

Práticas recomendadas

Responder rapidamente

Os pontos de extremidade do ciclo de vida devem responder o mais rápido possível:

• Executar operações de validação e instalação rápida de forma síncrona
• Provisão de infraestrutura de execução prolongada para fila de processamento em segundo plano
• Retornar êxito/falha rapidamente para evitar tempos limite

Manipular a Idempotência

As operações de item podem ser repetidas, portanto, o endpoint deve ser idempotente.

• Verificar se a infraestrutura já existe antes de criar
• Usar identificadores exclusivos para acompanhar as operações
• Lidar com notificações duplicadas normalmente

Fornecer mensagens de erro claras

Ao bloquear operações, forneça mensagens de erro úteis:

// 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' });

Segurança

• Validar o token de autenticação em cada solicitação
• Use o token para verificar se a operação é legítima
• Não confie em IDs de item ou IDs de workspace sem validação
• Consulte Autenticar pontos de extremidade remotos para obter as melhores práticas de segurança

Monitoramento e registro em log

• Registrar todas as notificações de ciclo de vida recebidas
• Acompanhar o êxito/falha do provisionamento de infraestrutura
• Monitorar o desempenho e os erros do endpoint
• Usar os dados de notificação para trilhas de auditoria

Solução de problemas

Notificações Não Recebidas

• Verifique se a URL do ponto de extremidade está correta no manifesto
• Verifique se o ponto de extremidade está acessível publicamente
• Verifique se o HTTPS está configurado corretamente
• Verificar os logs do endpoint em busca de erros

Tempo limite de operações

• Otimizar o tempo de resposta do endpoint
• Mover operações de execução longa para tarefas em segundo plano
• Aumentar as configurações de tempo limite do ponto de extremidade, se necessário
• Examinar o desempenho do provisionamento de infraestrutura

O bloqueio não está funcionando

• Verifique se você está retornando códigos de status 4xx para operações bloqueadas
• Verifique se as mensagens de erro estão incluídas na resposta
• Verifique se o ponto de extremidade responde dentro da janela de tempo limite
• Lembre-se de que as operações de exclusão não podem ser bloqueadas – a plataforma Fabric marca o item como excluído, independentemente da resposta da carga de trabalho.

Conteúdo relacionado

• Autenticar pontos de extremidade remotos
• Habilitar pontos de extremidade remotos
• Definição de item de repositório
• Definir tarefas para sua carga de trabalho
• Comece com o Fabric Extensibility Toolkit
• Registrar Servidor Web Local
• Fabric API de Gerenciamento de Itens
• Visão geral Fabric CI/CD
• Referência da API REST do ciclo de vida do item