Verbind Fabric Apps met Fabric-data

Connectors bieden getypte toegang vanuit een Fabric-app tot data in andere Fabric-items. Gebruik een connector om een lakehouse, warehouse, SQL-database in Fabric of semantisch model te bevragen zonder een aparte dataservice te configureren.

Ondersteunde connectoren

Kies een connector op basis van het Fabric-item en de bewerkingen die je app nodig heeft:

Stofitem Verbindingslijntype Ondersteunde bewerkingen
Lakehouse SQL-analyse-eindpunt fabric-sqlanalytics read
warehouse fabric-warehouse read, create, update en delete
Een SQL-database in Fabric fabric-sqldatabase read, create, update en delete
Semantisch model fabric-semanticmodel executeQuery

Voor warehouse- en SQL-database-in-Fabric-connectoren configureer je alleen de bewerkingen die je app nodig heeft. De lakehouse-connector is alleen-leesbaar.

Prerequisites

  • Een Fabric Apps-project gemaakt met npm create @microsoft/rayfin@latest of geïnitialiseerd met npx rayfin init.
  • Een Fabric-werkruimte die het item bevat waar je mee wilt verbinden.
  • Toestemming om toegang te krijgen tot de werkruimte en het bron-item.
  • De werkruimte-ID en item-ID, die je kunt vinden in de Fabric-URL of door het connectorzoekcommando te gebruiken.

Vind een Fabric-item

Gebruik connector search om items van een specifiek type in een werkruimte weer te geven. Het volgende voorbeeld geeft magazijnen weer:

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

Vervang <workspace-id> door de ID van uw Fabric-werkruimte. Om een ander ondersteund item te zoeken, verander je de --type waarde. Je kunt ook een naamfilter toevoegen:

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

Kopieer de item-ID uit het zoekresultaat.

Een connector toevoegen

Voer connector add uit vanuit de hoofdmap van je Fabric Apps-project. Het volgende voorbeeld voegt een alleen-lezen warehouse-connector toe met de naam inventory:

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

Gebruik het bijbehorende connectortype en de bewerkingen voor andere Fabric-items:

# 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

De opdracht:

  • Voegt de connector toe aan de bovenste sectie connectors in rayfin/rayfin.yml.
  • Maakt de connectorbestanden aan onder rayfin/connectors/<connector-name>/.
  • Drukt een op de versie afgestemde npm install opdracht af voor de vereiste connectorpakketten.

Voer exact het installatiecommando uit dat door de CLI is afgedrukt. Dit houdt de connectorpakketten uitgelijnd met je Rayfin CLI-versie.

Opmerking

Schema-ontdekking is een beste inspanning. De connector kan worden toegevoegd, zelfs als de detectie niet wordt afgerond. Als de CLI een ontdekkingswaarschuwing vertoont, los deze dan op voordat je entiteiten definieert uit het gegenereerde metadata.json bestand.

De gegenereerde configuratie gebruikt gedelegeerde authenticatie. Een warehouse- en semantisch modelconfiguratie lijkt op het volgende voorbeeld:

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

Houd de waarde van het semantische model version die de CLI genereert.

Configureer een entiteitsconnector

Lakehouse-, warehouse- en SQL-databaseconnectoren stellen geselecteerde brontabellen bloot als getypte entiteiten. Gebruik het gegenereerde metadata.json bestand om alleen de tabellen en kolommen te definiëren die je app nodig heeft.

Het volgende voorbeeld gaat ervan uit dat het geselecteerde warehouse een dbo.Order tabel bevat met een gehele primaire sleutel genaamd OrderID en een tekstkolom genaamd customerEmail. Vervang deze illustratieve namen en types door waarden uit je gegenereerde metadata.

Important

Leid geen primaire sleutel af uit een kolomnaam. Als een brontabel geen sleutel heeft, laat u primaryKeyweg Keyless entities ondersteunen geen bewerkingen die een rij per sleutel adresseren.

Creëer de entiteit:

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

Registreer vervolgens de entiteit in het connectorschema:

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

Houd de connectornaam, schema-eigenschap en clientconfiguratienaam consistent.

De Connectors-client configureren

Voeg de connectorschema's toe aan ConnectorsRayfinClient. Connectoren voor semantische modellen vereisen ook de fabricSemanticModel() runtime:

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

Gebruik de API-URL en publiceerbare sleutel van je Fabric Apps-project. Houd de bestaande inlogflow van de app behouden. Bij het maken van de client wordt een gebruiker niet aangemeld.

Zoek verbonden data op

Nadat de gebruiker is ingelogd, benader je een entiteitsconnector via zijn naam en entiteit:

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

Selecteer kolommen expliciet en beperk het aantal teruggestuurde rijen.

Voor een semantisch model dien je een DAX-query in met 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);
}

Vervang Sales door een tabel in je semantisch model. Controleer de geretourneerde status voordat je het resultaat gebruikt.

Beveiligde toegang tot de connector

Gebruik deze bedieningselementen samen:

  • Beperk de bewerkingen van de connector in rayfin.yml tot de acties die de app nodig heeft.
  • Voeg declaraties toe @role aan connectorentiteiten om te bepalen welke ingelogde gebruikers elke bewerking kunnen uitvoeren.
  • Voeg beleid op rijniveau of regels voor het opnemen en uitsluiten van velden toe wanneer gebruikers slechts toegang tot een deel van een entiteit nodig hebben.
  • Houd gedelegeerde authenticatie ingeschakeld zodat connectorverzoeken de toegang van de ingelogde gebruiker gebruiken.

Client-side TypeScript-typen verbeteren de ontwikkelingsveiligheid, maar vormen geen autorisatiegrens. Dwing toegang af in de connectorconfiguratie en entiteitsrollen.

De connector implementeren

Rol de app en connectorconfiguratie uit:

npx rayfin up

Test de geïmplementeerde app met een gebruiker die de verwachte rechten heeft op zowel de Fabric-app als het aangesloten item.

Verwante onderwerpen

  • Laatst bijgewerkt om