패브릭 워크로드 개발 키트 프런트 엔드(미리 보기)

아티클
08/14/2024

이 Microsoft Fabric 워크로드 개발 샘플 리포지 토리는 사용자 지정 UX 워크로드를 Microsoft Fabric과 통합하기 위한 가이드 역할을 합니다. 이 프로젝트를 통해 개발자는 자체 UI 구성 요소 및 동작을 패브릭의 런타임 환경에 원활하게 통합하여 신속한 실험 및 사용자 지정을 가능하게 합니다. 개발자는 패브릭 개발 키트의 프레임워크를 사용하여 워크로드를 빌드하고 패브릭 환경을 확장하는 사용자 지정 기능을 만들 수 있습니다. 패브릭 플랫폼은 ISV(Independent Software Vendor) 기능과 상호 운용 가능하도록 설계되었습니다. 예를 들어 항목 편집기를 사용하면 패브릭 작업 영역 항목의 컨텍스트에 ISV의 프런트 엔드를 포함하여 일관되고 일관된 네이티브 사용자 환경을 만들 수 있습니다.

UX 워크로드 프런트 엔드는 해당 기능을 사용하도록 설정하는 표준 npm 패키지인 워크로드 클라이언트 SDK를 통합하는 표준 웹앱(React)입니다. ISV는 패브릭 포털에서 호스트하고 실행 <iframe> 합니다. 항목 편집기 같은 ISV 관련 UI 환경을 제공합니다. SDK는 일반 웹앱을 패브릭 포털 내에서 원활하게 작동하는 마이크로 프런트 엔드 웹앱으로 변환하는 데 필요한 모든 인터페이스, API 및 부트스트랩 함수를 제공합니다.

SDK는 다음 기능을 사용하여 샘플 UI를 제공합니다.

사용 가능한 대부분의 SDK 호출 사용량을 보여 줍니다.
패브릭의 모양과 느낌과 일치하는 Fluent UI 기반 확장성 리본 의 예를 보여 줍니다.
쉽게 사용자 지정할 수 있습니다.
패브릭 개발 모드에서 패브릭의 변경 내용을 실시간으로 관찰할 수 있습니다.

필수 조건

UX 워크로드 웹앱

이 패키지는 Fluent UI를 기반으로 빌드되며 React용으로 설계되었습니다.
UX 워크로드 프런트 엔드 매니페스트

UX 워크로드 프런트 엔드 매니페스트는 ISV에서 제공하는 JSON 리소스입니다. 워크로드 웹앱의 URL과 같은 워크로드에 대한 필수 정보 및 ISV 항목의 표시 이름 및 관련 아이콘과 같은 다양한 UI 세부 정보가 포함됩니다. 또한 ISV는 사용자가 패브릭 포털에서 항목과 상호 작용할 때 발생하는 작업을 사용자 지정할 수 있습니다.

이 패키지에서 매니페스트 파일은 패키지 폴더 아래에 있습니다. 프런트 엔드 매니페스트 파일 및 자세한 설명은 프런트 엔드 매니페스트 파일에서 찾을 수 있습니다.

1단계: 패브릭에서 워크로드 개발 기능 사용

테넌트 관리자는 관리 포털에서 워크로드 개발 기능을 사용하도록 설정해야 합니다. 테넌트 스위치 용량 관리자가 추가 워크로드를 개발할 수 있도록 설정하여 전체 조직 또는 조직 내의 특정 그룹에 대해 사용하도록 설정할 수 있습니다.

워크로드 개발 테넌트 스위치의 스크린샷.

2단계: 프런트 엔드 설정

샘플 프로젝트의 프런트 엔드를 설정하려면 다음 단계를 수행합니다.

설치되어 있고 버전이 Node.js npm 9 이상인지 npm 확인합니다(그렇지 않은 경우 최신 Node.js 설치 및 npm).
리포지토리 복제 : 여기에 있는 리포지토리 복제: https://go.microsoft.com/fwlink/?linkid=2272254

필수 구성 요소 및 리소스에 대한 설명이 포함된 패키지 디렉터리 레이아웃입니다.
- 패키지 - 워크로드 패키지의 위치: 매니페스트 및 자산을 포함한 프런트 엔드 리소스입니다.
- src - 워크로드 코드:
  - index.ts - 주 초기화 파일, bootstrap index.worker 및 index.ui iFrames - 아래에 자세히 설명되어 있습니다.
  - App.tsx - 예를 들어 /sample-workload-editor 페이지로 경로 라우팅은 아래 함수로 SampleWorkloadEditor 라우팅됩니다. components
  - 자산 - 매니페스트에서 참조되고 UI에 표시될 수 있는 이미지(svg, jpg, png등)의 위치입니다. 예를 들어 assets/github.svg 매니페스트에서 제품의 아이콘으로 설정됩니다.
  - 구성 요소 - 실제 UI 코드의 위치 - 편집기 보기 및 샘플에서 사용되는 기타 보기(리본, 인증 페이지, 패널 등)
  - 컨트롤러 - SDK API를 호출하는 컨트롤러
  - 모델 - UI 자체 및 상용구 백 엔드와의 통신에 사용되는 계약 및 모델
- 공구 -
  - webpack.config.js - 로컬 Node.js 서버 구성
  - 웹 구성 및 매니페스트 판독기/프로세서
- 유효성 검사 -
  - validateSchema.js - 제품 및 항목 json 파일 스키마의 유효성 검사 에서 실행되도록 구성됩니다 npm start.
설치합니다. 아래의 기존 패키지를 확인합니다. node_modules

리포지토리 폴더에서 npm 설치로 Frontend 이동하여 실행 합니다.
```
<repository folder>\Frontend> npm install
```
서버 시작
```
<repository folder>\Frontend> npm start
```
이 명령은 개발 모드에서 Microsoft Fabric이 연결하는 로컬 Node.js 서버(사용 webpack)를 시작합니다.

시작 후 표시되는 포트 세부 정보는 localhost 서버 노트를 참조하세요. 현재 포트는 .입니다 60006. localhost 서버가 시작된 후 URL 127.0.0.1:60006/manifests 을 엽니다. 'Frontend/Package' 폴더에서 만든 집계된 매니페스트를 가져옵니다. 서버를 열고 서버가 실행 중인지 확인합니다.

원본 파일을 수정하면 이미 연결된 경우 Fabric webpack에서 콘텐츠가 다시 로드됩니다. 그러나 일반적으로 페이지를 새로 고쳐야 합니다.

'Frontend/Package' 폴더에서 파일을 변경하는 경우 "npm start"를 다시 시작해야 합니다.
Fabric에서 실행 하여 Fabric 개발자 모드 설정을 사용하도록 설정하여 Fabric이 localhost 서버에 액세스할 수 있도록 합니다. 개발자 설정 -->패브릭 개발자 모드로 이동하여 페이지를 새로 고칩니다. 이 설정은 현재 브라우저에서 유지됩니다.

사용 예

일반적인 헬로 월드 테스트 시나리오를 실행하려면 다음을 수행합니다.

로컬 서버를 시작하고 개발 모드를 사용하도록 설정합니다. 왼쪽 아래 모서리의 메뉴에는 새 샘플 워크로드가 표시됩니다.
샘플 워크로드를 선택하고 사용자를 샘플 워크로드 홈 페이지로 이동합니다. 위쪽 섹션에서는 환경 만들기를 제공합니다.
샘플 워크로드 카드를 선택하여 패브릭 내에서 샘플 워크로드의 UI를 엽니다.

다양한 컨트롤을 탐색하여 패브릭의 SDK(WorkloadClient API) 기능을 확인합니다.

알림 및 대화 상자 열기
페이지로 이동
테마 및 워크로드 설정 가져오기
작업 실행

사용 가능한 대부분의 SDK 기능은 단추 작업에 연결되거나 콜백으로 등록됩니다. 결과는 일반적으로 API가 호출되었음을 보여 주는 알림 또는 메시지 상자입니다.

예시:

실행 작업은 샘플이라는 작업을 사용하여 action.execute() API를 호출합니다. 작업입니다. 작업의 기능은 알림을 표시하는 것입니다.
리본에서 저장을 선택하여 API를 호출 dialog.open() 합니다. 그러면 사용자가 이름을 제공하고 항목을 Fabric에 저장하는 대화 상자가 열립니다(이 대화 상자는 CRUD 섹션에서 자세히 설명).
테마 설정 가져오기 단추는 API를 통해 theme.get() 패브릭의 테마 구성 목록을 표시합니다.

샘플 워크로드 UI는 페이지의 DOM을 검사할 때 확인할 수 있는 패브릭 iframe 에서 호스트됩니다.

iFrame 포함 이미지의 스크린샷.

3단계: 코드 살펴보기

bootstrap()

부트스트래핑하기 전에 경로를 확인하여 창을 닫아야 하는지 확인합니다. 이 단계는 인증 API에 필요합니다.

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

모든 패브릭 워크로드 앱은 다음 두 가지 모드로 로드되도록 지원해야 합니다.

UI 모드: UI 모드의 Am 앱은 표시되는 iFrames에 로드되고 페이지, 패널, 대화 상자 등과 같은 해당 UI 구성 요소를 렌더링하기 위해 자체 경로 변경 내용을 수신 대기합니다.
작업자 모드: 작업자 모드의 앱은 보이지 않는 iFrame에서 실행되며, 이는 주로 외부 환경에서 전송된 명령을 수신하고 응답하는 데 사용됩니다. @ms-fabric/workload-client 에서는 bootstrap() 초기화 단계를 간소화하는 메서드를 제공합니다. 부트스트랩() 메서드는 현재 앱이 UI 모드 또는 작업자 모드로 로드되는지 여부를 내부적으로 감지한 다음 적절한 초기화 메서드(initializeUI 또는 initializeWorker)를 호출합니다. 초기화가 완료되면 부트스트랩()은 패브릭 마이크로 프런트 엔드 프레임워크에 초기화 성공 또는 실패를 알 수 있습니다.

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

index.worker

기본 등록입니다 onAction . 실행된 작업에 의해 트리거되는 패브릭 호스트에서 전송된 이벤트를 처리합니다. 이러한 작업은 워크로드 자체에서 Fabric으로 전송한 다음 처리기로 다시 onAction 호출하거나 Fabric 호스트에서 시작할 수 있습니다. 예를 들어 샘플 항목 만들기 - 프런트 엔드만을 클릭하면 Fabric은 'open.createSampleWorkloadFrontendOnly' 작업을 트리거하고 onAction 처리기는 다음 코드와 같이 워크로드 기본 UI 페이지의 열기를 시작합니다. 현재 작업 영역 objectId 도 프런트 엔드 전용 환경으로 전달됩니다.

   workloadClient.action.onAction((message) => {
        switch (message.action) {
            /**
             * This opens the Frontend-only experience, allowing to experiment with the UI without the need for CRUD operations.
             * This experience still allows saving the item, if the Backend is connected and registered
             */
            case 'open.createSampleWorkloadFrontendOnly':
                const { workspaceObjectId: workspaceObjectId1 } = data as ItemCreateContext;
                return workloadClient.page.open({
                    extensionName: 'Org.WorkloadSample',
                    route: {
                        path: `/sample-workload-frontend-only/${workspaceObjectId1}`,
                    },
                });

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

index.ui

함수는 initialize() 함수가 포함된 React DOM을 App 렌더링합니다. API 호출을 호출하려면 코드 전체에서 workloadClient 사용되는 SDK 핸들을 전달합니다. 클래스는 FluentProvider 다양한 FluentUI 컨트롤에서 스타일 일관성을 보장합니다.

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

개발 흐름

App는 코드를 반환하는 함수인 로 SampleWorkloadEditor라우팅합니다React.JSX.Element.
함수에는 UI 구조(리본 메뉴 및 페이지의 컨트롤( 단추, 입력 필드 등)가 포함됩니다.
사용자로부터 수집된 정보는 React의 useState() 후크를 통해 저장됩니다.
UI 컨트롤의 처리기는 SampleWorkloadController 함수를 호출하고 관련 상태 변수를 전달합니다.
CRUD 작업을 지원하기 위해 생성/로드된 항목의 상태와 페이로드 변수의 샘플 구현이 workspaceObjectId 함께 저장 artifactItem 됩니다.

API를 사용하는 notification.open() 예제:

상태:

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

UI:

제목:

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

보내기 단추:

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

처리기:

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

컨트롤러:

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

CRUD 작업

프런트 엔드 전용 개발 시나리오는 쉽게 지원되지만 전체 엔드 투 엔드 개발자 환경에는 기존 워크로드 항목을 저장, 읽기 및 편집해야 합니다. 백 엔드 구현 가이드에서는 백 엔드 쪽을 설정하고 사용하는 방법을 자세히 설명합니다.

백 엔드가 실행 Org.WorkloadSample.SampleWorkloadItem 되고 형식이 Fabric에 등록되면 이 형식에 대해 CRUD 작업을 수행할 수 있습니다. 다음 작업은 ItemCrud API를 통해 노출됩니다.

CREATE

워크로드 항목을 처음 저장할 때 구현되는 샘플 호출 create:

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

샘플 구현에서는 생성된 항목을 내부에 저장합니다 artifactItem. 항목은 현재 선택한 작업 영역 아래에 만들어집니다. 따라서 백 엔드 문서에 자세히 설명된 대로 백 엔드 구성으로 구성된 용량에 작업 영역을 할당해야 합니다. 호환되지 않는 작업 영역에서 항목을 만들려는 시도가 실패합니다.

백 엔드의 콜백은 onCreateFabricItem CREATE 호출을 차단합니다. 오류가 발생하면 작업이 실패하고 Fabric에서 항목이 만들어지지 않습니다. 백 엔드의 디버깅/TSG 설명서를 참조하세요.
현재 저장된 항목은 작업 영역에 자동으로 표시되지 않습니다. 페이지 새로 고침이 필요합니다.

GET

작업 영역 보기에서 기존 샘플 워크로드 항목을 선택하면 Fabric은 프런트 엔드 매니페스트의 -->editor-->path--에 artifacts정의된 경로로 이동합니다.

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

호출 itemCrud.getItem하면 데이터가 워크로드 백 엔드의 데이터와 함께 Fabric의 백 엔드에서 로드되고 열린 GUI의 개체에 artifactItem 로드됩니다.

작업 영역에서 기존 항목을 여는 스크린샷

UPDATE

를 사용하여 기존 항목을 itemCrud.updateItem업데이트했습니다. 워크로드 페이로드 자체는 워크로드 백 엔드에 의해 업데이트되지만 패브릭에서는 항목 lastModifiedTime 만 변경됩니다.

DELETE

패브릭의 작업 영역 보기(모든 항목에 사용할 수 있는 일반 작업) 또는 워크로드에서 명시적으로 호출하여 삭제 작업을 호출합니다itemCrud.deleteItem. 두 호출 모두 워크로드 백 엔드의 onDeleteItem 콜백을 통과합니다.

인증

샘플 워크로드 편집기에서 인증 섹션으로 이동할 수 있는 섹션이 있습니다. 인증 API를 사용하기 전에 Entra 앱 Microsoft Entra ID를 구성합니다. 또한 env.dev 파일이 정확하게 구성되어 있는지 확인합니다. 자세한 내용은 다음을 참조하세요. 워크로드 로컬 매니페스트 구성 및 애플리케이션에 대한 토큰 획득

4단계: 디버그

작업자 및 UI iFrame을 보려면 브라우저의 DevTools(F12)의 원본 탭을 엽니다.

VS Code의 디버깅 파일 스크린샷

작업자 iFrame에 중단점을 배치하고 들어오는 작업의 기본 switch 을 볼 수 있습니다. UI iFrame(예: 내부 SampleWorkloadEditor코드)을 디버그할 수도 있습니다.

Fluent UI 컨트롤

UX 워크로드는 패브릭과 시각적 일관성 및 개발 용이성을 위해 Fluent UI 컨트롤을 사용합니다. 샘플 워크로드에서는 가장 일반적인 컨트롤을 사용하는 방법의 예를 제공합니다. 자세한 내용은 Fluent UI 페이지에서 찾을 수 있습니다.

프런트 엔드 매니페스트 사용자 지정

프런트 엔드 매니페스트는 제품 모양, 이름, 시각적 자산, 사용 가능한 작업 등 워크로드의 프런트 엔드 측면을 설명합니다. 패브릭과 워크로드 간의 주요 접촉 지점입니다. 샘플 워크로드의 경우 매니페스트는 개발자 모드에서 패브릭으로 로드되고, 매니페스트의 다양한 섹션, 정의 및 예제가 프런트 엔드 매니페스트 파일에 표시됩니다. 매니페스트 항목의 변경 내용, 다양한 작업의 연결 및 시각적 자산 업데이트는 페이지를 새로 고친 후 실시간으로 표시됩니다.

클라이언트 SDK - 지원되는 API

클라이언트 SDK 설명서는 @ms-fabric/workload-client 패키지에 있습니다.

지원되는 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

다음을 통해 공유

패브릭 워크로드 개발 키트 프런트 엔드(미리 보기)

필수 조건

1단계: 패브릭에서 워크로드 개발 기능 사용

2단계: 프런트 엔드 설정

사용 예

3단계: 코드 살펴보기

bootstrap()

index.worker

index.ui

개발 흐름

CRUD 작업

CREATE

GET

UPDATE

DELETE

인증

4단계: 디버그

Fluent UI 컨트롤

프런트 엔드 매니페스트 사용자 지정

클라이언트 SDK - 지원되는 API

피드백

추가 리소스

다음을 통해 공유

패브릭 워크로드 개발 키트 프런트 엔드(미리 보기)

필수 조건

1단계: 패브릭에서 워크로드 개발 기능 사용

2단계: 프런트 엔드 설정

사용 예

3단계: 코드 살펴보기

bootstrap()

index.worker

index.ui

개발 흐름

CRUD 작업

CREATE

GET

UPDATE

DELETE

인증

4단계: 디버그

Fluent UI 컨트롤

프런트 엔드 매니페스트 사용자 지정

클라이언트 SDK - 지원되는 API

관련 콘텐츠

피드백

추가 리소스