Σύνδεση εφαρμογών Fabric σε δεδομένα Fabric

Οι συνδέσεις παρέχουν πληκτρολογημένη πρόσβαση από μια εφαρμογή Fabric σε δεδομένα σε άλλα στοιχεία Fabric. Χρησιμοποιήστε μια σύνδεση για να υποβάλετε ερώτημα σε μια λίμνη, μια αποθήκη, μια βάση δεδομένων SQL στο Fabric ή ένα σημασιολογικό μοντέλο χωρίς να ρυθμίσετε τις παραμέτρους μιας ξεχωριστής υπηρεσίας δεδομένων.

Υποστηριζόμενες συνδέσεις

Επιλέξτε μια σύνδεση με βάση το στοιχείο Fabric και τις λειτουργίες που χρειάζεται η εφαρμογή σας:

Υφασμάτινο αντικείμενο	Τύπος σύνδεσης	Υποστηριζόμενες λειτουργίες
Τελικό σημείο ανάλυσης SQL Lakehouse	fabric-sqlanalytics	read
αποθήκη	fabric-warehouse	read, create, update, και delete
Βάση δεδομένων SQL στο Fabric	fabric-sqldatabase	read, create, update, και delete
Σημασιολογικό μοντέλο	fabric-semanticmodel	executeQuery

Για αποθήκη και βάση δεδομένων SQL σε συνδέσεις Fabric, ρυθμίστε μόνο τις λειτουργίες που χρειάζεται η εφαρμογή σας. Η σύνδεση lakehouse είναι μόνο για ανάγνωση.

Προαπαιτούμενα στοιχεία

• Ένα έργο Fabric Apps που δημιουργήθηκε με npm create @microsoft/rayfin@latest ή αρχικοποιήθηκε με npx rayfin init.
• Ένας χώρος εργασίας Fabric που περιέχει το στοιχείο στο οποίο θέλετε να συνδεθείτε.
• Δικαίωμα πρόσβασης στον χώρο εργασίας και στο στοιχείο προέλευσης.
• Το αναγνωριστικό χώρου εργασίας και το αναγνωριστικό στοιχείου, τα οποία μπορείτε να βρείτε στη διεύθυνση URL του Fabric ή χρησιμοποιώντας την εντολή αναζήτησης σύνδεσης.

Βρείτε ένα αντικείμενο Fabric

Χρησιμοποιείται για connector search τη λίστα στοιχείων συγκεκριμένου τύπου σε έναν χώρο εργασίας. Το παρακάτω παράδειγμα παραθέτει τις αποθήκες:

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

Αντικαταστήστε <workspace-id> το με το αναγνωριστικό χώρου εργασίας Fabric. Για να αναζητήσετε ένα άλλο υποστηριζόμενο στοιχείο, αλλάξτε την --type τιμή. Μπορείτε επίσης να προσθέσετε ένα φίλτρο ονόματος:

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

Αντιγράψτε το αναγνωριστικό στοιχείου από το αποτέλεσμα αναζήτησης.

Προσθήκη ενός συνδέσμου

Εκτελέστε connector add από τη ρίζα του έργου σας Fabric Apps. Το παρακάτω παράδειγμα προσθέτει μια σύνδεση αποθήκης μόνο για ανάγνωση με το όνομα inventory:

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

Χρησιμοποιήστε τον αντίστοιχο τύπο σύνδεσης και τις λειτουργίες για άλλα στοιχεία 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

Η εντολή:

• Προσθέτει τη γραμμή σύνδεσης στην ενότητα ανώτατου επιπέδου connectors στο rayfin/rayfin.yml.
• Δημιουργεί τα αρχεία σύνδεσης στην περιοχή rayfin/connectors/<connector-name>/.
• Εκτυπώνει μια εντολή που αντιστοιχεί στην npm install έκδοση για τα απαιτούμενα πακέτα σύνδεσης.

Εκτελέστε την ακριβή εντολή εγκατάστασης που εκτυπώνεται από το CLI. Αυτό διατηρεί τα πακέτα σύνδεσης ευθυγραμμισμένα με την έκδοση Rayfin CLI.

Σημείωμα

Η ανακάλυψη σχήματος είναι η καλύτερη προσπάθεια. Ο σύνδεσμος μπορεί να προστεθεί ακόμα και αν ο εντοπισμός δεν ολοκληρωθεί. Εάν το CLI εμφανίζει μια προειδοποίηση εντοπισμού, επιλύστε την πριν ορίσετε οντότητες από το αρχείο που δημιουργήθηκε metadata.json .

Η διαμόρφωση που δημιουργείται χρησιμοποιεί έλεγχο ταυτότητας με ανάθεση. Μια διαμόρφωση αποθήκης και σημασιολογικού μοντέλου μοιάζει με το ακόλουθο παράδειγμα:

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

Διατηρήστε την τιμή του σημασιολογικού μοντέλου version που δημιουργεί το CLI.

Ρύθμιση παραμέτρων σύνδεσης οντότητας

Οι συνδέσεις Lakehouse, αποθήκης και βάσης δεδομένων SQL εκθέτουν επιλεγμένους πίνακες προέλευσης ως οντότητες με τύπους. Χρησιμοποιήστε το αρχείο που δημιουργήθηκε metadata.json για να ορίσετε μόνο τους πίνακες και τις στήλες που χρειάζεται η εφαρμογή σας.

Το παρακάτω παράδειγμα υποθέτει ότι η επιλεγμένη αποθήκη περιέχει έναν dbo.Order πίνακα με ένα ακέραιο πρωτεύον κλειδί με όνομα και μια στήλη κειμένου με όνομα OrderIDcustomerEmail. Αντικαταστήστε αυτά τα επεξηγηματικά ονόματα και τύπους με τιμές από τα μετα-δεδομένα που δημιουργήσατε.

Σημαντικό

Μην συμπεραίνετε ένα πρωτεύον κλειδί από το όνομα μιας στήλης. Εάν ένας πίνακας προέλευσης δεν έχει κλειδί, παραλείψτε το primaryKey. Οι οντότητες χωρίς κλειδί δεν υποστηρίζουν λειτουργίες που απευθύνονται σε μια γραμμή προς κλειδί.

Δημιουργήστε την οντότητα:

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

Στη συνέχεια, καταχωρήστε την οντότητα στο σχήμα σύνδεσης:

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

Διατηρήστε συνεπή το όνομα σύνδεσης, την ιδιότητα σχήματος και το όνομα ρύθμισης παραμέτρων προγράμματος-πελάτη.

Ρύθμιση παραμέτρων του προγράμματος-πελάτη συνδέσεων

Προσθέστε τα σχήματα σύνδεσης στο ConnectorsRayfinClient. Οι συνδέσεις σημασιολογικών μοντέλων απαιτούν επίσης το 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(),
  }
);

Χρησιμοποιήστε τη διεύθυνση URL API και το κλειδί με δυνατότητα δημοσίευσης από το έργο Fabric Apps. Διατηρήστε την υπάρχουσα ροή εισόδου της εφαρμογής. Η δημιουργία του προγράμματος-πελάτη δεν συνδέει έναν χρήστη.

Υποβολή ερωτήματος σε συνδεδεμένα δεδομένα

Αφού εισέλθει ο χρήστης, αποκτήστε πρόσβαση σε μια σύνδεση οντότητας μέσω του ονόματος και της οντότητάς της:

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

Επιλέξτε ρητά τις στήλες και δεσμεύστε τον αριθμό των γραμμών που επιστρέφονται.

Για ένα μοντέλο σημασιολογίας, υποβάλετε ένα ερώτημα DAX με 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);
}

Αντικαταστήστε Sales με έναν πίνακα στο σημασιολογικό σας μοντέλο. Ελέγξτε την κατάσταση που επιστράφηκε πριν χρησιμοποιήσετε το αποτέλεσμα.

Ασφαλής πρόσβαση σύνδεσης

Χρησιμοποιήστε αυτά τα χειριστήρια μαζί:

• Περιορίστε τις λειτουργίες της σύνδεσης στις rayfin.yml ενέργειες που χρειάζεται η εφαρμογή.
• Προσθέστε @role δηλώσεις σε οντότητες σύνδεσης για να ελέγξετε ποιοι συνδεδεμένοι χρήστες μπορούν να εκτελέσουν κάθε λειτουργία.
• Προσθήκη πολιτικών γραμμής ή πεδίου περιλαμβάνουν και εξαιρούν κανόνες όταν οι χρήστες χρειάζονται πρόσβαση μόνο σε ένα μέρος μιας οντότητας.
• Διατηρήστε ενεργοποιημένο τον έλεγχο ταυτότητας με ανάθεση, ώστε οι αιτήσεις σύνδεσης να χρησιμοποιούν την πρόσβαση του συνδεδεμένου χρήστη.

Οι τύποι TypeScript από την πλευρά του προγράμματος-πελάτη βελτιώνουν την ασφάλεια ανάπτυξης, αλλά δεν αποτελούν όριο εξουσιοδότησης. Επιβολή πρόσβασης στη ρύθμιση παραμέτρων σύνδεσης και στους ρόλους οντότητας.

Ανάπτυξη της σύνδεσης

Αναπτύξτε τη ρύθμιση παραμέτρων της εφαρμογής και της σύνδεσης:

npx rayfin up

Δοκιμάστε την αναπτυγμένη εφαρμογή με έναν χρήστη που έχει τα αναμενόμενα δικαιώματα τόσο για την εφαρμογή Fabric όσο και για το συνδεδεμένο στοιχείο.

Σχετικό περιεχόμενο

• Δημιουργία εφαρμογής συνδεδεμένης σε μοντέλο σημασιολογίας
• Ορισμός μοντέλων δεδομένων
• Ορισμός δικαιωμάτων δεδομένων
• Έλεγχος ταυτότητας για εφαρμογές Fabric
• Αναπτύξτε μια εφαρμογή Fabric στο Fabric
• Αναφορά Rayfin CLI