Koble Fabric Apps til Fabric-data

Koblinger gir skrevet tilgang fra en Fabric-app til data i andre Fabric-elementer. Bruk en kobling for å spørre et lakehouse, lager, SQL-database i Fabric eller semantisk modell uten å konfigurere en separat datatjeneste.

Støttede koblinger

Velg en kobling basert på Fabric-elementet og operasjonene som appen din trenger:

Stoff vare	Koblingstype	Støttede operasjoner
Endepunkt for SQL-analyse i Lakehouse	fabric-sqlanalytics	read
lager	fabric-warehouse	read, create, updateog delete
SQL-database i Fabric	fabric-sqldatabase	read, create, updateog delete
Semantisk modell	fabric-semanticmodel	executeQuery

For lager- og SQL-databaser i Fabric-tilkoblinger, konfigurer kun de operasjonene appen din trenger. Lakehouse-kontakten er skrivebeskyttet.

Forutsetninger

• Et Fabric Apps-prosjekt opprettet med npm create @microsoft/rayfin@latest eller initialisert med npx rayfin init.
• Et Fabric-arbeidsområde som inneholder gjenstanden du ønsker å koble til.
• Tillatelse til å få tilgang til arbeidsområdet og kildeelementet.
• Arbeidsområdets ID og gjenstands-ID, som du kan finne i Fabric-URL-en eller ved å bruke koblingssøkekommandoen.

Finn et Fabric-produkt

Bruk connector search den til å liste opp elementer av en bestemt type i et arbeidsområde. Følgende eksempel viser lagre:

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

Erstatt <workspace-id> med ID-en for Fabric-arbeidsområdet. For å søke etter et annet støttet element, endre --type verdien. Du kan også legge til et navnefilter:

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

Kopier vare-ID-en fra søkeresultatet.

Legge til en kobling

Kjør connector add fra roten av Fabric Apps-prosjektet ditt. Følgende eksempel legger til en skrivebeskyttet lagerkobling kalt inventory:

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

Bruk tilsvarende kontakttype og operasjoner for andre Fabric-elementer:

# 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

Kommandoen:

• Legger til kontakten i toppnivådelen connectors i rayfin/rayfin.yml.
• Oppretter koblingsfilene under rayfin/connectors/<connector-name>/.
• Skriver ut en versjonstilpasset npm install kommando for de nødvendige koblingspakkene.

Kjør nøyaktig den installasjonskommandoen som er skrevet ut av CLI-en. Dette holder koblingspakkene på linje med din Rayfin CLI-versjon.

Notat

Skjemaoppdagelse er beste innsats. Koblingen kan legges til selv om oppdagelsen ikke fullføres. Hvis CLI-en viser en oppdagelsesadvarsel, løs den før du definerer enheter fra den genererte metadata.json filen.

Den genererte konfigurasjonen bruker delegert autentisering. En lager- og semantisk modellkonfigurasjon ligner følgende eksempel:

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

Behold den semantiske modellverdien version som CLI-en genererer.

Konfigurer en entitetskobling

Lakehouse-, warehouse- og SQL-databasekoblinger eksponerer utvalgte kildetabeller som typede enheter. Bruk den genererte metadata.json filen til å definere kun tabellene og kolonnene som appen din trenger.

Følgende eksempel antar at det valgte lageret inneholder en dbo.Order tabell med en heltallsprimærnøkkel navngitt OrderID og en tekstkolonne kalt customerEmail. Erstatt disse illustrative navnene og typene med verdier fra dine genererte metadata.

Important

Ikke utlede en primærnøkkel fra et kolonnenavn. Hvis en kildetabell ikke har en nøkkel, utelas primaryKey. Nøkkelløse enheter støtter ikke operasjoner som adresserer rad for nøkkel.

Opprett enheten:

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

Registrer deretter enheten i koblingsskjemaet:

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

Hold tilkoblingsnavnet, skjema-egenskapen og klientkonfigurasjonsnavnet konsistent.

Konfigurer connectors-klienten

Legg til koblingsskjemaene til .ConnectorsRayfinClient Semantiske modellkontakter krever fabricSemanticModel() også kjøretiden:

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

Bruk API-URL-en og publiserbar nøkkel fra Fabric Apps-prosjektet ditt. Behold appens eksisterende innloggingsflyt. Å opprette klienten logger ikke inn en bruker.

Søk i sammenkoblede data

Etter at brukeren logger inn, tilgang til en entitetskontakt via navn og entitet:

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

Velg kolonner eksplisitt og begrens antall returnerte rader.

For en semantisk modell, send inn en DAX-forespørsel med 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);
}

Erstatt Sales med en tabell i din semantiske modell. Sjekk returstatusen før du bruker resultatet.

Sikker tilkoblingstilgang

Bruk disse kontrollene sammen:

• Begrens koblingens operasjoner til rayfin.yml de handlingene appen trenger.
• Legg til @role deklarasjoner til koblingsenheter for å kontrollere hvilke innloggede brukere som kan utføre hver operasjon.
• Legg til radpolicyer eller felt-inkluder og ekskluderer regler når brukere trenger tilgang til bare deler av en enhet.
• Hold delegert autentisering aktivert slik at tilkoblingsforespørsler bruker brukerens tilgang til den innloggede brukeren.

TypeScript-typer på klientsiden forbedrer utviklingssikkerheten, men de er ikke en autorisasjonsgrense. Håndhev tilgang i tilkoblingskonfigurasjonen og entitetsrollene.

Distribuer koblingen

Distribuer appens og tilkoblingskonfigurasjonen:

npx rayfin up

Test den distribuerte appen med en bruker som har forventede tillatelser både i Fabric-appen og på det tilkoblede produktet.

Relatert innhold

• Lag en app koblet til en semantisk modell
• Definer datamodeller
• Definer datatillatelser
• Autentisering for Fabric-apper
• Distribuer en Fabric-app til Fabric
• Rayfin CLI-referanse