Ota käyttöön tuotteen elinkaaren ilmoitukset

Esineiden elinkaaren ilmoitukset antavat työkuorman rakentajille mahdollisuuden vastaanottaa ilmoituksia elinkaaren tapahtumista mukautetuille kohteille, vaikka työkuorman käyttökokemus ei olisi silmukassa. Tämä asetus mahdollistaa esineen reagoimisen esineoperaatioihin riippumatta siitä, miten ne on käynnistetty.

Yleiskuvaus

Esineiden elinkaaren ilmoitukset ovat välttämättömiä tilanteissa, joissa kohteita luodaan, päivitetään tai poistetaan työkuorman käyttöliittymän ulkopuolelta. Tämä palvelu ilmoittaa työkuormastasi aina, kun esineen elinkaaren tapahtuma tapahtuu, jolloin voit:

• Perusta tai purkaa infrastruktuuri uusille tai poistetuille kohteille
• Vahvista luvat tai kiintiöt ennen toiminnan sallimista
• Synkronoi tila ulkoisten järjestelmien kanssa
• Toteuta räätälöity liiketoimintalogiikka tehtäväoperaatioihin
• Käsittele pehmeän poiston skenaariot omalla puhdistuslogiikalla

Kun elinkaaren ilmoitukset laukeavat

Elinkaaren ilmoitukset laukaistaan tehtäväoperaatioille, jotka lähtevät useista lähteistä:

Julkiset ohjelmointirajapinnat

Kohteita voi luoda, päivittää tai poistaa Fabric:n julkisten REST-APIen kautta ilman vuorovaikutusta työkuorman käyttöliittymän kanssa. Esimerkki:

• Automaatioskriptit Items API:n avulla
• Kolmannen osapuolen sovellukset, jotka integroituvat Fabric-ohjelmistoon
• Hallinnolliset toiminnot suoritetaan ohjelmallisesti

CI/CD-putket

Kohteet otetaan käyttöön Fabric:n CI/CD-ominaisuuksien kautta osana automatisoituja käyttöönottoputkia. Tässä tilanteessa:

• Kohteet luodaan tai päivitetään osana Git-integraatiotyönkulkuja
• Käyttöönottoputket edistävät kohteita eri ympäristöissä
• Käyttöliittymän vuorovaikutusta ei tapahdu käyttöönottoprosessin aikana

Platform-Controlled UX-virrat

Jopa Fabric-käyttöliittymässä alusta ohjaa tiettyjä luonti- ja hallintaprosesseja. Työkuormasi vastaanottaa ilmoituksia näistä operaatioista johdonmukaisuuden ylläpitämiseksi:

• Kohteiden luominen alustan dialogien kautta
• Työtilatason toiminnot, jotka vaikuttavat kohteisiin
• Työtilan väliset kopiointi- tai siirtotoiminnot

Elinkaaren tapahtumat

Työkuormasi voi saada ilmoituksia seuraavista elinkaaren tapahtumista:

Luo

Aktivoituu, kun uusi esine luodaan. Voit tehdä seuraavia toimintoja:

• Perusta tarvittava infrastruktuuri (tietokannat, laskentaresurssit)
• Vahvista luvat tai kapasiteettikiintiöt
• Alustoi kohdekohtaiset resurssit
• Estä operaatio , jos validointi epäonnistuu tai ennakkovaatimuksia ei täytetä

Update

Aktivoituu, kun tuotteen määritelmää tai ominaisuuksia muutetaan. Voit tehdä seuraavia toimintoja:

• Päivitä siihen liittyvä infrastruktuuri
• Validoi uusi kokoonpano
• Synkronoi muutokset ulkoisten järjestelmien kanssa
• Estä operaatio , jos päivitys rikkoo liiketoimintasääntöjä

Poista

Aktivoituu, kun esine poistetaan. Pyyntö sisältää kentän deleteType , joka kertoo, onko poisto kovaa vai pehmeää poistoa:

• Kovapoisto: Pysyvä poisto – siivoa kaikki siihen liittyvät resurssit
• Pehmeä poisto: Kohde on merkitty poistettavaksi, mutta voidaan palauttaa myöhemmin – säilyttää riittävästi metatietoja ja resursseja palautuksen tukemiseksi

Työkuormasi voi valita erilaisia pehmeitä poistostrategioita:

• Pysäytä kalliit laskentaresurssit samalla kun pidät dataa
• Arkistoi kriittinen data edullisempaan tallennukseen
• Säilytä täysi tila toipumisajan ajan

Palauta

Aktivoituu, kun aiemmin pehmeästi poistettu kohde palautetaan. Päätepisteesi vastaanottaa kohteen määritelmän ja sen pitäisi:

• Varaa uudelleen resursseja, jotka vapautettiin pehmeän poiston aikana
• Palauta tuotteen tila ja jatka palveluita
• Uudelleenalustoi laskenta- tai tallennusresursseja tarpeen mukaan

Pyyntömuoto

Fabric kutsuu erillisen päätepisteen jokaiselle elinkaaren tapahtumalle. Jokainen pyyntö sisältää:

URL-polkuparametrit

Kohteen tunnistetiedot löytyvät URL-polusta:

• workspaceId - Työtilan ID (UUID)
• itemType - Tuotetyyppi (esimerkiksi, Contoso.FinanceAnalytics.Forecast)
• itemId - Tuotetunnus (UUID)

Tunnistautumisen otsikko

Otsikko Authorization käyttää järjestelmää SubjectAndAppToken1.0 , joka sisältää sekä delegoidun käyttäjätunnuksen että vain sovellukselle tarkoitetun tokenin:

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

Tämä kaksoistoken-muoto mahdollistaa työkuormasi pyynnön alkuperän validoinnin, käyttäjäkontekstin varmistamisen ja muiden palveluiden kutsumisen. Ylimääräisiä vaadittuja otsikoita ovat ActivityId, RequestId, ja x-ms-client-tenant-id.

Lisätietoja näiden tokenien validoinnista löytyy kohdasta Authenticate Remote Endpoints.

Pyynnön leipäteksti

Pyyntöjen runko vaihtelee toiminnon mukaan:

• Luo, päivitä ja palauta: Runko sisältää ItemDefinition objektin, jolla on taulukko parts . Jokaisella osalla on path, payload (Base64-koodattu) ja payloadType.
• Poista: Kappale sisältää kentän deleteType , jonka arvo on Hard tai Soft.

Pyyntörungon tiedot mahdollistavat:

• Poima konfiguraatio infrastruktuurin perustamista varten luomisen ja palautuksen aikana
• Ymmärrä, mitä päivitystoiminnoissa muuttui
• Tee perusteltuja päätöksiä estotoiminnoista
• Valitse oikea puhdistusstrategia koville ja pehmeille poistoille

Estotoimet

Luonti- ja päivitystoiminnoissa työkuormasi voi estää toiminnon palauttamalla virhevastauksen elinkaaren päätepisteestä. Tästä on hyötyä seuraavissa tilanteissa:

• Lisenssin validointi: Estä kohteiden luominen, jos käyttäjällä ei ole vaadittuja lisenssejä
• Kiintiön valvonta: Lohkojen luominen, jos työtila- tai kapasiteettirajat ylitetään
• Konfiguraation validointi: Hylkää päivitykset, jotka aiheuttaisivat virheellisiä tiloja
• Turvallisuuskäytännöt: Pakota organisaation käytännöt kohteen konfiguraatioissa

Kun estät operaation:

1. Palauta virhetilakoodi (esimerkiksi 400 tai 403) päätepisteestäsi
2. Anna selkeä virheilmoitus, jossa selität, miksi operaatio estettiin
3. Alusta näyttää käyttäjälle virheilmoituksesi
4. Esineoperaatio ei ole valmis

Elinkaaren ilmoitusten käsittelyn toteuttaminen

Mukautetuissa kohteissa määriteltyjä elinkaaren ilmoituksia ei voi käsitellä suoraan Fabric-järjestelmässä. Sen sijaan sinun täytyy toteuttaa etäpäätepiste, jonka Fabric kutsuu, kun elinkaaren tapahtuma tapahtuu. Tämä antaa sinulle täyden hallinnan siitä, missä ja miten ilmoitusten käsittelylogiikka suoritetaan.

Etäpäätepiste voi olla:

• An Azure Function - Yksinkertainen, palvelinvapaa suoritus kevyeseen ilmoituskäsittelyyn
• An Azure Container Instance - Ilmoituksiin, jotka vaativat tiettyjä ajonaikaisia ympäristöjä
• Räätälöity verkkopalvelu – Monimutkaiseen orkestrointiin ja käsittelyyn
• Mikä tahansa laskentapalvelu – kunhan se pystyy paljastamaan HTTP-päätepisteen ja käsittelemään ilmoituksen

Yksityiskohtaista tietoa etäpäätelaitteiden toteutuksesta ja konfiguroinnista löytyy kohdasta Remote Endpoints Enable Remote Endpoints.

Määritykset

Ottaaksesi käyttöön elinkaaren ilmoitukset mukautetulle tuotteellesi määrittämällä ilmoitukset tuoteluettelossasi.

Määrittele elinkaaren ilmoitukset Item Manifestissa

Lisää elinkaaren ilmoitusasetus esineluetteloosi:

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

Määritä vain ne tapahtumat, jotka sinun täytyy käsitellä. Aseta arvoksi false tai jätä elementti pois, jos et tarvitse ilmoituksia tietylle tapahtumatyypille.

Päätepistevaatimukset

Elinkaaren päätepisteesi täytyy:

• Ole julkisesti saatavilla HTTPS:n kautta
• Vastaa kohtuullisen ajan sisällä (suositeltava: 30 sekuntia)
• Palauta sopivat HTTP-tilakoodit
• Hoida tunnistautuminen annetulla tunnisteella

Toimintojen luominen ja päivitys, jotka haluat estää:

• Palauta 4xx-tilakoodi virhetiedoilla
• Sisällytä käyttäjäystävällinen virheilmoitus vastausrunkoon

Onnistuneille operaatioille tai poisto- ja palautusoperaatioille:

• Palauta 200 OK -tilakoodi
• Voit halutessasi lisätä lokitus- tai seurantatiedot

Paikallinen kehitystuki

Paikallista kehitystä ja testausta varten Fabric Extensibility Toolkit tarjoaa kehityspalvelimelle sisäänrakennetun stub-toteutuksen. Tämä mahdollistaa esineiden elinkaaren ilmoitusten testaamisen paikallisella koneellasi ilman, että sinun tarvitsee ottaa käyttöön Azure.

Miten se toimii

Kun ajat paikallisen kehityspalvelimen (katso Aloita Fabric Extensibility Toolkitista ja Register Local Web Server), kaikki elinkaari-ilmoitukset, jotka on määritelty item manifestissasi, ohjataan automaattisesti paikalliselle koneellesi.

Kun elinkaaren tapahtuma tapahtuu kehitystilassa:

1. Ilmoitus siepaa paikallinen kehityspalvelin
2. Lokilausekkeet näkyvät paikallisessa konsolissasi, jotka näyttävät tapahtuman tiedot
3. Esimerkkitoteutus osoittaa, miten kohdemäärittelyn ja OneLake-tallennuksen kanssa voi olla vuorovaikutuksessa
4. Saat tokenin, jolla voi kutsua mitä tahansa Fabric-operaatiota

Tämä stub-toteutus tarjoaa:

• Välitön palaute – Katso lokilausekkeet konsolistasi elinkaaren tapahtumien tapahtuessa
• Esimerkkikoodi – Opi jäsentämään ilmoitusten käsittelylogiikkasi
• OneLake-integraatioesimerkkejä – Katso, miten pääset käsiksi tuotteen OneLake-tallennustilaan ilmoitusten aikana
• tokenin käsittely - Ymmärrä, miten hankitaan ja käytetään Fabric todennustokeneita
• Kohteen määrittelyn käyttöoikeus – Näytä koko alkiomäärittelykuorma

Kehitysstubin käyttö

Paikallisen kehityspalvelimen käyttö elinkaaren ilmoitustestaukseen:

1. Aloita paikallinen kehityspalvelin pikakäynnistysoppaan mukaan
2. Rekisteröi paikallinen verkkopalvelimesi rekisteröitymisvaiheiden avulla
3. Määritä elinkaaren ilmoitukset tuotemanifestissasi kuten yllä kuvattu
4. Suorita item operations (luo, päivitä, poista) Fabric-ohjelmassa
5. Seuraa ilmoitustietoja paikallisesta konsolistasi
6. Tutustu OneLake-interaktion ja tokenien käsittelyn esimerkkikoodiin kehityspalvelinlokeissa

OneLake-interaktioesimerkki

Kehitysstubissa on esimerkkikoodi, joka näyttää, miten voit olla vuorovaikutuksessa tuotteen OneLake-tallennustilan kanssa:

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

Tämä paikallinen kehityskokemus mahdollistaa elinkaaren ilmoituslogiikan rakentamisen ja testaamisen ennen käyttöönottoa tuotantopäätepisteisiin.

Toteutusesimerkki

Seuraava esimerkki käyttää Node.js ja Expressiä, jotka perustuvat Fabric Extensibility Toolkit -viitetoteutukseen. Jokaisella elinkaaren tapahtumalla on oma päätepisteensä, jonka Fabric kutsuu asianmukaisella pyyntökeholla. Täydelliset API-tiedot löytyvät Item Lifecycle REST API -viitteestä.

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

Käyttötapaukset

Infrastruktuurin hallinta

Automaattinen infrastruktuurin käyttöönotto ja poisto kohteen elinkaaren mukaan:

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

Lisenssin ja kiintiön validointi

Valvo toimilupa- ja kapasiteettivaatimuksia käsittelijässä 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
  });
}

Ulkoisen järjestelmän synkronointi

Pidä ulkoiset järjestelmät synkronissa Fabric-tuotteiden kanssa:

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

Poista ja palauta strategia

Toteuta erilaisia siivousstrategioita deleteType, ja hoida palautus:

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

Parhaat käytännöt

Vastaa nopeasti

Elinkaaren päätepisteiden tulisi reagoida mahdollisimman nopeasti:

• Suorita validointi- ja pikaasennusoperaatiot synkronisesti
• Jonotus, pitkäaikainen infrastruktuurin provisiointi taustaprosessointia varten
• Palauta onnistuminen/epäonnistuminen nopeasti aikalisän välttämiseksi

Käsittele idempotenssia

Esineoperaatioita voidaan yrittää uudelleen, joten päätepisteesi tulisi olla idempotentti:

• Tarkista, onko infrastruktuuria jo olemassa ennen luomista
• Käytä yksilöllisiä tunnisteita operaatioiden seuraamiseen
• Käsittele päällekkäiset ilmoitukset sulavasti

Anna selkeät virheilmoitukset

Kun estät operaatioita, anna hyödyllisiä virheilmoituksia:

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

Suojaus

• Validoi autentikointitunnus jokaisessa pyynnössä
• Käytä tokenia varmistaaksesi operaation laillisuuden
• Älä luota item ID:iin tai työtilan ID:hen ilman validointia
• Katso Authenticate Remote Endpoints -osiosta tietoturvan parhaista käytännöistä

Seuranta ja kirjaaminen

• Kirjaa kaikki vastaanotetut elinkaaren ilmoitukset
• Seuraa infrastruktuurin provisionoinnin onnistumista/epäonnistumista
• Seuraa päätelaitteiden suorituskykyä ja virheitä
• Käytä ilmoitustietoja auditointireiteissä

Vianmääritys

Ilmoituksia ei vastaanotettu

• Varmista, että päätepisteen URL on oikein manifestissa
• Tarkista, että päätepiste on julkisesti saatavilla
• Varmista, että HTTPS on oikein konfiguroitu
• Tarkista päätepistelokit virheiden varalta

Operaatioiden aikakatkaisu

• Optimoi päätepisteen vasteaika
• Siirrä pitkäaikaiset toiminnot taustatöihin
• Lisää päätepisteen aikakatkaisuasetuksia tarvittaessa
• Tarkastele infrastruktuurin provisionoinnin suorituskykyä

Estäminen ei toimi

• Varmista, että palautat 4xx-tilakoodit estettyihin operaatioihin
• Tarkista, että virheilmoitukset sisältyvät vastaukseen
• Varmista, että päätepiste reagoi aikakatkaisuikkunan puitteissa
• Muista, että poistotoimintoja ei voi estää – Fabric-alusta merkitsee kohteen poistetuksi riippumatta työkuormasi reaktiosta.

Aiheeseen liittyvä sisältö

• Todenna etäpäätepisteet
• Ota etäpäätepisteet käyttöön
• Kaupan tuotteen määrittely
• Määrittele työt työkuormallesi
• Aloita Fabric Extensibility Toolkitin parissa
• Rekisteröi paikallinen verkkopalvelin
• Fabric Item Management API
• Fabric CI/CD-yleiskatsaus
• Tuotteen elinkaaren REST API -viite