Połącz Fabric Apps z danymi usługi Fabric

Konektory zapewniają typowy dostęp z aplikacji Fabric do danych w innych elementach Fabric. Użyj konektora do zapytań do domu nad jeziorem, magazynu, bazy danych SQL w Fabric lub modelu semantycznego, bez konieczności konfigurowania osobnej usługi danych.

Obsługiwane łączniki

Wybierz złącze na podstawie elementu Fabric i operacji, których potrzebuje Twoja aplikacja:

produkt tekstylny Typ łącznika Obsługiwane operacje
Punkt końcowy analizy SQL usługi Lakehouse fabric-sqlanalytics read
warehouse fabric-warehouse read, create, updatei delete
Baza danych SQL na platformie Fabric fabric-sqldatabase read, create, updatei delete
Model semantyczny fabric-semanticmodel executeQuery

Dla magazynu i bazy danych SQL w Fabric connectorach konfiguruj tylko operacje, których potrzebuje Twoja aplikacja. Konektor lakehouse jest tylko do odczytu.

Wymagania wstępne

  • Projekt Fabric Apps utworzony za pomocą npm create @microsoft/rayfin@latest lub zainicjowany przy użyciu npx rayfin init.
  • Przestrzeń robocza Fabric, która zawiera przedmiot, do którego chcesz się połączyć.
  • Uprawnienia do dostępu do przestrzeni roboczej i elementu źródłowego.
  • Identyfikator obszaru roboczego i identyfikator elementu, które można znaleźć w adresie URL usługi Fabric lub za pomocą polecenia wyszukiwania łącznika.

Znajdź element usługi Fabric

Użyj connector search, aby wyświetlić elementy określonego typu w przestrzeni roboczej. Poniższy przykład przedstawia magazyny:

npx rayfin connector search --workspace-id <workspace-id> --type fabric-warehouse --json

Zastąp <workspace-id> identyfikatorem obszaru roboczego Fabric. Aby wyszukać inny wspierany element, zmień jego wartość --type . Możesz też dodać filtr nazw:

npx rayfin connector search "sales" --workspace-id <workspace-id> --type fabric-warehouse --json

Skopiuj ID przedmiotu z wyników wyszukiwania.

Dodawanie łącznika

Uruchamiaj connector add od korzenia swojego projektu Fabric Apps. Poniższy przykład dodaje złącze magazynowe tylko do odczytu o nazwie:inventory

npx rayfin connector add --type fabric-warehouse --workspace-id <workspace-id> --item-id <warehouse-item-id> --name inventory --operations read

Użyj odpowiedniego typu i operacji złącza dla innych elementów Fabric:

# Lakehouse SQL analytics endpoint
npx rayfin connector add --type fabric-sqlanalytics --workspace-id <workspace-id> --item-id <lakehouse-item-id> --name analytics --operations read

# SQL database in Fabric
npx rayfin connector add --type fabric-sqldatabase --workspace-id <workspace-id> --item-id <sql-database-item-id> --name operational --operations read

# Semantic model
npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

Polecenie:

  • Dodaje złącze do sekcji najwyższego poziomu connectors w rayfin/rayfin.yml.
  • Tworzy pliki łącznika w katalogu rayfin/connectors/<connector-name>/.
  • Wyświetla polecenie npm install dopasowane do wersji wymaganych pakietów konektorów.

Uruchom dokładne polecenie instalacyjne wydrukowane przez CLI. Dzięki temu pakiety konektorów pozostają zgodne z wersją Rayfin CLI.

Note

Odkrywanie schematów to najlepszy wysiłek. Złącze można dodać nawet jeśli odkrywanie nie zostanie zakończone. Jeśli CLI wyświetla ostrzeżenie o wykrywaniu, rozwiąż je przed definiowaniem jednostek z wygenerowanego metadata.json pliku.

Wygenerowana konfiguracja wykorzystuje uwierzytelnianie delegowane. Konfiguracja modelu magazynowego i semantycznego przypomina następujący przykład:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: "<workspace-id>"
      itemId: "<warehouse-item-id>"
    auth:
      type: delegated
    operations:
      - name: read

  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

Zachowaj wartość modelu version semantycznego, którą generuje CLI.

Konfiguruj konektor encji

Łączniki dla rozwiązań Lakehouse, hurtowni danych i baz danych SQL udostępniają wybrane tabele źródłowe jako typowane encje. Użyj wygenerowanego metadata.json pliku, aby zdefiniować tylko tabele i kolumny, których potrzebuje Twoja aplikacja.

Poniższy przykład zakłada, że wybrany magazyn zawiera tabelę dbo.Order z nazwanym kluczem OrderID pierwotnym liczbowym oraz kolumną tekstową o nazwie customerEmail. Zamień te ilustracyjne nazwy i typy na wartości z wygenerowanych przez siebie metadanych.

Important

Nie wyciągaj klucza głównego z nazwy kolumny. Jeśli tabela źródłowa nie ma klucza, pomiń primaryKey. Encje bez klucza nie obsługują operacji, które odwołują się do wiersza za pomocą klucza.

Stwórz byt:

// rayfin/connectors/inventory/Order.ts
import { entity, int, text, role } from '@microsoft/rayfin-core';
import { Source } from '@microsoft/rayfin-connectors';

@role('authenticated', ['read'])
@entity()
export class Order extends Source({
  schema: 'dbo',
  table: 'Order',
  primaryKey: ['orderId'],
}) {
  @int({ column: 'OrderID' }) orderId!: number;
  @text() customerEmail!: string;
}

Następnie rejestruje jednostkę w schemacie łącznika:

// rayfin/connectors/inventory/schema.ts
import type { GraphQLBackedConnector } from '@microsoft/rayfin-connector-fabric-graphql';
import type { ConnectorConfig } from '@microsoft/rayfin-connectors';
import { Order } from './Order.js';

export { Order } from './Order.js';

export const connectorConfig = {
  connector: 'fabric-warehouse',
  operations: ['read'],
  entities: { Order },
} as const satisfies ConnectorConfig;

export type InventorySchema = GraphQLBackedConnector<
  { Order: typeof Order },
  typeof connectorConfig
>;

Utrzymuj spójność nazwy złącza, właściwości schematu i nazwy konfiguracji klienta.

Konfiguruj klienta konektorów

Dodaj schematy łączników do ConnectorsRayfinClient. Konektory modeli semantycznych również wymagają środowiska uruchomieniowego fabricSemanticModel():

// src/lib/connectors.ts
import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';

import {
  connectorConfig as inventoryConfig,
  type InventorySchema,
} from '../../rayfin/connectors/inventory/schema.js';
import {
  connectorConfig as salesModelConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  inventory: InventorySchema;
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      inventory: inventoryConfig,
      salesModel: salesModelConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

Użyj adresu URL API i klucza publikowalnego z projektu Fabric Apps. Zachowaj istniejący przepływ logowania w aplikacji. Utworzenie klienta nie powoduje zalogowania użytkownika.

Zapytanie o dane powiązane

Po zalogowaniu użytkownika uzyskaj dostęp do łącznika encji przez jego nazwę i podmiot:

const orders = await client.connectors.inventory.Order
  .select(['orderId', 'customerEmail'])
  .first(20)
  .execute();

Wybierz kolumny jawnie i ogranicz liczbę zwróconych wierszy.

Dla modelu semantycznego przesłaj zapytanie DAX z :executeQuery

const result = await client.connectors.salesModel.executeQuery({
  query: 'EVALUATE TOPN(10, Sales)',
});

if (result.status === 'success') {
  console.log(result.table.columns, result.table.rows);
} else {
  console.error(result.error.category, result.error.message);
}

Zastąp Sales tabelą w modelu semantycznym. Sprawdź zwrócony stan przed użyciem wyniku.

Dostęp do złącza zabezpieczonego

Używaj tych kontrolek razem:

  • Ogranicz operacje łącznika w rayfin.yml do działań wymaganych przez aplikację.
  • Dodaj @role deklaracje do jednostek łączących, aby kontrolować, którzy zalogowani użytkownicy mogą wykonywać każdą operację.
  • Dodaj zasady na poziomie wierszy lub reguły uwzględniania i wykluczania pól, gdy użytkownicy potrzebują dostępu tylko do części encji.
  • Zachowaj włączone uwierzytelnianie delegowane, aby żądania łącznikowe korzystały z dostępu zalogowanego użytkownika.

Typy TypeScript po stronie klienta poprawiają bezpieczeństwo rozwoju, ale nie stanowią granicy autoryzacji. Wymusz dostęp w konfiguracji konektora i rolach podmiotów.

Wdrażanie łącznika

Wdrożenie aplikacji i konfiguracji złącza:

npx rayfin up

Przetestuj wdrożoną aplikację z użytkownikiem, który ma oczekiwane uprawnienia zarówno do aplikacji Fabric, jak i do połączonego elementu.

Treści powiązane

  • Ostatnia aktualizacja o