Ativar Notificações do Ciclo de Vida dos Itens

As notificações do ciclo de vida dos itens fornecem aos criadores de carga de trabalho a capacidade de receber notificações sobre eventos do ciclo de vida para itens personalizados, mesmo quando a experiência de utilizador da carga de trabalho não está presente. Esta configuração permite que o seu item responda às operações do item independentemente da forma como foram iniciadas.

Descrição geral

As notificações do ciclo de vida dos itens são essenciais para cenários em que os itens são criados, atualizados ou eliminados fora da interface da sua carga de trabalho. Este serviço notifica a sua carga de trabalho sempre que ocorre um evento no ciclo de vida do item, permitindo-lhe:

• Configurar ou desmontar infraestrutura para itens novos ou eliminados
• Validar licenças ou quotas antes de permitir operações
• Sincronizar o estado com sistemas externos
• Implementar lógica de negócio personalizada para operações de itens
• Lidar com cenários de eliminação suave com lógica de limpeza personalizada

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

Notificações do ciclo de vida são acionadas para operações de itens que têm origem em múltiplas fontes:

APIs públicas

Os itens podem ser criados, atualizados ou eliminados através das APIs REST públicas da Fabric sem qualquer interação com a interface da sua carga de trabalho. Por exemplo:

• Scripts de automação usando a API Itens
• Aplicações de terceiros que se integram com o Fabric
• Operações administrativas realizadas programaticamente

CI/CD Pipelines

Os itens são implementados através das capacidades CI/CD do Fabric como parte de pipelines automatizados de implementação. Neste cenário:

• Os itens são criados ou atualizados como parte dos fluxos de trabalho de integração do Git
• Os pipelines de implementação promovem itens entre ambientes
• Não ocorre qualquer interação com a interface do utilizador durante o processo de implementação

Fluxos de UX controlados pela plataforma

Mesmo dentro da interface de utilizador do Fabric, a plataforma controla certos fluxos de criação e gestão. A sua carga de trabalho recebe notificações para estas operações para manter a consistência:

• Criação de itens através de diálogos de plataforma
• Operações ao nível do espaço de trabalho que afetam itens
• Operações de cópia ou transferência entre espaços de trabalho

Eventos do Ciclo de Vida

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

Criar

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

• Configurar a infraestrutura necessária (bases de dados, recursos de computação)
• Validar licenças ou quotas de capacidade
• Inicializar recursos específicos de itens
• Bloqueie a operação se a validação falhar ou se os pré-requisitos não forem cumpridos

Atualização

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

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

Delete

Ativado quando um item é eliminado. O pedido inclui um campo deleteType que indica se é uma hard delete ou soft delete:

• Eliminação completa: Eliminação permanente - limpar todos os recursos associados
• Eliminação suave: O item está marcado para eliminação, mas pode ser restaurado mais tarde – manter metadados e recursos suficientes para suportar a restauração

A sua carga de trabalho pode escolher diferentes estratégias para eliminação suave:

• Interromper recursos de computação dispendiosos enquanto mantém os dados
• Arquivar dados críticos para armazenamento de menor custo
• Manter o estado total durante o período de recuperação

Restore

É ativado quando um item previamente apagado suavemente é restaurado. O seu endpoint recebe a definição do item e deve:

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

Formato do Pedido

O Fabric chama um endpoint separado para cada evento do ciclo de vida. Cada pedido inclui:

Parâmetros do Caminho URL

A informação identificativa do item é fornecida no caminho da URL:

• workspaceId - O ID do espaço de trabalho (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 utiliza o SubjectAndAppToken1.0 esquema, que contém tanto um token de utilizador delegado como um token exclusivo da aplicação:

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

Este formato de token duplo permite que a sua carga de trabalho valide a origem do pedido, verifique o contexto do utilizador e chame outros serviços. Cabeçalhos extra necessários incluem ActivityId, RequestId, e x-ms-client-tenant-id.

Para detalhes sobre a validação destes tokens, consulte Autenticação de Endpoints Remotos.

Órgão do Pedido

O corpo do pedido varia por operação:

• Criar, Atualizar e Restaurar: O corpo contém um ItemDefinition objeto com uma parts matriz. Cada parte tem um path, um payload (codificação Base64) e um payloadType.
• Eliminar: O corpo contém um deleteType campo com valor de Hard ou Soft.

A informação no corpo do pedido permite-lhe:

• Extrair configuração para a instalação da infraestrutura durante a criação e restauração
• Compreender o que mudou nas operações de atualização
• Tome decisões informadas sobre bloqueio de operações
• Escolha a estratégia de limpeza adequada para eliminações "hard" ou "soft"

Operações de Bloqueio

Para operações de criar e atualizar, a carga de trabalho pode bloquear a operação devolvendo uma resposta de erro do endpoint do ciclo de vida. Isto é útil para:

• Validação de licenças: Impedir a criação de itens se o utilizador não tiver licenças obrigatórias
• Fiscalização de quotas: Criação de blocos se forem ultrapassados os limites de espaço de trabalho ou capacidade
• Validação de configuração: Rejeitar atualizações que criariam estados inválidos
• Políticas de segurança: Aplicar políticas organizacionais sobre configurações de itens

Quando bloqueia uma operação:

1. Devolva um código de estado de erro (por exemplo, 400 ou 403) do seu endpoint
2. Fornecer uma mensagem de erro clara explicando porque é que a operação foi bloqueada
3. A plataforma mostra a sua mensagem de erro ao utilizador
4. A operação do item não está concluída

Implementação do Tratamento de Notificações de Ciclo de Vida

As notificações do ciclo de vida definidas em itens personalizados não podem ser geridas diretamente no Fabric. Em vez disso, precisa de implementar um endpoint remoto que o Fabric chame quando ocorre um evento do ciclo de vida. Isto dá-lhe controlo total sobre onde e como a lógica de gestão de notificações é executada.

O endpoint remoto pode ser:

• An Azure Function - Execução simples e serverless para um tratamento leve de notificações
• An Azure Container Instance - Para notificações que requerem ambientes de execução específicos
• Um serviço web personalizado - Para orquestração e processamento complexos
• Qualquer serviço de computação - Desde que consiga expor um endpoint HTTP e tratar da notificação

Para informações detalhadas sobre a implementação e configuração de endpoints remotos, consulte Habilitar Remote Endpoints.

Configuração

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

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

Adicione a configuração da notificação do ciclo de vida ao seu manifesto de artigos:

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

Configura apenas os eventos que precisas de gerir. Define o valor para false ou omite o elemento se não precisares de notificações para um tipo específico de evento.

Requisitos do Endpoint

O seu endpoint do ciclo de vida deve:

• Seja acessível publicamente via HTTPS
• Responder dentro de um tempo de espera razoável (recomendado: 30 segundos)
• Devolver os códigos de estado HTTP apropriados
• Tratar da autenticação usando o token fornecido

Para criar e atualizar operações que pretende bloquear:

• Devolver o código de estado 4xx com detalhes de erro
• Inclua uma mensagem de erro fácil de usar no corpo da resposta

Para operações que tenham sucesso, ou para operações de eliminação e restauro:

• Devolver código de estado 200 OK
• Opcionalmente, inclua informações de registo ou rastreio

Apoio ao Desenvolvimento Local

Para desenvolvimento e testes locais, o Fabric Extensibility Toolkit fornece uma implementação stub incorporada no servidor de desenvolvimento. Isto permite-lhe testar as notificações do ciclo de vida dos itens na sua máquina local sem ter de ser implementado no Azure.

Como funciona

Quando executa o servidor de desenvolvimento local (veja Comece com Fabric Extensibility Toolkit e Register Local Web Server), todas as notificações do ciclo de vida definidas no seu manifesto de itens são automaticamente redirecionadas para a sua máquina local.

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

1. A notificação é interceptada pelo servidor de desenvolvimento local
2. Os logs aparecem na sua consola local, mostrando os detalhes do evento.
3. Uma implementação de exemplo demonstra como interagir com a definição do item e o armazenamento do OneLake
4. Recebes um token que pode ser usado para chamar qualquer operação Fabric

Esta implementação de stub fornece:

• Feedback imediato - Veja os registos de log na sua consola à medida que ocorrem eventos de ciclo de vida
• Código de exemplo - Aprenda a estruturar a lógica de gestão das notificações
• Exemplos de integração OneLake - Veja como aceder ao armazenamento OneLake do item durante as notificações
• Token handling - Compreender como obter e usar tokens de autenticação Fabric
• Acesso à definição de itens - Visualize a carga útil completa de definição de itens

Utilização do Esboço de Desenvolvimento

Para usar o servidor de desenvolvimento local para testes de notificações ao longo do ciclo de vida:

1. Inicie o seu servidor de desenvolvimento local seguindo o guia de início rápido
2. Registe o seu servidor web local usando os passos de registo
3. Configure as notificações do ciclo de vida no seu manifesto de itens conforme descrito acima
4. Realizar operações de item (criar, atualizar, eliminar) no Fabric
5. Observe os detalhes das notificações na sua consola local
6. Revise o código de exemplo para interação OneLake e tratamento de tokens nos registos do servidor de desenvolvimento

Exemplo de Interação OneLake

O esboço de desenvolvimento inclui código de exemplo que mostra como interagir com o armazenamento OneLake do 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}`);
}

Esta experiência de desenvolvimento local permite-lhe construir e testar a lógica de notificações do seu ciclo de vida antes de a implementar em endpoints de produção.

Exemplo de Implementação

O exemplo seguinte utiliza Node.js e Express, baseados na implementação de referência Fabric Extensibility Toolkit. Cada evento do ciclo de vida tem o seu próprio endpoint que o Fabric chama com o corpo de pedido apropriado. Para 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 Infraestruturas

Fornecer e desprovisionar 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ças e Quotas

Aplicar os requisitos de licenciamento e capacidade no onCreateItem handler:

// 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 de Sistemas Externos

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

Estratégia de Eliminar e Restaurar

Implementar diferentes estratégias de limpeza baseadas em deleteType, e gerir 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);

Melhores práticas

Responda rapidamente

Os endpoints do ciclo de vida devem responder o mais rapidamente possível:

• Realizar validação e operações de configuração rápida de forma síncrona
• Enfileirar provisionamento prolongado de infraestrutura para processamento em segundo plano
• Devolve o sucesso/fracasso rapidamente para evitar tempos de espera

Idempotência do controlo

As operações de item podem ser tentadas novamente, por isso o teu endpoint deve ser idempotente:

• Verifique se a infraestrutura já existe antes de criar
• Utilize identificadores únicos para acompanhar operações
• Lide com notificações duplicadas com graça

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

• Valide o token de autenticação em cada pedido
• Use o token para verificar se a operação é legítima
• Não confie em IDs de itens ou IDs de espaço de trabalho sem validação
• Consulte a secção Autenticação de Endpoints Remotos para as melhores práticas de segurança

Monitorização e Registos

• Registar todas as notificações do ciclo de vida recebidas
• Acompanhar o sucesso/falha do provisionamento de infraestruturas
• Monitorizar o desempenho e os erros dos endpoints
• Use os dados de notificação para registos de auditoria

Troubleshooting

Notificações Não Recebidas

• Verifique se a URL do endpoint está correta no manifesto
• Verifique se o endpoint é acessível publicamente
• Garantir que o HTTPS está devidamente configurado
• Consultar os registos de endpoint em busca de erros

Tempo de Esgotamento das Operações

• Otimizar o tempo de resposta dos endpoints
• Transferir operações de longa duração para trabalhos em segundo plano
• Aumentar as configurações de timeout do endpoint, se for necessário
• Rever o desempenho do provisionamento de infraestruturas

Bloqueio Não Funciona

• Verifica se estás a devolver códigos de estado 4xx para operações bloqueadas
• Verifique se as mensagens de erro estão incluídas na resposta
• Garanta que o endpoint responde dentro da janela de timeout
• Lembra-te que as operações de eliminação não podem ser bloqueadas – a plataforma Fabric marca o item como eliminado independentemente da resposta da tua carga de trabalho.

Conteúdo relacionado

• Autenticar Endpoints Remotos
• Ativar Endpoints Remotos
• Definição de Item da Loja
• Defina Trabalhos para a Sua Carga de Trabalho
• Inicie com o Toolkit de Extensibilidade do Fabric
• Registo do Servidor Web Local
• Fabric API de Gestão de Itens
• Visão Geral do CI/CD do Fabric
• Referência da API REST do ciclo de vida do item