Соедините приложения Fabric с данными Fabric

Соединители обеспечивают типизированный доступ для приложения Fabric к данным в других элементах Fabric. Используйте коннектор для выполнения запросов к lakehouse, warehouse, базе данных SQL в Fabric или семантической модели без необходимости настраивать отдельную службу данных.

Поддерживаемые соединители

Выберите соединитель, исходя из элемента Fabric и операций, необходимых вашему приложению:

Предмет из ткани	Тип соединителя	Поддерживаемые операции
Конечная точка SQL-аналитики для Lakehouse	fabric-sqlanalytics	read
warehouse	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 таблицу с целочисленным первичным ключом OrderID и текстовым столбцем с именем customerEmail. Замените эти иллюстративные имена и типы значениями из ваших сгенерированных метаданных.

Important

Не делайте выводы о первичном ключе по названию столбца. Если в исходной таблице нет ключа, опустите 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