Forbind Fabric Apps til Fabric-data

Connectors giver indtastet adgang fra en Fabric-app til data i andre Fabric-elementer. Brug en connector til at forespørge et lakehouse, lager, SQL-database i Fabric eller semantisk model uden at konfigurere en separat dataservice.

Understøttede stik

Vælg en connector baseret på det Fabric-element og de operationer, din app har brug for:

Stof vare Connectortype Understøttede handlinger
Sql Analytics-slutpunkt for Lakehouse fabric-sqlanalytics read
lager fabric-warehouse read, create, updateog delete
SQL-database i Fabric fabric-sqldatabase read, create, updateog delete
Semantisk model fabric-semanticmodel executeQuery

For lager- og SQL-databaser i Fabric-connectorer skal du kun konfigurere de operationer, som din app har brug for. Lakehouse-forbindelsen er skrivebeskyttet.

Forudsætninger

  • Et Fabric Apps-projekt oprettet med npm create @microsoft/rayfin@latest eller initialiseret med npx rayfin init.
  • Et Fabric-arbejdsområde, der indeholder det objekt, du ønsker at forbinde til.
  • Tilladelse til at få adgang til arbejdsområdet og kildeelementet.
  • Arbejdsområdets ID og item ID, som du kan finde i Fabric URL eller ved at bruge connector-søgekommandoen.

Find et Fabric-produkt

Brug connector search den til at liste elementer af en bestemt type i et arbejdsområde. Følgende eksempel viser lagre:

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

Erstat <workspace-id> med dit Fabric-arbejdsområde-id. For at søge efter et andet understøttet element, skal du ændre værdien --type . Du kan også tilføje et navnefilter:

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

Kopier vare-ID'et fra søgeresultatet.

Tilføj en forbindelse

Kør connector add fra roden af dit Fabric Apps-projekt. Følgende eksempel tilføjer en skrivebeskyttet lagerkonnektor med navnet inventory:

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

Brug den tilsvarende stiktype og -operationer til 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:

  • Tilføjer forbindelsen til topniveau-sektionen connectors i rayfin/rayfin.yml.
  • Opretter connector-filerne under rayfin/connectors/<connector-name>/.
  • Printer en versionsmatchet npm install kommando til de nødvendige stikpakker.

Kør den præcise installationskommando, som CLI'en printer. Dette holder connector-pakkerne i overensstemmelse med din Rayfin CLI-version.

Bemærk

Skemaopdagelse er bedste indsats. Forbindelsen kan tilføjes, selvom opdagelsen ikke gennemføres. Hvis CLI'en viser en discovery-advarsel, skal du løse den, før du definerer enheder fra den genererede metadata.json fil.

SQL-connectortyper (fabric-sqlanalytics, fabric-warehouse, og fabric-sqldatabase) fungerer som standard til applikationsautentificering i CLI 1.36.2. De tilgår kilden som app-identiteten, som i øjeblikket er ejeren af app-objektet. Du kan eksplicit vælge delegeret autentificering for at bruge hver indlogget opkalders kildetilladelser i stedet. Semantiske modeller understøtter kun delegeret autentificering.

En standard lager- og semantisk modelkonfiguration ligner:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: "<workspace-id>"
      itemId: "<warehouse-item-id>"
    auth:
      type: application
    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 modelværdi version , som CLI'en genererer.

Vælg kildeidentiteten

Måde Kildetilladelser Hvornår skal du bruge den?
application Giv appens identitetsadgang til kildeelementet og de nødvendige SQL-tilladelser. App-brugere har stadig brug for app-adgang og enhedstilladelser. SQL-connectorer, der eksponerer app-kontrolleret adgang til delte kildedata.
delegated Hver kalder skal have adgang til kildeelementet og tilladelse til den ønskede operation. Semantiske modelforespørgsler kræver kalderens relevante modeltilladelser, inklusive Build. Per-bruger kildeautorisation eller enhver semantisk model-connector.

For delegeret SQL-adgang i CLI 1.36.2, sæt auth.type: delegated den connector i rayfin/rayfin.yml før udrulning. CLI-versioner, hvis connector add --help eksponeringer --auth kan vælge den ved oprettelse:

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

Flaget --auth er ikke tilgængeligt i CLI 1.36.2; brug YAML-indstillingen med den udgivelse. Hvor flaget understøttes, accepterer application det eller delegated kun hvis stiktypen understøtter den tilstand. Konfigurer ikke applikationsautentificering til en semantisk model.

At ændre tilstanden giver ikke kildetilladelser. Udviklerens login-ind og skema-opdagelse bruger udviklerens adgang og beviser ikke, at den deployerede runtime-identitet kan tilgå kildekoden. Eksisterende deklarationer migreres ikke automatisk til den nye standard; hold auth.type det eksplicit. Efter at have tilføjet en connector igen, gennemgå den genererede tilstand før udrulning.

Konfigurér en entitetsconnector

Lakehouse-, lager- og SQL-databaseforbindelser eksponerer udvalgte kildetabeller som typede enheder. Brug den genererede metadata.json fil til kun at definere de tabeller og kolonner, som din app har brug for.

Det følgende eksempel antager, at det valgte lager indeholder en dbo.Order tabel med en heltals-primærnøgle navngivet OrderID og en tekstkolonne kaldet customerEmail. Erstat disse illustrative navne og typer med værdier fra dine genererede metadata.

Vigtig

Udled ikke en primærnøgle ud fra et kolonnenavn. Hvis en kildetabel ikke har en nøgle, udelades primaryKey. Keyless entities understøtter ikke operationer, der adresserer en række for nøgle.

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

Registrer derefter entiteten i connector-skemaet:

// 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 connectorens navn, skema-egenskab og klientkonfigurationsnavn ensartede.

Konfigurer connectors-klienten

Tilføj stikskemaerne til ConnectorsRayfinClient. Semantiske modelstik kræver fabricSemanticModel() også kø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(),
  }
);

Brug API-URL'en og den publicerbare nøgle fra dit Fabric Apps-projekt. Behold appens eksisterende login-flow. Oprettelse af klienten logger ikke ind som bruger.

Forespørg forbundne data

Efter brugeren har logget ind, skal du tilgå en entitetsforbindelse via dens navn og entitet:

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

Vælg kolonner eksplicit og begrænser antallet af returnerede rækker.

For en semantisk model, indsend en DAX-forespørgsel 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);
}

Erstat Sales med en tabel i din semantiske model. Tjek status på returneret, før du bruger resultatet.

Sikker forbindelsesadgang

Brug disse kontroller sammen:

  • Begræns connectorens operationer til rayfin.yml de handlinger, appen har brug for.
  • Tilføj @role deklarationer til connector-enheder for at kontrollere, hvilke indloggede brugere der kan udføre hver operation.
  • Tilføj rækkepolitikker eller felt-regler for inkluder og eksklusion, når brugere kun har brug for adgang til en del af en enhed.
  • Vælg kildeidentiteten med omhu. Med applikationsautentificering håndhæves adgang per bruger gennem app- og enhedstilladelser i stedet for at antage, at kildetilladelser kontrolleres for hver kalder. Ved delegeret autentificering skal du også verificere hver opkalders kildeadgang.

TypeScript-typer på klientsiden forbedrer udviklingssikkerheden, men de er ikke en autorisationsgrænse. Håndhæv adgang i connector-konfigurationen og entity-rollerne.

Installér connectoren

Udrul appen og connector-konfigurationen:

npx rayfin up

Test den deployerede app med de forventede app-brugere og runtime-kildeidentitet. For applikationsautentificering, verificér appens identitets kildetilladelser; for delegeret autentificering, verificér hver kalders kildetilladelser.

Relateret indhold

  • Sidst opdateret den