Создание приложения, подключенного к семантической модели

Используйте шаблон приложения данных с коннектором семантической модели Fabric для создания аналитического приложения Fabric. Шаблон предоставляет визуализацию, форматирование, сетку данных и шаблоны проверки браузером. Коннектор предоставляет типированный, делегированный доступ к семантической модели через клиент Fabric Apps.

По умолчанию приложения, созданные на основе шаблона, включают:

Аутентификация Fabric.
Руководство по созданию высококачественных выражений DAX (Data Analysis Expressions).
Корпоративные визуальные компоненты, предназначенные для аналитических приложений.
Сетка данных, тематика, форматирование и шаблоны валидации браузером.

Замечание

В настоящее время поддерживаемым способом создания приложений с помощью шаблона приложения данных является Rayfin CLI.

Почему используйте шаблон приложения данных?

Без этих встроенных возможностей кодирующий агент должен решать задачи аутентификации, генерации DAX и визуализации с нуля в каждой сессии. Это может привести к:

Больше неудач и сломанных или пустых визуальных эффектов.
Непоследовательное поведение в графике.
Ненужные запросы по DAX во время разработки и выполнения.

Шаблон предоставляет повторно используемые шаблоны, повышающие надёжность, создающие более целостные визуальные эффекты, соответствующие лучшим практикам отчётности, и снижают накладные расходы на запросы. Разъём стандартизирует конфигурацию семантических моделей и доступ во время выполнения.

Необходимые условия

Node.js 20 или более поздняя версия.
Доступ к Fabric.
Рабочая область Fabric, в которой у вас есть права участника, члена или администратора.
Рабочая нагрузка Fabric Apps включена в вашем тенанте. См. «Создать свое первое приложение Fabric».
Включен параметр арендатора REST API Execute Queries для семантической модели.
Разрешения на построение и чтение для семантической модели, размещённой на мощностях Fabric или Power BI.
Идентификатор рабочего пространства и идентификатор элемента для семантической модели.

Создание приложения

Создайте проект по шаблону приложения данных:

npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>

Замените <app-name> и <workspace-name> названиями вашего приложения и рабочей области Fabric. Затем откройте папку нового проекта:

cd <app-name>

Добавьте разъём семантической модели

Если вы не знаете идентификатор элемента семантической модели, перечислите семантические модели в рабочем пространстве:

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

Добавьте семантическую модель в качестве соединителя:

npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

Команда:

Добавляет коннектор salesModel к rayfin/rayfin.yml.
Создаёт свою схему в rayfin/connectors/salesModel/.
Выводит команду npm install, соответствующую версии пакетов коннектора.

Запустите точно ту команду установки, которую выводит CLI.

Сгенерированная конфигурация напоминает следующий пример:

connectors:
  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

Сохраняйте сгенерированную version ценность.

Подключите шаблон к семантической модели

Шаблон содержит аналитические компоненты и инструкции для агента, которые можно повторно использовать с коннектором. Настройте его слой доступа к данным для создания ConnectorsRayfinClient и регистрации среды выполнения семантической модели:

Important

Используйте клиент-коннектор для запросов семантической модели. Если шаблон уже включает другой клиент семантической модели, замените вызовы так, чтобы они обращались к нему, вместо того чтобы поддерживать два пути доступа к данным.

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import {
  connectorConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      salesModel: connectorConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

Используйте URL API и ключ для публикации из вашего проекта Fabric Apps. Сохранить существующий в шаблоне процесс входа в Fabric.

Отправьте DAX через коннектор:

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 на таблицу в вашей семантической модели. Проверьте возвращённый статус перед передачей столбцов и строк в визуальный объект.

Для получения дополнительной конфигурации разъёмов и рекомендаций по безопасности см. раздел Connect Fabric Apps to Fabric data.

Создайте приложение с помощью программистского агента

Каркас включает инструкции и навыки для агентов для программирования. Откройте проект в выбранном агенте и опишите аудиторию, вопросы, взаимодействия и визуализации приложения.

Например, доступны следующие возможности:

Откройте проект в Visual Studio Code, а затем откройте панель Copilot Chat на GitHub.
Откройте терминал в проекте, затем запустите copilot.

Используйте этот запрос как отправную точку:

Build an analytical Fabric app that uses the existing salesModel connector.

Before editing:
1. Read the repository instructions and skills.
2. Inspect rayfin/connectors/salesModel/schema.ts and the template's data-access,
   visualization, data grid, formatting, and validation patterns.
3. Query the semantic model metadata before writing DAX. Don't guess table,
   measure, or column names.

Requirements:
- Use ConnectorsRayfinClient and fabricSemanticModel() for semantic model access.
- Call client.connectors.salesModel.executeQuery() for DAX queries.
- Keep the existing Fabric sign-in flow. Don't add credentials, access tokens,
  another authentication flow, or direct calls to the Execute Queries REST API.
- Reuse query results where practical, and bound large result sets.
- Apply semantic model format strings consistently to cards, charts, tooltips,
  and data grids.
- Include loading, empty, and error states.
- Use the template's browser-validation workflow at desktop and mobile sizes.

Give me a short implementation plan, make the changes, run the existing build,
and report the results.

Используйте возможности шаблона

Шаблон приложения для данных содержит повторно используемые шаблоны для аналитических приложений.

Fabric Apps — это стандартные веб-приложения, поэтому вы можете реализовать функции вне этих шаблонов. Функции, отсутствующие в шаблоне, могут потребовать дополнительной индивидуальной инженерии и проверки.

Визуальные элементы

Шаблон включает перекрёстное выделение и заранее настроенные примитивы для:

Столбчатые диаграммы, включая вертикальные, горизонтальные, сгруппированные и сложенные схемы.
Линейные диаграммы с опциональными маркерами.
Карты районов.
Диаграммы рассеяния.
Диаграммы с пирогом и пончиками.
Тепловые карты.
Пузырьковые диаграммы.
Карты водопадов.
Карточки с одним значением для вызовов KPI.
Многослойные и составные визуальные элементы, такие как полосы с метками данных и линейные диаграммы с двумя осями.

Используйте поля и показатели, существующие в связной семантической модели. Не заменяйте неудачный запрос по коннектору на имитацию данных.

Вы можете попросить агента по программированию сгенерировать другие визуальные элементы. Визуалы без шаблонного примитива могут потребовать больше итераций и проверки.

Возможности сетки данных

Шаблон включает сетку данных со следующими заранее настроенными возможностями:

Заголовки столбцов, полученные из метаданных семантической модели.
Форматирование чисел и дат применяется для каждого столбца с помощью строк формата.
Сортировка.
Прокручиваемые строки с обработкой переполнения.
Поддержка светлых и тёмных тем.
Кастомные рендереры ячеек для:
- Полоски данных для числовых значений.
- Булевые индикаторы.
- Кликаемые URL-адреса.
- Ячейки изображения с наложением лайтбокса.
- Многополевые ячейки, такие как имя и роль в одном столбце.

Можно добавить другие возможности сетки данных, но для них может потребоваться больше индивидуальной инженерии.

Тематизация

Дайте своему агенту по программированию требования к брендингу или стилю, такие как цветовая палитра, стиль углов или шрифт. Шаблон хранит общие стили в одном месте, поэтому изменения автоматически применяются к карточкам, кнопкам, диаграммам, таблицам данных и всплывающим подсказкам.

Централизованное оформление позволяет избежать несовпадающих цветов, несогласованных шрифтов и различий в макете, которые могут возникнуть при отдельном стилизации каждого компонента.

Форматирование строк

Определите форматирование один раз на каждый столбец результата. Шаблон может повторно использовать строки форматирования семантической модели на осях диаграмм, во всплывающих подсказках, в метках данных, карточках и ячейках таблицы данных.

Например, одно определение формата обеспечивает отображение 1500.5 как $1,500.50 и 0.25 как 25% везде, где встречаются эти значения.

Проверка браузера

Перед публикацией приложения используйте встроенный рабочий процесс проверки браузера Playwright, чтобы открыть его в реальном браузере и проверить:

Визуализация отображается корректно.
Диаграммы не обрезаются и не сжимаются.
Текст читается.
Сетки данных обрабатывают переполнение.
Состояния загрузки, пустого состояния и ошибки пригодны для использования.
Фильтры, перекрёстное выделение и форматирование данных работают как следует.
В консоли браузера нет неожиданных ошибок.

Этот рабочий процесс фиксирует проблемы с макетом и рендерингом до того, как пользователи их заметят. Проверка браузера подтверждает поведение фронтенда. Протестируйте развернутый коннектор отдельно с пользователем, имеющим доступ как к приложению Fabric, так и к семантической модели.

Развернуть и проверить приложение

Разверните приложение и конфигурацию коннектора:

npx rayfin up

Откройте развернутое приложение через портал Fabric. Войдите в систему, запустите каждое взаимодействие пользователя и сравните важные результаты с семантической моделью.

Если запрос завершается ошибкой:

Подтвердите идентификаторы элементов рабочего пространства и семантической модели в rayfin.yml.
Убедитесь, что настройка REST API tenant Semantic Model Execute Queries включена.
Убедитесь, что у пользователя есть права на создание и чтение семантической модели.
Проверьте, что DAX ссылается на существующие таблицы, столбцы и измерения.
Проверьте категорию ошибки и сообщение результата разъёма.
Проверьте браузерную консоль на наличие ошибок на стороне клиента.

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-09-29