Rozszerzanie frontonu usługi Microsoft Fabric

Zestaw Microsoft Fabric Workload Development Kit umożliwia tworzenie obciążeń i tworzenie niestandardowych funkcji, które rozszerzają środowisko sieci szkieletowej. Platforma sieci szkieletowej została zaprojektowana tak, aby współdziałała z możliwościami niezależnego dostawcy oprogramowania (ISV). Możesz na przykład użyć edytora elementów, aby utworzyć natywne, spójne środowisko użytkownika, osadzając fronton niezależnego dostawcy oprogramowania w kontekście elementu obszaru roboczego sieć szkieletowa.

W tym artykule użyjesz przykładowego repozytorium tworzenia obciążeń usługi Microsoft Fabric jako przewodnika w celu zintegrowania niestandardowej aplikacji internetowej obciążenia środowiska użytkownika z usługą Microsoft Fabric. Projekt i szczegółowe przykłady ułatwiają bezproblemową integrację własnych składników interfejsu użytkownika i akcji ze środowiskiem środowiska uruchomieniowego sieci Szkieletowej w celu wydajnego eksperymentowania i dostosowywania.

Fronton przykładowego projektu obciążenia środowiska użytkownika to standardowa aplikacja internetowa platformy React , która zawiera zestaw SDK klienta obciążenia jako standardowy pakiet npm w celu zapewnienia funkcjonalności.

Niezależnego dostawcy oprogramowania hostuje i uruchamia projekt wewnątrz elementu w trybie piaskownicy <iframe> w portalu sieci szkieletowej. Przedstawia środowiska interfejsu użytkownika specyficzne dla niezależnego dostawcy oprogramowania, w tym edytor elementów.

Zestaw SDK udostępnia wszystkie niezbędne interfejsy, interfejsy API i funkcje uruchamiania wymagane do przekształcenia regularnej aplikacji internetowej w aplikację internetową mikro frontonu, która bezproblemowo działa w portalu sieci szkieletowej.

Zestaw SDK udostępnia przykładowy projekt obciążenia środowiska użytkownika. Przykład:

• Pokazuje, jak używać większości dostępnych wywołań zestawu SDK.
• Przedstawia przykład rozszerzalnej wstążki opartej na interfejsie użytkownika Fluent, która pasuje do wyglądu i działania sieci szkieletowej.
• Umożliwia łatwe dostosowywanie.
• Umożliwia obserwowanie zmian w sieci szkieletowej w czasie rzeczywistym po włączeniu trybu dewelopera sieci szkieletowej.

Wymagania wstępne

• Aplikacja internetowa obciążenia środowiska użytkownika

  Ten pakiet jest oparty na interfejsie użytkownika Fluent i jest przeznaczony dla platformy React.

• Manifest frontonu obciążenia środowiska użytkownika

  Manifest frontonu obciążenia środowiska użytkownika to zasób JSON zapewniany przez niezależnego dostawcę oprogramowania. Plik zawiera podstawowe informacje o obciążeniu, w tym adres URL aplikacji internetowej obciążenia i różne szczegóły interfejsu użytkownika, takie jak nazwa wyświetlana elementu niezależnego dostawcy oprogramowania i skojarzone ikony. Niezależnego dostawcy oprogramowania może użyć pliku manifestu, aby dostosować, co się stanie, gdy użytkownicy wchodzą w interakcję z elementami w portalu sieci szkieletowej.

W tym pakiecie pliki manifestu frontonu znajdują się w folderze pakietu. Plik manifestu zawiera szczegółowy opis manifestu obciążenia i jego składników.

Włączanie funkcji tworzenia obciążeń w sieci szkieletowej

Administrator dzierżawy musi najpierw włączyć funkcję tworzenia obciążeń w portalu administracyjnym usługi Microsoft Fabric. Tę funkcję można włączyć dla całej organizacji lub dla określonych grup w organizacji. Aby umożliwić administratorowi dzierżawy włączenie funkcji tworzenia obciążeń dla określonych grup, wykonaj kroki opisane w temacie Włącz ustawienie dzierżawy dewelopera.

Konfigurowanie frontonu

Aby skonfigurować przykładowy fronton projektu:

1. Sprawdź, czy Node.js i narzędzie npm są zainstalowane. Instalacja narzędzia npm musi być w wersji 9 lub nowszej. W przeciwnym razie zainstaluj najnowsze wersje Node.js i npm.

2. Sklonuj przykładowe repozytorium tworzenia obciążeń usługi Microsoft Fabric.

   Poniższa lista zawiera opis układu katalogu pakietów, składników i zasobów:

   • Pakiet: lokalizacja pakietu obciążenia. Pakiet zawiera zasoby frontonu, w tym manifesty i zasoby.
   • src: kod obciążenia zawierający następujące zasoby:
     • index.ts: główny plik inicjowania, w tym bootstrap i index.worker index.ui i iFrame (zobacz szczegóły w dalszej części tego artykułu).
     • App.tsx: ten plik kieruje ścieżki do stron. Na przykład /sample-workload-editor element jest kierowany do SampleWorkloadEditor funkcji w obszarze components.
     • Zasoby: lokalizacja obrazów (.jpg, .jpeg i png), do których można się odwoływać w manifeście i pokazana w interfejsie użytkownika. Na przykład assets/github.jpg parametr jest ustawiany w manifeście jako ikona produktu.
     • components: lokalizacja kodu interfejsu użytkownika, w tym widok edytora i inne widoki używane przez przykład (wstążka, strona uwierzytelniania i panele).
     • kontroler: kontroler wywołuje interfejsy API zestawu SDK.
     • modele: kontrakty i modele, które są używane przez interfejs użytkownika i do komunikacji z zapleczem kotła.
   • tools: Elementy, których można użyć do tworzenia ustawień i konfiguracji.
     • webpack.config.js: użyj tego pliku, aby skonfigurować lokalny serwer Node.js.
     • Konfiguracja sieci Web i czytnik/procesor manifestu.
   • walidacja: w przykładzie użyto validateSchema.js metody sprawdzania poprawności schematów plików JSON i produktu. Jest ona skonfigurowana do uruchamiania w systemie npm start.

3. W folderze repozytorium przejdź do folderu Frontend , aby zainstalować pliki projektu:

   <repository folder>\Frontend> npm install
   

4. Uruchom serwer, uruchamiając następujące polecenie:

   <repository folder>\Frontend> npm start
   

   To polecenie uruchamia lokalny serwer Node.js (przy użyciu pakietu webpack), z którego usługa Microsoft Fabric nawiązuje połączenie, gdy jest w trybie dewelopera.

   Aby uzyskać informacje na temat szczegółów portów wyświetlanych po uruchomieniu serwera, zobacz uwagi dotyczące lokalnego serwera hosta.

   Bieżący port to 60006.

   Po uruchomieniu serwera localhost przejdź do adresu URL 127.0.0.1:60006/manifests , aby otworzyć zagregowany manifest utworzony w folderze Frontend/Package .

   Jeśli zmienisz pliki w folderze Frontend/Package , uruchom npm start go ponownie.

   To ustawienie jest utrwalane w bieżącej przeglądarce.

   

Przykład "Hello world"

Aby uruchomić scenariusz testowy "hello world":

1. Uruchom serwer lokalny (wykonaj kroki opisane w temacie Wprowadzenie , aby uruchomić zarówno przykłady obciążeń frontonu, jak i zaplecza) i upewnij się, że tryb dewelopera jest włączony.

2. W menu obszaru roboczego wybierz ikonę Utwórz centrum (czasami ikona znajduje się w obszarze Pokaż więcej wielokropka).

   

3. Wybierz opcję Zobacz wszystko.

   

4. W obszarze Przykładowe obciążenie wybierz kartę Przykładowy element , aby utworzyć element.

   

Nowy element wygląda podobnie do tego przykładu:

Zapoznaj się z różnymi kontrolkami, aby wyświetlić możliwości interfejsu API Obciążenia sieci szkieletowej (zestawu SDK obciążenia):

• Otwieranie powiadomień i okien dialogowych
• Przejdź do stron
• Pobieranie ustawień motywu i obciążenia
• Wykonywanie akcji

Większość dostępnych funkcji zestawu SDK jest skonfigurowana jako akcje przycisku lub zarejestrowana jako wywołania zwrotne. Wyniki zazwyczaj są powiadomieniem lub polem komunikatu, które pokazuje, że interfejs API został wywołany.

Na przykład:

• Wykonaj akcję wywołuje interfejs API action.execute() z akcją o nazwie sample. Akcja. Funkcja akcji polega na wyświetlaniu powiadomienia.

• Wybierz pozycję Zapisz na wstążce, aby wywołać interfejs API dialog.open(). Interfejs API otwiera okno dialogowe, w którym użytkownik wprowadza nazwę i zapisuje element w sieci szkieletowej. Aby uzyskać więcej informacji na temat okna dialogowego, zobacz sekcję CRUD.

• Przycisk Pobierz ustawienia motywu zawiera listę konfiguracji motywu sieci szkieletowej (za pośrednictwem interfejsu API theme.get().

Przykładowy interfejs użytkownika obciążenia jest hostowany w elemecie w trybie piaskownicy iframe sieci szkieletowej, który jest wyświetlany w trybie dewelopera dla strony internetowej.

Uwaga

Element w iframe trybie piaskownicy obsługuje atrybuty allow-same-origin i allow-scripts.

Aby uzyskać więcej informacji na temat piaskownicy i atrybutów, zobacz Dokumentacja sieci Web usługi MDN.

Zrozumienie kodu

W poniższych sekcjach opisano elementy kodu i istotne zagadnienia.

bootstrap()

Przed uruchomieniem sprawdź ścieżkę, aby sprawdzić, czy musisz zamknąć okno. Ten krok jest wymagany, jeśli używasz interfejsu API uwierzytelniania .

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
    window.close();
}

Każda aplikacja obciążenia sieci szkieletowej musi obsługiwać inicjowanie w dwóch trybach:

• Tryb interfejsu użytkownika: aplikacja w trybie interfejsu użytkownika jest ładowana w widocznych elementach iFrame. Nasłuchuje ona własnych zmian trasy w celu renderowania odpowiednich składników interfejsu użytkownika, takich jak strony, panele i okna dialogowe.

• Tryb roboczy: aplikacja w trybie roboczym jest uruchamiana w niewidocznym elemecie iFrame. Niewidoczny element iFrame jest używany głównie do odbierania poleceń zewnętrznych, a następnie odpowiadania na nie.

Interfejs @ms-fabric/workload-client API udostępnia metodę bootstrap() upraszczania kroków inicjowania. Metoda wewnętrznie wykrywa, czy bieżąca bootstrap() aplikacja jest ładowana w trybie interfejsu użytkownika, czy w trybie roboczym. Następnie wywołuje odpowiednią metodę inicjowania (initializeUI lub initializeWorker). Po zakończeniu bootstrap() inicjowania powiadamia platformę mikro frontonu sieci szkieletowej o powodzeniu lub niepowodzeniu inicjowania.

bootstrap({
    initializeWorker: (params) =>
        import('./index.worker').then(({ initialize }) => initialize(params)),
    initializeUI: (params) =>
        import('./index.ui').then(({ initialize }) => initialize(params)),
});

index.worker

index.worker jest główną onAction rejestracją. Obsługuje zdarzenia wysyłane przez hosta sieci szkieletowej, które są wyzwalane przez wykonane akcje.

Akcje mogą być wysyłane przez obciążenie do sieci szkieletowej, a następnie wywoływane z powrotem do onAction programu obsługi lub mogą być inicjowane przez hosta sieci szkieletowej. Na przykład po wybraniu pozycji Utwórz przykładowy element — tylko fronton sieć szkieletowa wyzwala akcję open.createSampleWorkloadFrontendOnly, a onAction program obsługi inicjuje otwarcie głównej strony interfejsu użytkownika obciążenia. Bieżąca wartość obszaru roboczego objectId jest również przekazywana do środowiska tylko frontonu.

Sekwencja jest pokazana w poniższym przykładzie kodu:

   workloadClient.action.onAction((message) => {
        switch (message.action) {
            /**
             * This opens the frontend-only experience, so you can experiment with the UI without using CRUD operations.
             * You can still save the item if the backend is connected and registered.
             */
            case 'open.createSampleWorkloadFrontendOnly':
                const { workspaceObjectId: workspaceObjectId1 } = data as ItemCreateContext;
                return workloadClient.page.open({
                    workloadName: 'Org.WorkloadSample',
                    route: {
                        path: `/sample-workload-frontend-only/${workspaceObjectId1}`,
                    },
                });

                // . . . elided for brevity . . .
            default:
                throw new Error('Unknown action received');
        }
    });

index.ui

Funkcja initialize() renderuje aplikację React DOM, w której App osadzona jest funkcja. Aby wywołać wywołania interfejsu API, przekaż workloadClient dojście zestawu SDK, które jest używane w całym kodzie.

Klasa FluentProvider zapewnia spójność stylu w różnych kontrolkach FluentUI. Oto przykład:

ReactDOM.render(
      <FluentProvider theme={fabricLightTheme}>
           <App
               history={history}
               workloadClient={workloadClient}
           />
       </FluentProvider>,
       document.querySelector("#root")
   );

Przepływ programowania

• Funkcja App kieruje kod do SampleWorkloadEditor. Funkcja zwraca wartość .React.JSX.Element
• Funkcja zawiera strukturę interfejsu użytkownika. Struktura interfejsu użytkownika zawiera kontrolki wstążki i strony, takie jak przyciski i pola wejściowe.
• Informacje zbierane od użytkownika są przechowywane za pośrednictwem punktu zaczepienia React useState() .
• Programy obsługi kontrolek interfejsu użytkownika nazywają SampleWorkloadController funkcje i przekazują odpowiednie zmienne stanu.
• Aby obsługiwać operacje CRUD, stan utworzonego/załadowanego elementu jest przechowywany wraz artifactItem z workspaceObjectId przykładową implementacją zmiennych ładunku.

W poniższych przykładach użyto interfejsu API notification.open():

• Stan:

     const [apiNotificationTitle, setNotificationTitle] = useState<string>('');
     const [apiNotificationMessage, setNotificationMessage] = useState<string>('');
  

• UI:

  Te przykłady umożliwiają skonfigurowanie określonych elementów interfejsu użytkownika:

  • Tytuł:

    <Field label="Title" validationMessage={notificationValidationMessage} orientation="horizontal" className="field">
        <Input size="small" placeholder="Notification Title" onChange={e => setNotificationTitle(e.target.value)} />
      </Field>
    

  • Przycisk Wyślij:

    <Button icon={<AlertOn24Regular />} appearance="primary" onClick={() => onCallNotification()} > Send Notification </Button>
    

  • Obsługi:

    function onCallNotification() {
      ... elided for brevity
       callNotificationOpen(apiNotificationTitle, apiNotificationMessage, undefined, undefined, workloadClient, setNotificationId);
    };
    

• Kontroler:

    export async function callNotificationOpen(
      title: string,
      message: string,
      type: NotificationType = NotificationType.Success,
      duration: NotificationToastDuration = NotificationToastDuration.Medium,
      workloadClient: WorkloadClientAPI,
      setNotificationId?: Dispatch<SetStateAction<string>>) {
  
      const result = await workloadClient.notification.open({
          notificationType: type,
          title,
          duration,
          message
      });
      if (type == NotificationType.Success && setNotificationId) {
          setNotificationId(result?.notificationId);
      }
  }
  

Operacje CRUD

Chociaż scenariusz programowania tylko dla frontonu jest łatwo obsługiwany, pełne środowisko deweloperskie wymaga zapisywania, odczytywania i edytowania istniejących elementów obciążenia.

W przewodniku implementacji zaplecza opisano szczegółowo sposób konfigurowania zaplecza i korzystania z niego.

Gdy zaplecze jest uruchomione Org.WorkloadSample.SampleWorkloadItem i typ jest zarejestrowany w sieci szkieletowej, możesz wykonać operacje CRUD na tym typie.

Następujące operacje są uwidocznione przy użyciu interfejsu API ItemCrud.

CREATE

Aby wykonać createprzykładowe wywołanie metody , użyj następującego przykładu, który pokazuje zapisywanie elementu obciążenia po raz pierwszy:

 const params: CreateItemParams = {
        workspaceObjectId,
        payload: { itemType, displayName, description, workloadPayload: JSON.stringify(workloadPayload), payloadContentType: "InlineJson", }
    };
 const result: CreateItemResult = await workloadClient.ItemCrud.createItem(params);

Nasza przykładowa implementacja przechowuje utworzony element w pliku artifactItem.

Element jest tworzony w aktualnie wybranym obszarze roboczym. Obszar roboczy musi być przypisany do pojemności ustawionej w konfiguracji zaplecza. Aby uzyskać więcej informacji, zobacz dokumentację zaplecza.

Próba utworzenia elementu w niezgodnym obszarze roboczym kończy się niepowodzeniem:

• Wywołanie onCreateFabricItem zwrotne w zapleczu blokuje wywołanie CREATE . Błąd w tym momencie powoduje niepowodzenie operacji i żaden element nie jest tworzony w sieci szkieletowej. Aby uzyskać więcej informacji, zobacz dokumentację debugowania i rozwiązywania problemów zaplecza.

• Obecnie zapisany element nie jest automatycznie wyświetlany w obszarze roboczym. Aby wyświetlić zapisany element w obszarze roboczym, odśwież stronę.

GET

Po wybraniu istniejącego przykładowego elementu obciążenia w widoku obszaru roboczego sieć szkieletowa przechodzi do trasy zdefiniowanej w manifeście frontonu w artifacts>>editorpathprogramie :

"items": [
  {
   "name": "Org.WorkloadSample.SampleWorkloadItem",
   "editor": {
    "workload": "Org.WorkloadSample",
    "path": "/sample-workload-editor"
   },

Podczas wywoływania metody itemCrud.getItemdane są ładowane zarówno z zaplecza sieci szkieletowej, jak i z zaplecza obciążenia. Dane z obu źródeł są ładowane do artifactItem obiektu otwartego graficznego interfejsu użytkownika.

UPDATE

Aby zaktualizować istniejący element, użyj polecenia itemCrud.updateItem. Ładunek obciążenia jest aktualizowany przez zaplecze obciążenia. W sieci szkieletowej tylko zmiany elementu lastModifiedTime po aktualizacji.

DELETE

Operację można wywołać w widoku obszaru roboczego Sieć szkieletowa delete jako ogólną akcję dostępną dla wszystkich elementów lub za pomocą jawnego wywołania z obciążenia do itemCrud.deleteItem.

Oba typy wywołań przechodzą przez wywołanie zwrotne zaplecza onDeleteItem obciążenia.

Wyświetlanie działań uwierzytelniania

W edytorze przykładowego obciążenia można wyświetlić działanie uwierzytelniania.

Przed użyciem interfejsu API uwierzytelniania skonfiguruj aplikację do uwierzytelniania przy użyciu identyfikatora Entra firmy Microsoft.

Upewnij się również, że plik env.dev jest poprawnie skonfigurowany. Aby uzyskać więcej informacji, zobacz Konfigurowanie manifestu lokalnego obciążenia i uzyskiwanie tokenu dla aplikacji.

Debugowanie

Aby wyświetlić elementy procesu roboczego i elementu iframe interfejsu użytkownika, w przeglądarce wybierz pozycję F12, aby otworzyć narzędzia deweloperskie przeglądarki. Wybierz kartę Źródła .

Punkt przerwania można umieścić w elemecie iframe procesu roboczego i wyświetlić główny switch element w akcji przychodzącej. Możesz również debugować element iframe interfejsu użytkownika. Możesz na przykład debugować kod wewnątrz SampleWorkloadEditorpliku .

Płynne kontrolki interfejsu użytkownika

Obciążenia środowiska użytkownika korzystają z kontrolek Fluent UI w celu zapewnienia spójności wizualnej z usługą Fabric i ułatwiają programowanie. Przykładowy projekt obciążenia zawiera przykłady używania najbardziej typowych kontrolek.

Aby uzyskać więcej informacji, zobacz Fluent UI.

Dostosowywanie manifestu frontonu

Manifest frontonu opisuje aspekty frontonu obciążenia, w tym wygląd produktu, nazwy, zasoby wizualne i dostępne akcje. Manifest frontonu jest głównym punktem kontaktu między siecią szkieletową a obciążeniem.

W przypadku naszego przykładowego obciążenia manifest jest ładowany do sieci szkieletowej w trybie dewelopera. Sekcje manifestu, definicje i przykłady manifestu są wyświetlane w plikach manifestu frontonu.

Zmiany wpisów manifestu, ustawień akcji i aktualizacji zasobów wizualnych są wyświetlane w czasie rzeczywistym po odświeżeniu strony.

Obsługiwane interfejsy API zestawu SDK klienta

Obsługiwane są następujące interfejsy API:

• notification.open
• notification.hide
• panel.open
• panel.close
• action.onAction
• action.execute
• navigation.navigate
• navigation.onNavigate
• navigation.onBeforeNavigateAway
• navigation.onAfterNavigateAway
• page.open
• dialog.openDialog
• dialog.openMessageBox
• dialog.close
• theme.get
• theme.onChange
• settings.get
• settings.onChange
• errorHandling.openErrorDialog
• errorHandling.handleRequestFailure
• itemCrud.createItem
• itemCrud.getItem
• itemCrud.updateItem
• itemCrud.deleteItem
• itemSchedule.runItemJob
• itemSchedule.cancelItemJob
• itemRecentRuns.open

Aby uzyskać więcej informacji, zobacz pakiet @ms-fabric/workload-client.

Powiązana zawartość

• Omówienie zestawu Workload Development Kit
• Przewodnik konfiguracji zaplecza