Koppla Fabric Apps till Fabric-data

Connectors ger typad åtkomst från en Fabric-app till data i andra Fabric-objekt. Använd en anslutningsapp för att köra frågor mot ett lakehouse, ett datalager, en SQL-databas eller en semantisk modell i Fabric utan att konfigurera en separat datatjänst.

Stödda kopplingar

Välj en koppling baserat på den Fabric-produkt och de operationer som din app behöver:

Tygföremål	Anslutningstyp	Åtgärder som stöds
Lakehouse SQL-analysslutpunkt	fabric-sqlanalytics	read
warehouse	fabric-warehouse	read, create, updateoch delete
SQL-databasen i Fabric	fabric-sqldatabase	read, create, updateoch delete
Semantisk modell	fabric-semanticmodel	executeQuery

För lager- och SQL-databaser i Fabric-anslutningar, konfigurera endast de operationer som din app behöver. Lakehouse-anslutningen är skrivskyddad.

Förutsättningar

• Ett Fabric Apps-projekt som skapats med npm create @microsoft/rayfin@latest eller initierats med npx rayfin init.
• Ett Fabric-arbetsområde som innehåller det föremål du vill koppla upp dig på.
• Behörighet att komma åt arbetsområdet och källobjektet.
• Workspace-ID och objekt-ID, som du kan hitta i Fabric-URL:en eller genom att använda connector-sökningskommandot.

Hitta en Fabric-artikel

Använd connector search för att lista objekt av en specifik typ i en arbetsyta. Följande exempel listar lager:

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

Ersätt <workspace-id> med ditt Fabric arbetsyte-ID. För att söka efter ett annat stödd objekt, ändra värdet --type . Du kan också lägga till ett namnfilter:

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

Kopiera artikel-ID:t från sökresultatet.

Lägg till en anslutning

Kör connector add från roten av ditt Fabric Apps-projekt. Följande exempel lägger till en skrivskyddad lageranslutning med namnet inventory:

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

Använd motsvarande kontakttyp och operationer för andra Fabric-artiklar:

# 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

Kommandot:

• Lägger till kontakten till den översta sektionen connectors i rayfin/rayfin.yml.
• Skapar anslutningsfilerna under rayfin/connectors/<connector-name>/.
• Skriver ut ett versionsmatchat npm install kommando för de nödvändiga kontaktpaketen.

Kör exakt det installationskommando som CLI:n skriver ut. Detta håller kontaktpaketen i linje med din Rayfin CLI-version.

Anmärkning

Schemaupptäckt är bästa ansträngning. Kontakten kan läggas till även om upptäckten inte slutförs. Om CLI:n visar en upptäcktsvarning, lös den innan du definierar entiteter från den genererade metadata.json filen.

Den genererade konfigurationen använder delegerad autentisering. En lager- och semantisk modellkonfiguration liknar följande exempel:

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

Behåll det semantiska modellvärdet version som CLI:n genererar.

Konfigurera en entitetsanslutning

Lakehouse-, lager- och SQL-databaskopplingar exponerar utvalda källtabeller som typade enheter. Använd den genererade metadata.json filen för att definiera endast de tabeller och kolumner som din app behöver.

Följande exempel antar att det valda lagret innehåller en dbo.Order tabell med en heltalsprimärnyckel som OrderID heter och en textkolumn med namnet customerEmail. Ersätt dessa illustrativa namn och typer med värden från din genererade metadata.

Important

Dra inte slutsatser om en primärnyckel från ett kolumnnamn. Om en källtabell inte har en nyckel, utelämna primaryKey. Nyckellösa enheter stödjer inte operationer som adresserar en rad för nyckel.

Skapa entiteten:

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

Registrera sedan entiteten i kopplingsschemat:

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

Håll kontaktens namn, schema-egenskap och klientkonfigurationsnamn konsekventa.

Konfigurera klienten för anslutningar

Lägg till anslutningsscheman till ConnectorsRayfinClient. Anslutningsprogram för semantiska modeller kräver också körtiden 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(),
  }
);

Använd API-URL:en och publicierbar nyckel från ditt Fabric Apps-projekt. Behåll appens befintliga inloggningsflöde. Att skapa klienten loggar inte in en användare.

Fråga om sammanhängande data

Efter att användaren loggat in, gå åt en entitetskopplare via dess namn och entitet:

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

Välj kolumner explicit och begränsa antalet returnerade rader.

För en semantisk modell, skicka in en DAX-fråga 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);
}

Ersätt Sales med en tabell i din semantiska modell. Kontrollera den returnerade statusen innan du använder resultatet.

Säker anslutningsåtkomst

Använd dessa kontroller tillsammans:

• Begränsa anslutningens åtgärder i rayfin.yml till de åtgärder som appen behöver.
• Lägg till @role deklarationer till kopplingsenheter för att kontrollera vilka inloggade användare som kan utföra varje operation.
• Lägg till radpolicyer eller fält inkluderar och exkluderar regler när användare behöver åtkomst till endast en del av en enhet.
• Ha delegerad autentisering aktiverad så att anslutningsförfrågningar använder den inloggade användarens åtkomst.

Typtyper på klientsidan förbättrar utvecklingssäkerheten, men de är inte en auktorisationsgräns. Upprätthåll åtkomst i anslutningskonfigurationen och entitetsrollerna.

Distribuera anslutningen

Distribuera appen och anslutningskonfigurationen:

npx rayfin up

Testa den distribuerade appen med en användare som har förväntade behörigheter både i Fabric-appen och på det anslutna objektet.

Relaterat innehåll

• Skapa en app kopplad till en semantisk modell
• Definiera datamodeller
• Definiera databehörigheter
• Autentisering för Fabric-appar
• Distribuera en Fabric-app till Fabric
• Referens för Rayfin CLI