Connectez les applications Fabric aux données Fabric

Les connecteurs fournissent un accès typé, à partir d’une application Fabric, aux données stockées dans d’autres éléments Fabric. Utilisez un connecteur pour interroger un lakehouse, un entrepôt, une base de données SQL dans Fabric ou un modèle sémantique sans configurer un service de données séparé.

Connecteurs pris en charge

Choisissez un connecteur basé sur l’élément Fabric et les opérations dont votre application a besoin :

Article en tissu Type de connecteur Opérations prises en charge
Point de terminaison pour l'analyse SQL du Lakehouse fabric-sqlanalytics read
warehouse fabric-warehouse read, create, update et delete
Base de données SQL dans Fabric fabric-sqldatabase read, create, update et delete
Modèle sémantique fabric-semanticmodel executeQuery

Pour l’entrepôt et la base de données SQL dans les connecteurs Fabric, configurez uniquement les opérations dont votre application a besoin. Le connecteur de la maison du lac est en lecture seule.

Prerequisites

  • Projet Fabric Apps créé avec npm create @microsoft/rayfin@latest ou initialisé avec npx rayfin init.
  • Un espace de travail Fabric qui contient l’élément auquel vous souhaitez vous connecter.
  • Permission d’accéder à l’espace de travail et à l’élément source.
  • L’ID de l’espace de travail et l’ID de l’élément, que vous pouvez trouver dans l’URL Fabric ou en utilisant la commande de recherche de connecteur.

Trouver un élément Fabric

Utilisez connector search pour lister des éléments d’un type spécifique dans un espace de travail. L’exemple suivant liste les entrepôts :

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

Remplacez <workspace-id> par votre ID d’espace de travail Fabric. Pour chercher un autre objet supporté, modifiez la --type valeur. Vous pouvez aussi ajouter un filtre de noms :

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

Copiez l’identifiant de l’élément depuis le résultat de recherche.

Ajouter un connecteur

Exécutez connector add à la racine de votre projet Fabric Apps. L’exemple suivant ajoute un connecteur d’entrepôt en lecture seule nommé inventory:

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

Utilisez le type de connecteur et les opérations correspondants pour d’autres éléments 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

Commande :

  • Ajoute le connecteur à la section de niveau supérieur connectors dans rayfin/rayfin.yml.
  • Crée les fichiers du connecteur sous rayfin/connectors/<connector-name>/.
  • Imprime une commande correspondante npm install à la version pour les paquets de connecteurs requis.

Exécutez exactement la commande d’installation imprimée par la CLI. Cela permet de maintenir les paquets de connecteurs synchronisés avec votre version de Rayfin CLI.

Note

La découverte de schéma est la meilleure tentative. Le connecteur peut être ajouté même si le processus de découverte n’aboutit pas. Si la CLI affiche un avertissement de découverte, résolvez-le avant de définir des entités à partir du fichier généré metadata.json .

La configuration générée utilise une authentification déléguée. Une configuration d’entrepôt et de modèle sémantique ressemble à l’exemple suivant :

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

Conservez la valeur du modèle version sémantique générée par la LI.

Configurez un connecteur d’entité

Les connecteurs Lakehouse, Warehouse et SQL Database exposent certaines tables sources sous forme d’entités typées. Utilisez le fichier généré metadata.json pour définir uniquement les tables et colonnes dont votre application a besoin.

L’exemple suivant suppose que l’entrepôt sélectionné contient une dbo.Order table avec une clé primaire entière nommée OrderID et une colonne de texte nommée customerEmail. Remplacez ces noms et types illustratifs par des valeurs issues de vos métadonnées générées.

Important

N’inférez pas une clé primaire à partir d’un nom de colonne. Si une table source n’a pas de clé, omettez primaryKey. Les entités sans clé ne prennent pas en charge les opérations qui ciblent une ligne à l’aide d’une clé.

Créez l’entité :

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

Ensuite, enregistrez l’entité dans le schéma du connecteur :

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

Gardez cohérents le nom du connecteur, la propriété du schéma et le nom de configuration client.

Configurez le client des connecteurs

Ajoutez les schémas de connecteurs à ConnectorsRayfinClient. Les connecteurs de modèles sémantiques nécessitent également le temps d’exécution 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(),
  }
);

Utilisez l’URL de l’API et la clé publiable de votre projet Fabric Apps. Conservez le flux de connexion existant de l’application. La création du client n’authentifie pas un utilisateur.

Requête des données connectées

Après la connexion, l’utilisateur accéde à un connecteur d’entité via son nom et son entité :

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

Sélectionnez explicitement les colonnes et limitez le nombre de lignes retournées.

Pour un modèle sémantique, soumettez une requête DAX avec 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);
}

Remplacez-le Sales par une table dans votre modèle sémantique. Vérifiez l’état renvoyé avant d’utiliser le résultat.

Accès sécurisé par le connecteur

Utilisez ces commandes ensemble :

  • Limitez les opérations du connecteur dans rayfin.yml aux actions dont l’application a besoin.
  • Ajoutez des déclarations @role aux entités de connecteurs pour contrôler quels utilisateurs connectés peuvent effectuer chaque opération.
  • Ajouter des politiques au niveau des lignes ou des règles d’inclusion et d’exclusion de champs lorsque les utilisateurs doivent accéder uniquement à une partie d’une entité.
  • Gardez l’authentification déléguée activée afin que les requêtes de connecteur utilisent l’accès de l’utilisateur connecté.

Les types TypeScript côté client améliorent la sécurité du développement, mais ils ne constituent pas une limite d’autorisation. Appliquez les contrôles d’accès au niveau de la configuration du connecteur et des rôles des entités.

Déployer le connecteur

Déploie l’application et la configuration du connecteur :

npx rayfin up

Testez l’application déployée avec un utilisateur qui dispose des autorisations attendues à la fois sur l’application Fabric et sur l’élément connecté.

Contenu connexe

  • Dernière mise à jour :