Поделиться через

Подключение приложений к API Fabric для GraphQL

Подключение приложений к API Fabric для GraphQL позволяет веб-приложениям, мобильным и серверным приложениям запрашивать источники данных Fabric с помощью современного, эффективного API. Для этой интеграции требуется правильная проверка подлинности с помощью идентификатора Microsoft Entra и настройки приложения для безопасного вызова конечной точки GraphQL.

В этой статье описано, как подключить приложение React к API GraphQL Fabric, выполнив следующие действия.

  1. Создание и настройка приложения Microsoft Entra для проверки подлинности
  2. Настройка примера API GraphQL в Fabric с данными для запроса
  3. Клонирование и настройка полного приложения React из GitHub
  4. Тестирование аутентифицированного подключения

В этом руководстве используется React, но основные понятия проверки подлинности применяются к любому языку. Примеры на C#, Python или других языках см. в репозитории GitHub примеров Microsoft Fabric.

Кто должен подключать приложения

Настройка подключения к приложению необходима для:

  • Веб-разработчики и разработчики мобильных приложений, создающие программы, использующие данные из Fabric lakehouses и хранилищ
  • Разработчики интеграции подключают данные Fabric к пользовательским приложениям и автоматизированным рабочим процессам
  • Разработчики серверной части создают службы, которые интегрируются с унифицированной платформой аналитики Fabric
  • Инженеры данных настраивают автоматизированные рабочие процессы обработки данных, которые используют данные Fabric через API

Используйте это руководство, если необходимо выполнить проверку подлинности и авторизацию приложений для доступа к API GraphQL Fabric.

Необходимые компоненты

  • Средства разработки: на компьютере требуется Node.js (версия LTS) и Visual Studio Code .

  • Перед подключением приложения убедитесь, что у вас есть API для GraphQL в Fabric. Дополнительные сведения см. в статье "Создание API для GraphQL в Fabric" и добавление данных.

  • API для GraphQL требует, чтобы приложения использовали Microsoft Entra для проверки подлинности. Зарегистрируйте и настройте приложение для выполнения вызовов API в Fabric. Дополнительные сведения см. в статье "Создание приложения Microsoft Entra" в Azure.

  • Учетные данные, прошедшие проверку подлинности (субъект-пользователь, субъект-служба или управляемое удостоверение), вызывая API, требуют разрешения execute для API GraphQL (параметр "Выполнить запросы и мутации" при добавлении разрешений прямого доступа). При использовании единого входа (SSO) в качестве параметра подключения в API убедитесь, что учетные данные имеют разрешения на чтение или запись в выбранном источнике данных. Дополнительные сведения см. в разделе Подключение к источнику данных и сборка схемы.

Сводка по проверке подлинности и разрешениям

Для доступа к API GraphQL требуется правильная проверка подлинности и авторизация на уровне API и базовом уровне источника данных. Вы можете пройти проверку подлинности с помощью субъекта-пользователя (представляющего отдельного пользователя) или субъекта-службы (представляющего приложение или службу). Для подключения к источнику данных можно использовать единый вход, где удостоверение вызывающего объекта передается в источник данных, или сохраненные учетные данные, в которых используется предварительно настроенное подключение.

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

Вызывающий API Подключение к источнику данных Обязательные разрешения API GraphQL Необходимые разрешения источника данных Область приложения Microsoft Entra
Субъект-пользователь (UPN) Единый вход (SSO) Выполнение запросов и мутаций на уровне API Соответствующие разрешения на чтение и запись, предоставленные имени участника-пользователя в источнике данных GraphQLApi.Execute.All
Субъект-служба (SPN) Единый вход (SSO) Выполнение запросов и мутаций на уровне API Соответствующие разрешения на чтение и запись, предоставленные имени участника-службы в источнике данных Не применимо
Субъект-пользователь (UPN) Сохраненные учетные данные Выполнение запросов и мутаций на уровне API Соответствующие разрешения на чтение и запись, предоставленные сохраненным учетным данным (подключение) в источнике данных GraphQLApi.Execute.All
Субъект-служба (SPN) Сохраненные учетные данные Выполнение запросов и мутаций на уровне API Соответствующие разрешения на чтение и запись, предоставленные имени участника-службы в источнике данных Не применимо

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

Прежде чем приложение сможет вызвать API GraphQL Fabric, необходимо зарегистрировать его в идентификаторе Microsoft Entra. Эта регистрация создает идентичность для вашего приложения и определяет, какие разрешения ему необходимы. Процесс регистрации создает идентификатор клиента (идентификатор приложения) и устанавливает поток проверки подлинности, который приложение использует для получения маркеров доступа.

Для приложений React вы настраиваете параметры одностраничного приложения (SPA), использующие поток PKCE— безопасный метод проверки подлинности, предназначенный для приложений на основе браузера, в которых секреты клиента не могут безопасно храниться.

  1. Зарегистрируйте приложение, используя шаги, описанные в разделе Быстрый старт: Регистрация приложения на платформе идентификации Microsoft.

  2. Значения идентификатора приложения приложения Microsoft Entra (клиента) и идентификатора каталога (клиента) отображаются в поле сводки. Запишите эти значения, так как они необходимы при настройке приложения React.

  3. Настройте разрешения API, чтобы приложение получите доступ к API GraphQL Fabric. В списке Управление выберите Разрешения API, затем Добавить разрешение.

  4. Добавьте службу PowerBI, выберите делегированные разрешения и выберите разрешения GraphQLApi.Execute.All . Это разрешение позволяет приложению выполнять запросы и изменения от имени пользователя, выполнившего вход. Убедитесь, что согласие администратора не требуется.

  5. Вернитесь в список "Управление", выберите "Добавить>одностраничные приложения>".

  6. Для локальных целей разработки добавьте http://localhost:3000 в URI перенаправления и убедитесь, что приложение включено для потока кода авторизации с ключом проверки подлинности для Exchange (PKCE). Нажмите кнопку "Настройка", чтобы сохранить изменения. Если приложение сталкивается с ошибкой, связанной с запросами между источниками, добавьте платформу мобильных и классических приложений на предыдущем шаге с тем же URI перенаправления.

  7. Вернитесь к проверке подлинности, прокрутите вниз до расширенные настройки и, в разделе Разрешить потоки общедоступных клиентов, выберите Да для Включить следующие потоки для мобильных и настольных приложений.

Настройка примера API GraphQL для доступа к приложениям

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

Пример API предоставляет данные праздников из таблицы Lakehouse, которую приложение React запрашивает для отображения государственных праздников.

  1. На домашней странице портала Fabric выберите Инжиниринг данных из списка рабочих нагрузок.

  2. В разделе "Проектирование данных" выберите "Использовать пример" и в разделе Lakehouse выберите общедоступные праздники, чтобы автоматически создать новый Lakehouse с данными о государственных праздниках.

    Снимок экрана: выбор примера параметра Data Lakehouse.

  3. Выполните действия из статьи "Создание API для GraphQL", чтобы создать новый API GraphQL и выбрать созданное приложение Lakehouse. Добавьте таблицу государственных праздников, чтобы клиенты могли получить доступ к этим данным.

    Снимок экрана: добавление примера Lakehouse в качестве источника данных GraphQL.

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

     query {
 publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
     items {
       countryOrRegion
       holidayName
       date
     }
   }
 }

  5. Выберите конечную точку копирования на панели инструментов элемента API.

    Снимок экрана: параметры панели инструментов для элемента API.

  6. На экране ссылки "Копировать" нажмите кнопку "Копировать".

    Снимок экрана: диалоговое окно

  7. Запишите идентификатор клиента и идентификатор клиента из приложения Microsoft Entra и URI конечной точки. Эти значения требуются при настройке приложения React.

Клонирование и настройка приложения React

Теперь, когда у вас есть приложение Microsoft Entra и API GraphQL, вы можете настроить приложение React для подключения к ним. Приложение использует библиотеку проверки подлинности Майкрософт (MSAL) для обработки проверки подлинности и выполнения запросов GraphQL с маркерами носителя.

  1. Клонируйте репозиторий примеров из GitHub:

    git clone https://github.com/microsoft/fabric-samples.git

  2. Перейдите в папку приложения React:

    cd fabric-samples/docs-samples/data-engineering/GraphQL/React

    Папка содержит полное приложение React. Необходимо изменить src/authConfig.js только для настройки конкретной конечной точки и учетных данных.

  3. Откройте проект в редакторе кода:

    code .

  4. В вашем редакторе перейдите в папку src и откройте authConfig.js.

  5. Замените следующие значения заполнителей конкретными сведениями:

    Это важно

    В том же файле константа loginRequest включает область https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Эта точная область требуется для доступа к GraphQL API Fabric. Не удаляйте и не изменяйте эту область действия; иначе проверка подлинности завершится ошибкой.

  6. Сохраните файл.

  7. В терминале перейдите в корневую папку проекта и выполните следующую команду:

    npm install

    При этом устанавливаются все необходимые зависимости.

Тестирование приложения

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

  1. В терминале выполните следующую команду:

    npm start

    Эта команда запускает сервер разработки и открывает приложение в браузере.

  2. Завершите поток проверки подлинности при загрузке http://localhost:3000приложения. Следуйте инструкциям по входу, описанным в разделе учебника "Вызов API" из приложения.

  3. После успешного входа нажмите кнопку API Query Fabric для GraphQL Data . Это активирует поток проверки подлинности, получает маркер доступа и выполняет запрос GraphQL к API Fabric.

    Снимок экрана: пример приложения React после входа.

  4. Если все настроено правильно, приложение отображает общедоступные праздники в таблице. Это подтверждает следующее:

    • Приложение Microsoft Entra имеет правильные разрешения
    • Маркер доступа успешно получен
    • API GraphQL прошел проверку подлинности запроса
    • Запрос, выполняемый для данных Lakehouse

    Снимок экрана: пример приложения React после получения запроса GraphQL.

Другие команды npm

Кроме npm start и npm install вы можете использовать эти распространенные npm команд для различных сценариев разработки:

  • npm run dev — альтернативный способ запуска сервера разработки
  • npm run build — создание оптимизированной рабочей сборки приложения
  • npm run preview — протестируйте рабочую сборку локально перед развертыванием
  • npm test — Выполнение автоматических тестов для проверки правильности работы кода

Связанный контент

Теперь, когда у вас есть рабочее приложение, подключенное к API GraphQL Fabric, изучите эти ресурсы для создания более сложных решений:

  • Last updated on