Aktiver notifikationer om varelivscyklus

Item lifecycle notifikationer giver workload builders mulighed for at modtage notifikationer om livscyklusbegivenheder for brugerdefinerede varer, selv når workload UX ikke er med i loopet. Denne indstilling gør det muligt for dit element at reagere på vareoperationer uanset, hvordan de blev startet.

Oversigt

Notifikationer om varelivscyklus er essentielle i situationer, hvor elementer oprettes, opdateres eller slettes uden for din arbejdsbelastnings brugergrænseflade. Denne tjeneste giver din arbejdsbyrde besked, når en varelivscyklusbegivenhed opstår, så du kan:

• Opsæt eller nedbryd infrastruktur for nye eller slettede elementer
• Valider licenser eller kvoter, før du tillader operationer
• Synkroniser tilstand med eksterne systemer
• Implementer brugerdefineret forretningslogik til vareoperationer
• Håndter bløde sletningsscenarier med brugerdefineret oprydningslogik

Når livscyklusnotifikationer udløses

Livscyklusnotifikationer udløses for vareoperationer, der stammer fra flere kilder:

Offentlige API'er

Elementer kan oprettes, opdateres eller slettes via Fabric's offentlige REST API'er uden nogen interaktion med din arbejdsbelastnings brugerflade. Eksempel:

• Automatiseringsscripts ved brug af Items API
• Tredjepartsapplikationer, der integreres med Fabric
• Administrative operationer udført programmæssigt

CI/CD-pipelines

Elementer implementeres gennem Fabric's CI/CD-funktioner som en del af automatiserede deploymentspipelines. I dette scenarie:

• Elementer oprettes eller opdateres som en del af Git-integrationsworkflows
• Implementeringspipelines fremmer elementer på tværs af miljøer
• Der forekommer ingen brugergrænsefladeinteraktion under udrulningsprocessen

Platform-Controlled UX-flowet

Selv inden for Fabric-brugergrænsefladen styrer platformen visse oprettelses- og administrationsflows. Din arbejdsbyrde modtager notifikationer for disse operationer for at opretholde konsistens:

• Oprettelse af genstande via platformdialoger
• Arbejdsområde-niveau operationer, der påvirker elementer
• Cross-workspace kopierings- eller flytningsoperationer

Livscyklusbegivenheder

Din arbejdsbyrde kan modtage notifikationer for følgende livscyklusbegivenheder:

Opret

Udløses, når et nyt element oprettes. Du kan:

• Opsætning af nødvendig infrastruktur (databaser, beregningsressourcer)
• Valider licenser eller kapacitetskvoter
• Initialiser objektspecifikke ressourcer
• Blokér operationen , hvis valideringen fejler eller forudsætningerne ikke opfyldes.

Update

Udløses, når en genstands definition eller egenskaber ændres. Du kan:

• Opdater tilhørende infrastruktur
• Valider den nye konfiguration
• Synkroniser ændringer med eksterne systemer
• Blokér operationen , hvis opdateringen overtræder forretningsreglerne

Slette

Udløses, når en genstand slettes. Anmodningen indeholder et deleteType felt, der angiver, om det er en hård eller blød sletning:

• Hård sletning: Permanent sletning - ryd op i alle tilknyttede ressourcer
• Blød sletning: Elementet er markeret til sletning, men kan gendannes senere – behold tilstrækkelig metadata og ressourcer til at understøtte gendannelse

Din arbejdsbyrde kan vælge forskellige strategier for soft delete:

• Stop dyre beregningsressourcer, mens du bevarer data
• Arkivér kritiske data til lavere omkostningslagring
• Bevar fuld tilstand i restitutionsperioden

Genopret

Udløses, når et tidligere blødt slettet element gendannes. Dit endpoint modtager item-definitionen og bør:

• Omalloker ressourcer, der blev frigjort under soft delete
• Genopret genskabstilstand og genoptag tjenester
• Geninitialiser compute- eller lagringsressourcer efter behov

Anmodningsformat

Fabric kalder et separat endepunkt for hver livscyklusbegivenhed. Hver anmodning inkluderer:

URL-stiparametre

Elementets identificerende oplysninger gives i URL-stien:

• workspaceId - Arbejdsområde-ID (UUID)
• itemType - Elementtypen (for eksempel, Contoso.FinanceAnalytics.Forecast)
• itemId - Item ID (UUID)

Autentificeringsheader

Headeren Authorization bruger skemaet SubjectAndAppToken1.0 , som indeholder både et delegeret brugertoken og et kun app-token:

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

Dette dual-token-format gør det muligt for din arbejdsbyrde at validere anmodningens oprindelse, verificere brugerkontekst og kalde andre tjenester. Ekstra nødvendige overskrifter inkluderer ActivityId, RequestId, og x-ms-client-tenant-id.

For detaljer om validering af disse tokens, se Autentificér fjernterminaler.

Brødtekst for anmodning

Anmodningsorganet varierer efter operation:

• Opret, Opdater og Gendann: Kroppen indeholder et ItemDefinition objekt med et parts array. Hver del har en path, payload (Base64-kodet), og payloadType.
• Slet: Kroppen indeholder et deleteType felt med værdien eller HardSoft.

Oplysningerne i anmodningsdelen giver dig mulighed for at:

• Udtræk konfiguration til infrastrukturopsætning under oprettelse og gendannelse
• Forstå, hvad der ændrede sig i opdateringsoperationerne
• Tag informerede beslutninger om blokeringsoperationer
• Vælg den passende oprydningsstrategi for hårde vs. bløde sletninger

Blokeringsoperationer

For oprettelse og opdatering kan din arbejdsbyrde blokere operationen ved at returnere et fejlsvar fra livscyklus-endpointet. Dette er nyttigt til:

• Licensvalidering: Forhindre oprettelse af genstande, hvis brugeren ikke har de nødvendige licenser
• Kvotehåndhævelse: Blokoprettelse, hvis arbejdsområde- eller kapacitetsgrænser overskrides
• Konfigurationsvalidering: Afvis opdateringer, der ville skabe ugyldige tilstande
• Sikkerhedspolitikker: Håndhæv organisatoriske politikker på varekonfigurationer

Når du blokerer en operation:

1. Returner en fejlstatuskode (for eksempel 400 eller 403) fra dit endpoint
2. Giv en klar fejlmeddelelse, der forklarer, hvorfor operationen blev blokeret
3. Platformen viser din fejlmeddelelse til brugeren
4. Item-operationen er ikke fuldført

Implementering af Lifecycle Notification Handling

Livscyklusnotifikationer defineret i brugerdefinerede varer kan ikke håndteres direkte i Fabric. I stedet skal du implementere et fjernt endpoint, som Fabric kalder, når en livscyklusbegivenhed opstår. Dette giver dig fuld kontrol over, hvor og hvordan din notifikationshåndteringslogik udføres.

Det fjern endepunkt kan være:

• An Azure Function - Simpel, serverløs udførelse til letvægts notifikationshåndtering
• An Azure Container Instance - Til notifikationer, der kræver specifikke runtime-miljøer
• En skræddersyet webservice - Til kompleks orkestrering og behandling
• Enhver compute-tjeneste - Så længe den kan eksponere et HTTP-endpoint og håndtere notifikationen

For detaljeret information om implementering og konfiguration af fjernendepunkter, se Aktiver fjernendepunkter.

Konfiguration

For at aktivere livscyklusnotifikationer for din brugerdefinerede vare, skal du konfigurere notifikationerne i dit produktmanifest.

Definér livscyklusnotifikationer i Item Manifest

Tilføj konfigurationen af livscyklusnotifikationer til dit varemanifest:

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

Konfigurer kun de begivenheder, du skal håndtere. Sæt værdien til eller false udelad elementet, hvis du ikke har brug for notifikationer for en bestemt begivenhedstype.

Endpoint-krav

Dit livscyklus-endpoint skal:

• Vær offentligt tilgængelig over HTTPS
• Svar inden for en rimelig timeout (anbefalet: 30 sekunder)
• Returner passende HTTP-statuskoder
• Håndter autentificering ved hjælp af den medfølgende token

For oprettelse og opdatering af operationer, du ønsker at blokere:

• Returner 4xx-statuskode med fejloplysninger
• Inkluder en brugervenlig fejlmeddelelse i svarets brødtekst

For operationer, der lykkes, eller for slet- og gendannelsesoperationer:

• Return 200 OK statuskode
• Inkluder eventuelt log- eller sporingsinformation

Lokal udviklingsstøtte

Til lokal udvikling og test tilbyder Fabric Extensibility Toolkit en indbygget stub-implementering i udviklingsserveren. Dette gør det muligt at teste notifikationer om produktlivscyklus på din lokale maskine uden at udrulle til Azure.

Sådan fungerer det

Når du kører den lokale udviklingsserver (se Kom i gang med Fabric Extensibility Toolkit og Register Local Web Server), bliver alle livscyklusnotifikationer defineret i dit item manifest automatisk omdirigeret til din lokale maskine.

Når en livscyklusbegivenhed opstår i udviklingstilstand:

1. Notifikationen opsnappes af den lokale udviklingsserver
2. Logudsagn vises i din lokale konsol med hændelsesdetaljerne
3. En eksempelimplementering demonstrerer, hvordan man interagerer med itemdefinitionen og OneLake-lagringen
4. Du modtager et token, der kan bruges til at kalde enhver Fabric-operation

Denne stub-implementering giver:

• Øjeblikkelig feedback – Se logudsagn i din konsol, når livscyklusbegivenheder opstår
• Eksempelkode - Lær hvordan du strukturerer din notifikationshåndteringslogik
• Eksempler på OneLake-integration - Se, hvordan du får adgang til enhedens OneLake-lager under notifikationer
• Tokenhåndtering - Forstå, hvordan man henter og bruger Fabric autentificeringstokens
• Adgang til genstandsdefinition - Se den komplette genstandsdefinitionspayload

Brug af udviklingsstubben

Til brug af den lokale udviklingsserver til test af livscyklusnotifikationer:

1. Start din lokale udviklingsserver ved at følge quickstart-guiden
2. Registrer din lokale webserver ved hjælp af registreringstrinnene
3. Konfigurer livscyklusnotifikationer i dit varemanifest som beskrevet ovenfor
4. Udfør itemoperationer (oprette, opdatere, slette) i Fabric
5. Følg notifikationsdetaljerne i din lokale konsol
6. Gennemgå eksempelkoden for OneLake-interaktion og tokenhåndtering i udviklingsserverloggene

OneLake interaktionseksempel

Udviklingsstubben indeholder eksempelkode, der viser, hvordan man interagerer med produktets OneLake-lager:

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

Denne lokale udviklingserfaring gør det muligt for dig at opbygge og teste din livscyklus-notifikationslogik, før du deployerer til produktionsendepunkter.

Implementeringseksempel

Følgende eksempel bruger Node.js og Express, baseret på referenceimplementeringen Fabric Extensibility Toolkit. Hver livscyklusbegivenhed har sit eget endepunkt, som Fabric kalder med den relevante anmodningskrop. For fulde API-detaljer, se referencen til Item Lifecycle REST API.

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({});
  }
);

Anvendelsestilfælde

Infrastrukturstyring

Automatisk provisionering og afprovisionering af infrastruktur baseret på produktets livscyklus:

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

Licens- og kvotevalidering

Håndhæv licens- og kapacitetskrav hos håndtereren onCreateItem :

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

Ekstern systemsynkronisering

Hold eksterne systemer synkroniserede med Fabric-elementer:

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

Slet- og gendannelsesstrategi

Implementér forskellige oprydningsstrategier baseret på deleteType, og håndter genoprettelse:

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

Bedste praksis

Svar hurtigt

Livscyklusendepunkter bør reagere så hurtigt som muligt:

• Udfør validering og hurtige opsætningsoperationer synkront
• Kø langvarig infrastrukturprovisionering til baggrundsbehandling
• Returner succes/fiasko hurtigt for at undgå timeouts

Håndter Idempotens

Itemoperationer kan prøves igen, så dit endpoint bør være idempotent:

• Tjek om der allerede findes infrastruktur, før du opretter
• Brug unikke identifikatorer til at spore operationer
• Håndter dubletnotifikationer elegant

Giv klare fejlmeddelelser

Når du blokerer operationer, giv nyttige fejlmeddelelser:

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

Sikkerhed

• Valider autentificeringstokenet på hver anmodning
• Brug tokenet til at verificere, at operationen er legitim
• Stol ikke på item-ID'er eller workspace-ID'er uden validering
• Se Autentificér fjernendepunkter for sikkerhedsbedste praksis

Overvågning og logning

• Log alle modtagne livscyklusnotifikationer
• Følg succes/fejl i infrastrukturprovisionering
• Overvåg endepunktets ydeevne og fejl
• Brug notifikationsdataene til revisionsspor

Fejlfinding

Notifikationer ikke modtaget

• Kontroller at endpoint-URL'en er korrekt i manifestet
• Tjek at endpointet er offentligt tilgængeligt
• Sørg for, at HTTPS er korrekt konfigureret
• Gennemgå endpoint-logs for fejl

Operationer Timeout

• Optimer endpointets responstid
• Flyt langvarige operationer til baggrundsjobs
• Øg endpoint-timeout-indstillingerne om nødvendigt
• Gennemgå infrastrukturens provisioneringspræstation

Blokering virker ikke

• Tjek at du returnerer 4xx-statuskoder for blokerede operationer
• Tjek, at fejlmeddelelser er inkluderet i svaret
• Sørg for, at endpointet svarer inden for timeout-vinduet
• Husk, at sletningsoperationer ikke kan blokeres – Fabric-platformen markerer elementet som slettet uanset din arbejdsbelastnings respons.

Relateret indhold

• Autentificér fjernendepunkter
• Aktivér fjernterminaler
• Definition af butiksvare
• Definér job til din arbejdsbyrde
• Kom i gang med Fabric Extensibility Toolkit
• Registrer lokal webserver
• Fabric Item Management API
• Fabric CI/CD Oversigt
• Item Lifecycle REST API-reference