Aktiver varsler for varelivssyklus

Varsler om varelivssyklus gir arbeidsbelastningsbyggere mulighet til å motta varsler om livssyklushendelser for egendefinerte elementer, selv når arbeidsbelastningens UX ikke er med i loopen. Denne innstillingen gjør at gjenstanden din kan svare på gjenstandsoperasjoner uavhengig av hvordan de ble startet.

Oversikt

Varsler om varelivssyklus er essensielle i situasjoner der elementer opprettes, oppdateres eller slettes utenfor arbeidsbelastningens brukergrensesnitt. Denne tjenesten varsler arbeidsmengden din hver gang en livssyklushendelse inntreffer, slik at du kan:

• Sett opp eller riv ned infrastruktur for nye eller slettede gjenstander
• Valider lisenser eller kvoter før du tillater operasjoner
• Synkroniser tilstand med eksterne systemer
• Implementer tilpasset forretningslogikk for vareoperasjoner
• Håndter myk sletting-scenarier med egendefinert oppryddingslogikk

Når livssyklusvarsler utløses

Livssyklusvarsler utløses for vareoperasjoner som stammer fra flere kilder:

Offentlige API-er

Elementer kan opprettes, oppdateres eller slettes via Fabric sine offentlige REST-APIer uten noen interaksjon med arbeidsbelastningens brukergrensesnitt. Eksempel:

• Automatiseringsskript som bruker Items-API-et
• Tredjepartsapplikasjoner som integreres med Fabric
• Administrative operasjoner utført programmessig

CI/CD-rørledninger

Elementer distribueres gjennom Fabric sine CI/CD-funksjoner som en del av automatiserte distribusjonspipelines. I dette scenariet:

• Elementer opprettes eller oppdateres som en del av Git-integrasjonsarbeidsflyter
• Distribusjonspipelines fremmer elementer på tvers av miljøer
• Ingen interaksjon med brukergrensesnittet skjer under distribusjonsprosessen

Platform-Controlled UX-flyter

Selv innenfor Fabric-brukergrensesnittet kontrollerer plattformen visse opprettelses- og administrasjonsprosesser. Arbeidsmengden din mottar varsler for disse operasjonene for å opprettholde konsistens:

• Gjenstandsopprettelse gjennom plattformdialoger
• Operasjoner på arbeidsplassnivå som påvirker elementer
• Kopierings- eller flytteoperasjoner på tvers av arbeidsområder

Livssyklushendelser

Arbeidsmengden din kan motta varsler for følgende livssyklushendelser:

Opprett

Utløses når en ny gjenstand opprettes. Du kan gjøre følgende:

• Oppsett nødvendig infrastruktur (databaser, datakraftressurser)
• Valider lisenser eller kapasitetskvoter
• Initialiser objektspesifikke ressurser
• Blokker operasjonen hvis validering feiler eller forutsetninger ikke er oppfylt

Update

Utløses når en gjenstands definisjon eller egenskaper endres. Du kan gjøre følgende:

• Oppdater tilhørende infrastruktur
• Valider den nye konfigurasjonen
• Synkroniser endringer med eksterne systemer
• Blokker operasjonen hvis oppdateringen bryter forretningsreglene

Slett

Utløses når en gjenstand slettes. Forespørselen inkluderer et deleteType felt som indikerer om det er en hard eller myk sletting:

• Hard sletting: Permanent sletting – rydd opp i alle tilknyttede ressurser
• Myk sletting: Elementet er merket for sletting, men kan gjenopprettes senere – behold tilstrekkelig metadata og ressurser til å støtte gjenoppretting

Arbeidsmengden din kan velge ulike strategier for myk sletting:

• Stopp dyre beregningsressurser samtidig som dataene beholdes
• Arkiver kritiske data til rimeligere lagring
• Behold full tilstand i restitusjonsperioden

Gjenopprett

Utløses når et tidligere mykt slettet element gjenopprettes. Endepunktet ditt mottar elementdefinisjonen og skal:

• Omalloker ressurser som ble frigjort under myk sletting
• Gjenopprette gjenstandstilstand og gjenoppta tjenestene
• Reinitialiser beregnings- eller lagringsressurser etter behov

Forespørselsformat

Fabric kaller et separat endepunkt for hver livssyklushendelse. Hver forespørsel inkluderer:

URL-stiparametere

Elementets identifiserende informasjon oppgis i URL-stien:

• workspaceId - Arbeidsområdets ID (UUID)
• itemType - Elementtypen (for eksempel, Contoso.FinanceAnalytics.Forecast)
• itemId - Gjenstands-ID (UUID)

Autentiseringsheader

Headeren Authorization bruker skjemaet SubjectAndAppToken1.0 , som inneholder både et delegert brukertoken og et appen-only token:

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

Dette dual-token-formatet lar arbeidsmengden din validere forespørselens opprinnelse, verifisere brukerkontekst og kalle andre tjenester. Ekstra nødvendige overskrifter inkluderer ActivityId, RequestId, og x-ms-client-tenant-id.

For detaljer om validering av disse tokenene, se Autentiserer eksterne endepunkter.

Brødtekst for forespørsel

Forespørselsorganet varierer etter operasjon:

• Lag, oppdater og gjenopprette: Kroppen inneholder et ItemDefinition objekt med et parts array. Hver del har en path, payload (Base64-kodet), og payloadType.
• Slett: Kroppen inneholder et deleteType felt med verdien eller HardSoft.

Informasjonen i forespørselsdelen lar deg å:

• Trekk ut konfigurasjon for infrastrukturoppsett under opprett og gjenoppretting
• Forstå hva som har endret seg i oppdateringsoperasjonene
• Ta informerte beslutninger om blokkeringsoperasjoner
• Velg riktig oppryddingsstrategi for harde vs. myke slettinger

Blokkeringsoperasjoner

For opprettelses- og oppdateringsoperasjoner kan arbeidsmengden din blokkere operasjonen ved å returnere et feilsvar fra livssyklusendepunktet. Dette er nyttig for:

• Lisensvalidering: Forhindre opprettelse av gjenstander hvis brukeren ikke har nødvendige lisenser
• Kvotehåndhevelse: Blokkopprettelse hvis arbeidsområde- eller kapasitetsgrenser overskrides
• Konfigurasjonsvalidering: Avvis oppdateringer som ville skape ugyldige tilstander
• Sikkerhetspolicyer: Håndhev organisatoriske policyer på elementkonfigurasjoner

Når du blokkerer en operasjon:

1. Returner en feilstatuskode (for eksempel 400 eller 403) fra endepunktet ditt
2. Gi en klar feilmelding som forklarer hvorfor operasjonen ble blokkert
3. Plattformen viser feilmeldingen din til brukeren
4. Gjenstandsoperasjonen er ikke fullført

Implementering av håndtering av livssyklusvarsler

Livssyklusvarsler definert i egendefinerte varer kan ikke håndteres direkte i Fabric. I stedet må du implementere et eksternt endepunkt som Fabric kaller når en livssyklushendelse inntreffer. Dette gir deg full kontroll over hvor og hvordan varslingshåndteringslogikken din kjøres.

Det eksterne endepunktet kan være:

• An Azure Function - Enkel, serverløs kjøring for lett varslingshåndtering
• An Azure Container Instance - For varsler som krever spesifikke kjøremiljøer
• En skreddersydd webtjeneste – for kompleks orkestrering og prosessering
• Enhver beregningstjeneste – Så lenge den kan eksponere et HTTP-endepunkt og håndtere varslingen

For detaljert informasjon om implementering og konfigurasjon av eksterne endepunkter, se Aktiver eksterne endepunkter.

Konfigurasjon

For å aktivere livssyklusvarsler for ditt tilpassede element, konfigurer varslene i varemanifestet ditt.

Definer livssyklusvarsler i varemanifestet

Legg til konfigurasjonen for livssyklusvarsler i varemanifestet ditt:

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

Konfigurer kun de hendelsene du trenger å håndtere. Sett verdien til eller false utelat elementet hvis du ikke trenger varsler for en spesifikk hendelsestype.

Endepunktskrav

Ditt livssyklusendepunkt må:

• Vær offentlig tilgjengelig over HTTPS
• Svar innen en rimelig timeout (anbefalt: 30 sekunder)
• Returner passende HTTP-statuskoder
• Håndter autentisering ved hjelp av den oppgitte tokenen

For opprettelses- og oppdateringsoperasjoner du vil blokkere:

• Returner 4xx-statuskode med feildetaljer
• Inkluder en brukervennlig feilmelding i svardelen

For operasjoner som lykkes, eller for slettings- og gjenopprettingsoperasjoner:

• Returner 200 OK statuskode
• Eventuelt inkluder logg- eller sporingsinformasjon

Lokal utviklingsstøtte

For lokal utvikling og testing tilbyr Fabric Extensibility Toolkit en innebygd stub-implementering i utviklingsserveren. Dette lar deg teste varelivssyklusvarsler på din lokale maskin uten å måtte distribuere til Azure.

Slik fungerer det

Når du kjører den lokale utviklingsserveren (se Kom i gang med Fabric Extensibility Toolkit og Register Local Web Server), blir alle livssyklusvarsler definert i produktmanifestet automatisk omdirigert til din lokale maskin.

Når en livssyklushendelse skjer i utviklingsmodus:

1. Varslingen blir avlyttet av den lokale utviklingsserveren
2. Loggsetninger vises i din lokale konsoll som viser hendelsesdetaljene
3. En eksempelimplementering demonstrerer hvordan man kan samhandle med elementdefinisjonen og OneLake-lagring
4. Du mottar en token som kan brukes til å kalle hvilken som helst Fabric-operasjon

Denne stub-implementeringen gir:

• Umiddelbar tilbakemelding – Se loggsetninger i konsollen din når livssyklushendelser skjer
• Eksempelkode – Lær hvordan du strukturerer din varslingshåndteringslogikk
• Eksempler på OneLake-integrasjon – Se hvordan du får tilgang til enhetens OneLake-lagring under varsler
• Tokenhåndtering - Forstå hvordan du skaffer og bruker Fabric autentiseringstokene
• Tilgang til gjenstandsdefinisjon – Se den komplette gjenstandsdefinisjonsnyttelasten

Bruk av utviklingsstubben

For å bruke den lokale utviklingsserveren for testing av livssyklusvarsler:

1. Start din lokale utviklingsserver etter hurtigstartguiden
2. Registrer din lokale webserver ved å bruke registreringstrinnene
3. Konfigurer livssyklusvarsler i varemanifestet ditt som beskrevet ovenfor
4. Utfør gjenstandsoperasjoner (opprette, oppdater, slett) i Fabric
5. Følg med på varslingsdetaljene i din lokale konsoll
6. Se gjennom eksempelkoden for OneLake-interaksjon og tokenhåndtering i utviklingsserverloggene

Eksempel på OneLake-interaksjon

Utviklingsstubben inkluderer eksempelkode som viser hvordan man kan samhandle med enhetens OneLake-lagring:

// 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 utviklingserfaringen lar deg bygge og teste livssyklusvarslingslogikken før du distribuerer til produksjonsendepunkter.

Implementeringseksempel

Følgende eksempel bruker Node.js og Express, basert på referanseimplementasjonen Fabric Extensibility Toolkit. Hver livssyklushendelse har sitt eget endepunkt som Fabric kaller med den riktige forespørselskroppen. For fullstendige API-detaljer, se Item Lifecycle REST API-referansen.

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

Brukstilfeller

Infrastrukturforvaltning

Automatisk tilrettelegging og avvikling av infrastruktur basert på produktets livssyklus:

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

Validering av lisens og kvote

Håndhev lisens- og kapasitetskrav 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 synkronisert med Fabric-produkter:

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

Slette og gjenopprette strategi

Implementer ulike oppryddingsstrategier basert på deleteType, og håndter gjenoppretting:

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

Anbefalte fremgangsmåter

Svar raskt

Livssyklusendepunkter bør svare så raskt som mulig:

• Utfør validering og raske oppsettsoperasjoner synkront
• Kø langvarig infrastruktur for bakgrunnsprosessering
• Returner suksess/fiasko raskt for å unngå timeouts

Håndter idempotens

Gjenstandsoperasjoner kan prøves på nytt, så endepunktet ditt bør være idempotent:

• Sjekk om infrastruktur allerede eksisterer før du oppretter
• Bruk unike identifikatorer for å spore operasjoner
• Håndter duplikatvarsler på en elegant måte

Gi klare feilmeldinger

Når du blokkerer operasjoner, gi nyttige feilmeldinger:

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

Security

• Valider autentiseringstoken på hver forespørsel
• Bruk tokenet for å verifisere at operasjonen er legitim
• Ikke stol på gjenstands-IDer eller arbeidsområde-IDer uten validering
• Se Autentisert eksterne endepunkter for beste sikkerhetspraksis

Overvåking og logging

• Logg alle mottatte livssyklusvarsler
• Spor suksess/feil i infrastrukturforsyning
• Overvåk endepunktets ytelse og feil
• Bruk varslingsdataene for revisjonsspor

Feilsøking

Varsler ikke mottatt

• Sjekk at endepunkts-URL-en er korrekt i manifestet
• Sjekk at endepunktet er offentlig tilgjengelig
• Sørg for at HTTPS er riktig konfigurert
• Gå gjennom endepunktslogger for feil

Operasjoner som går ut av tid

• Optimaliser responstiden på endepunktet
• Flytt langvarige operasjoner til bakgrunnsjobber
• Øk endepunktets timeout-innstillinger om nødvendig
• Gjennomgå infrastrukturytelse

Blokkering fungerer ikke

• Sjekk at du returnerer 4xx-statuskoder for blokkerte operasjoner
• Sjekk at feilmeldinger er inkludert i svaret
• Sørg for at endepunktet svarer innenfor timeout-vinduet
• Husk at slettingsoperasjoner ikke kan blokkeres – Fabric-plattformen markerer elementet som slettet uansett hvordan arbeidsmengden din reagerer.

Relatert innhold

• Autentiser eksterne endepunkter
• Aktiver eksterne endepunkter
• Definisjon av butikkvare
• Definer jobber for arbeidsmengden din
• Kom i gang med Fabric Extensibility Toolkit
• Registrer lokal webserver
• Fabric Item Management API
• Fabric CI/CD-oversikt
• Item Lifecycle REST API-referanse