Aktivieren von Elementlebenszyklusbenachrichtigungen

Lebenszyklusbenachrichtigungen für Elemente bieten Workload-Entwicklern die Möglichkeit, Benachrichtigungen über Lebenszyklusereignisse für benutzerdefinierte Elemente zu empfangen, auch wenn die Benutzeroberfläche der Workload nicht involviert ist. Diese Einstellung ermöglicht es Ihrem Element, auf Elementvorgänge zu reagieren, unabhängig davon, wie sie initiiert wurden.

Übersicht

Elementlebenszyklusbenachrichtigungen sind für Szenarien wichtig, in denen Elemente außerhalb der Benutzeroberfläche Ihrer Workload erstellt, aktualisiert oder gelöscht werden. Dieser Dienst benachrichtigt Ihre Workload immer dann, wenn ein Elementlebenszyklusereignis eintritt, sodass Sie:

• Einrichten oder Abreißen der Infrastruktur für neue oder gelöschte Elemente
• Überprüfen von Lizenzen oder Kontingenten vor dem Zulassen von Vorgängen
• Synchronisieren des Zustands mit externen Systemen
• Implementieren von benutzerdefinierter Geschäftslogik für Elementvorgänge
• Handhabung von Szenarien für weiche Löschungen mit benutzerdefinierter Aufräumlogik

Wenn Lebenszyklusbenachrichtigungen ausgelöst werden

Lebenszyklusbenachrichtigungen werden für Elementvorgänge ausgelöst, die aus mehreren Quellen stammen:

Öffentliche APIs

Elemente können über Fabric öffentliche REST-APIs ohne Interaktion mit der Benutzeroberfläche Ihrer Workload erstellt, aktualisiert oder gelöscht werden. Beispiel:

• Automatisierungsskripts mit der Items-API
• Anwendungen von Drittanbietern, die in Fabric integriert werden
• Programmgesteuerte Administrative Vorgänge

CI/CD-Pipelines

Elemente werden als Teil automatisierter Bereitstellungspipelines über die CI/CD-Funktionen von Fabric bereitgestellt. Szenario:

• Elemente werden als Teil von Git-Integrationsworkflows erstellt oder aktualisiert.
• Bereitstellungspipelines befördern Elemente durch verschiedene Umgebungen
• Während des Bereitstellungsprozesses tritt keine Benutzeroberflächeninteraktion auf.

Plattform-gesteuerte UX-Abläufe

Auch innerhalb der Fabric Benutzeroberfläche steuert die Plattform bestimmte Erstellungs- und Verwaltungsabläufe. Ihre Arbeitsaufgabe empfängt Benachrichtigungen für diese Vorgänge, um Konsistenz sicherzustellen.

• Elementerstellung über Plattformdialoge
• Vorgänge auf Arbeitsbereichsebene, die sich auf Elemente auswirken
• Arbeitsbereichübergreifende Kopier- oder Verschiebungsvorgänge

Lebenszyklusereignisse

Ihre Workload kann Benachrichtigungen für die folgenden Lebenszyklusereignisse erhalten:

Create

Wird ausgelöst, wenn ein neues Element erstellt wird. Sie haben folgende Möglichkeiten:

• Einrichten der erforderlichen Infrastruktur (Datenbanken, Computeressourcen)
• Überprüfen von Lizenzen oder Kapazitätskontingenten
• Initialisieren elementspezifischer Ressourcen
• Blockieren des Vorgangs , wenn die Überprüfung fehlschlägt oder voraussetzungen nicht erfüllt sind

Update

Wird ausgelöst, wenn die Definition oder Eigenschaften eines Elements geändert werden. Sie haben folgende Möglichkeiten:

• Aktualisieren der zugeordneten Infrastruktur
• Überprüfen der neuen Konfiguration
• Synchronisieren von Änderungen mit externen Systemen
• Blockieren des Vorgangs , wenn das Update gegen Geschäftsregeln verstößt

Löschen

Wird ausgelöst, wenn ein Element gelöscht wird. Die Anforderung enthält ein deleteType-Feld, das angibt, ob es sich um einen physischen oder logischen Löschvorgang handelt.

• Endgültig löschen: Dauerhafte Löschung – Bereinigen aller zugeordneten Ressourcen
• Vorläufiges Löschen: Das Element wird zum Löschen markiert, kann aber später wiederhergestellt werden – genügend Metadaten und Ressourcen aufbewahren, um die Wiederherstellung zu unterstützen.

Ihre Workload kann verschiedene Strategien für das vorläufige Löschen auswählen:

• Beenden von teuren Computeressourcen beim Aufbewahren von Daten
• Archivieren wichtiger Daten auf kostengünstigeren Speicher
• Beibehalten des vollständigen Zustands für den Wiederherstellungszeitraum

Wiederherstellen

Wird ausgelöst, wenn ein zuvor vorläufig gelöschtes Element wiederhergestellt wird. Ihr Endpunkt empfängt die Elementdefinition und sollte:

• Neu zuordnen von Ressourcen, die während der Soft-Löschung freigegeben wurden
• Wiederherstellen des Elementstatus und Fortsetzen von Diensten
• Erneutes Initialisieren von Compute- oder Speicherressourcen nach Bedarf

Anforderungsformat

Fabric ruft einen separaten Endpunkt für jedes Lebenszyklusereignis auf. Jede Anforderung umfasst:

URL-Pfad-Parameter

Die identifizierenden Informationen des Elements werden im URL-Pfad bereitgestellt:

• workspaceId - Die Arbeitsbereichs-ID (UUID)
• itemType - Der Elementtyp (z. B Contoso.FinanceAnalytics.Forecast. )
• itemId - Die Element-ID (UUID)

Authentifizierungsheader

Der Authorization Header verwendet das SubjectAndAppToken1.0 Schema, das sowohl ein delegiertes Benutzertoken als auch ein Nur-App-Token enthält:

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

Dieses Dualtokenformat ermöglicht Es Ihrer Workload, den Anforderungsursprung zu überprüfen, den Benutzerkontext zu überprüfen und andere Dienste aufzurufen. Zusätzliche erforderliche Kopfzeilen umfassen ActivityId, RequestIdund x-ms-client-tenant-id.

Ausführliche Informationen zum Überprüfen dieser Token finden Sie unter Authentifizieren von Remoteendpunkten.

Anforderungstext

Der Anforderungstext variiert je nach Vorgang:

• Erstellen, Aktualisieren und Wiederherstellen: Der Inhalt enthält ein ItemDefinition Objekt mit einem parts Array. Jeder Teil verfügt über ein path, payload (Base64-codiert) und payloadType.
• Delete: Der Textkörper enthält ein deleteType Feld mit einem Wert von Hard oder Soft.

Die Informationen im Anforderungstext ermöglichen Ihnen Folgendes:

• Extrahieren der Konfiguration für die Infrastruktureinrichtung beim Erstellen und Wiederherstellen
• Verstehen Sie, was sich bei den Aktualisierungsvorgängen geändert hat
• Treffen fundierter Entscheidungen über Blockierungsvorgänge
• Wählen Sie die geeignete Bereinigungsstrategie für harte und weiche Löschvorgänge aus.

Blockieren von Vorgängen

Bei Erstellungs - und Aktualisierungsvorgängen kann Ihre Workload den Vorgang blockieren, indem eine Fehlerantwort vom Lebenszyklusendpunkt zurückgegeben wird. Dies ist nützlich für:

• Lizenzüberprüfung: Verhindern der Elementerstellung, wenn der Benutzer nicht über erforderliche Lizenzen verfügt
• Kontingenterzwingung: Erstellung blockieren, wenn Arbeitsbereichs- oder Kapazitätsgrenzen überschritten werden
• Konfigurationsüberprüfung: Ablehnen von Updates, die ungültige Zustände erstellen würden
• Sicherheitsrichtlinien: Erzwingen von Organisationsrichtlinien für Elementkonfigurationen

Wenn Sie einen Vorgang blockieren:

1. Zurückgeben eines Fehlerstatuscodes (z. B. 400 oder 403) von Ihrem Endpunkt
2. Geben Sie eine klare Fehlermeldung an, in der erläutert wird, warum der Vorgang blockiert wurde.
3. Die Plattform zeigt dem Benutzer Ihre Fehlermeldung an.
4. Der Elementvorgang ist nicht abgeschlossen.

Implementierung der Behandlung von Lebenszyklusbenachrichtigungen

In benutzerdefinierten Elementen definierte Lebenszyklusbenachrichtigungen können nicht direkt in Fabric behandelt werden. Stattdessen müssen Sie einen Remote-Endpunkt implementieren, den Fabric aufruft, wenn ein Lebenszyklusereignis auftritt. Dadurch erhalten Sie vollständige Kontrolle darüber, wo und wie ihre Benachrichtigungsbehandlungslogik ausgeführt wird.

Der Remoteendpunkt kann folgendes sein:

• An Azure Function – Einfache, serverlose Ausführung für die einfache Benachrichtigungsverarbeitung
• An Azure Containerinstanz – Für Benachrichtigungen, die bestimmte Laufzeitumgebungen erfordern
• Ein benutzerdefinierter Webdienst – für komplexe Orchestrierung und Verarbeitung
• Jeder Computedienst – solange er einen HTTP-Endpunkt verfügbar machen und die Benachrichtigung behandeln kann

Ausführliche Informationen zum Implementieren und Konfigurieren von Remoteendpunkten finden Sie unter Aktivieren von Remoteendpunkten.

Konfiguration

Um Lebenszyklusbenachrichtigungen für Ihr benutzerdefiniertes Element zu aktivieren, konfigurieren Sie die Benachrichtigungen im Elementmanifest.

Definieren von Lebenszyklusbenachrichtigungen im Elementmanifest

Fügen Sie der Elementmanifestdatei die Lebenszyklusbenachrichtigungskonfiguration hinzu:

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

Konfigurieren Sie nur die Ereignisse, die Sie behandeln müssen. Legen Sie den Wert auf das Element fest false , oder lassen Sie es aus, wenn Sie keine Benachrichtigungen für einen bestimmten Ereignistyp benötigen.

Endpunktanforderungen

Ihr Lebenszyklusendpunkt muss:

• Über HTTPS öffentlich zugänglich sein
• Innerhalb eines angemessenen Timeouts reagieren (empfohlen: 30 Sekunden)
• Zurückgeben geeigneter HTTP-Statuscodes
• Behandlung der Authentifizierung mit dem bereitgestellten Token

Für Erstellungs- und Aktualisierungsvorgänge, die Sie blockieren möchten:

• Geben Sie den 4xx-Statuscode mit Fehlerdetails zurück
• Einschließen einer benutzerfreundlichen Fehlermeldung im Antworttext

Für Vorgänge, die erfolgreich sind, oder für Lösch- und Wiederherstellungsvorgänge:

• Statuscode 200 OK zurückgeben
• Optionales Einschließen von Protokollierungs- oder Nachverfolgungsinformationen

Unterstützung für lokale Entwicklung

Für lokale Entwicklung und Tests stellt das Fabric Extensibility Toolkit eine integrierte Stubimplementierung im Entwicklungsserver bereit. Auf diese Weise können Sie Elementlebenszyklusbenachrichtigungen auf Ihrem lokalen Computer testen, ohne Azure bereitzustellen.

Funktionsweise

Wenn Sie den lokalen Entwicklungsserver ausführen (siehe Get started with Fabric Extensibility Toolkit and Register Local Web Server), werden alle im Elementmanifest definierten Lebenszyklusbenachrichtigungen automatisch an Ihren lokalen Computer umgeleitet.

Wenn ein Lebenszyklusereignis im Entwicklungsmodus auftritt:

1. Die Benachrichtigung wird vom lokalen Entwicklungsserver abgefangen.
2. Protokolleinträge werden in Ihrer lokalen Konsole mit den Ereignisdetails angezeigt.
3. Eine Beispielimplementierung veranschaulicht die Interaktion mit der Elementdefinition und dem OneLake-Speicher
4. Sie erhalten ein Token, das zum Aufrufen eines beliebigen Fabric Vorgangs verwendet werden kann.

Diese Stubimplementierung bietet Folgendes:

• Sofortiges Feedback – Anzeigen von Protokollanweisungen in Ihrer Konsole, wenn Lebenszyklusereignisse auftreten
• Beispielcode – Erfahren Sie, wie Sie Ihre Benachrichtigungsbehandlungslogik strukturieren.
• OneLake-Integrationsbeispiele – Erfahren Sie, wie Sie während Benachrichtigungen auf den OneLake-Speicher des Elements zugreifen.
• Token-Verarbeitung – Informationen zum Abrufen und Verwenden von Fabric Authentifizierungstoken
• Elementdefinitionszugriff – Anzeigen der vollständigen Elementdefinitionsnutzlast

Verwenden des Entwicklungs-Stubs

So verwenden Sie den lokalen Entwicklungsserver für Lebenszyklusbenachrichtigungstests:

1. Starten Des lokalen Entwicklungsservers im Anschluss an die Schnellstartanleitung
2. Registrieren Des lokalen Webservers mithilfe der Registrierungsschritte
3. Konfigurieren von Lebenszyklusbenachrichtigungen in Ihrem Elementmanifest wie oben beschrieben
4. Ausführen von Elementvorgängen (Erstellen, Aktualisieren, Löschen) in Fabric
5. Überprüfen Sie die Benachrichtigungsdetails in Ihrer lokalen Konsole.
6. Den Beispielcode für die OneLake-Interaktion und die Tokenverarbeitung in den Entwicklungsserverprotokollen überprüfen.

Beispiel für oneLake-Interaktion

Der Entwicklungs-Stub enthält Beispielcode zur Interaktion mit dem OneLake-Speicher des Elements:

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

Mit dieser lokalen Entwicklungsumgebung können Sie Ihre Lebenszyklusbenachrichtigungslogik vor der Bereitstellung in Produktionsendpunkten erstellen und testen.

Implementierungsbeispiel

Im folgenden Beispiel werden Node.js und Express basierend auf der Referenzimplementierung Fabric Extensibility Toolkit verwendet. Fabric ruft jeden Endpunkt eines Lebenszyklusereignisses mit dem entsprechenden Anforderungstext auf. Vollständige API-Details finden Sie in der Elementlebenszyklus-REST-API-Referenz.

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

Anwendungsfälle

Infrastrukturverwaltung

Automatische Bereitstellung und Entfernung von Infrastrukturen basierend auf dem Lebenszyklus eines Elements.

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

Lizenz- und Kontingentüberprüfung

Erzwingen von Lizenzierungs- und Kapazitätsanforderungen im 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
  });
}

Externe Systemsynchronisierung

Synchronisierung externer Systeme mit Fabric Elementen:

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

Lösch- und Wiederherstellungsstrategie

Implementieren Sie verschiedene Bereinigungsstrategien auf Grundlage von deleteType und kümmern Sie sich um die Wiederherstellung.

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

Bewährte Methoden

Schnelles Reagieren

Lebenszyklusendpunkte sollten so schnell wie möglich reagieren:

• Synchrones Ausführen von Überprüfungs- und Schnelleinrichtungsvorgängen
• Langandauernde Infrastrukturbereitstellung in der Warteschlange für die Hintergrundverarbeitung.
• Geben Sie Erfolg oder Misserfolg schnell zurück, um Timeouts zu vermeiden

Umgang mit Idempotenz

Elementvorgänge können wiederholt werden, sodass Ihr Endpunkt idempotent sein sollte:

• Überprüfen, ob die Infrastruktur bereits vor dem Erstellen vorhanden ist
• Verwenden eindeutiger Bezeichner zum Nachverfolgen von Vorgängen
• Behandeln doppelter Benachrichtigungen ordnungsgemäß

Bereitstellen klarer Fehlermeldungen

Stellen Sie beim Blockieren von Vorgängen hilfreiche Fehlermeldungen bereit:

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

Sicherheit

• Überprüfen des Authentifizierungstokens für jede Anforderung
• Verwenden des Tokens, um zu überprüfen, ob der Vorgang legitim ist
• Vertrauen Sie Element-IDs oder Arbeitsbereichs-IDs nicht, ohne sie zu überprüfen.
• Siehe Authentifizieren von Remoteendpunkten für bewährte Sicherheitspraktiken.

Überwachung und Protokollierung

• Protokollieren aller empfangenen Lebenszyklusbenachrichtigungen
• Nachverfolgen des Erfolgs/Fehlers der Infrastrukturbereitstellung
• Überwachen der Endpunktleistung und -fehler
• Verwenden von Benachrichtigungsdaten für Prüfpfade

Problembehandlung

Benachrichtigungen nicht empfangen

• Überprüfen, ob die Endpunkt-URL im Manifest korrekt ist
• Überprüfen, ob der Endpunkt öffentlich zugänglich ist
• Sicherstellen, dass HTTPS ordnungsgemäß konfiguriert ist
• Überprüfen von Endpunktprotokollen auf Fehler

Betriebszeitüberschreitung

• Optimieren der Endpunktantwortzeit
• Verschieben von lang andauernden Vorgängen in Hintergrundaufträge
• Erhöhen Sie bei Bedarf die Timeout-Einstellungen für Endpunkte.
• Überprüfen der Leistung der Infrastrukturbereitstellung

Blockieren funktioniert nicht

• Überprüfen, ob Sie 4xx-Statuscodes für blockierte Vorgänge zurückgeben
• Überprüfen Sie, ob Fehlermeldungen in der Antwort enthalten sind.
• Stellen Sie sicher, dass der Endpunkt innerhalb des Timeoutfensters antwortet.
• Denken Sie daran, dass Löschvorgänge nicht blockiert werden können – die Fabric Plattform kennzeichnet das Element unabhängig von der Antwort Ihrer Workload als gelöscht.

Verwandte Inhalte

• Authentifizieren von Remoteendpunkten
• Aktivieren von Remoteendpunkten
• Store-Elementdefinition
• Definieren Sie Aufträge für Ihre Workload
• Einführung in das Fabric Extensibility Toolkit
• Registrieren des lokalen Webservers
• Fabric Elementverwaltungs-API
• Fabric CI/CD Übersicht
• Elementlebenszyklus-REST-API-Referenz