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


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

Примечание.

API Microsoft Fabric для GraphQL находится в предварительной версии.

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

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

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

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

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

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

В следующих шагах показано, как настроить поддержку приложения ReactJS в Entra.

  1. Войдите на портал Azure.

  2. Найдите и выберите Microsoft Entra ID.

  3. В списке "Управление" выберите "Регистрация приложения".

  4. Выберите Создать регистрацию.

  5. Заполните необходимые сведения:

    • Имя — введите имя приложения.

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

    • (Необязательно) Универсальный код ресурса (URI перенаправления) — при необходимости введите универсальный код ресурса (URI).

  6. Выберите Зарегистрировать. Значения идентификатора приложения приложения Microsoft Entra (клиента) и каталога (клиента) отображаются в поле сводки. Запишите эти значения, так как они требуются позже.

  7. В списке "Управление" выберите разрешения API, а затем добавьте разрешение.

  8. Добавьте службу PowerBI, выберите делегированные разрешения и выберите разрешения Item.Execute.All и Datamart.ReadWrite.All. Убедитесь, что согласие администратора не требуется.

  9. Вернитесь в список "Управление ", выберите "Проверка подлинности", выберите " Добавить платформу", а затем выберите одностраничные приложения.

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

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

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

В этом примере мы создадим API GraphQL для предоставления примеров данных Lakehouse клиентам.

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

    Снимок экрана: переключатель рабочей нагрузки Fabric.

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

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

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

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

  4. Проверьте API GraphQL в редакторе 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. В качестве идентификатора клиента и идентификатора клиента из приложения Entra, записанного ранее, скопируйте URI конечной точки, как это требуется позже.

Настройка приложения React для доступа к API общедоступных праздников

  1. Мы используем существующее приложение React в качестве отправной точки. Выполните все действия, описанные в руководстве по созданию одностраничного приложения React, и подготовьте его к проверке подлинности, чтобы создать проект React с проверкой подлинности Entra, включая дополнительные файлы и папки, необходимые для добавления в структуру проекта. Нам нужно изменить только три файла, чтобы адаптировать приложение для нашего варианта использования GraphQL.

  2. В папке src откройте файл authConfig.js и замените содержимое файла следующим фрагментом кода:

     /*
      * Copyright (c) Microsoft Corporation. All rights reserved.
      * Licensed under the MIT License.
      */
    
     import { LogLevel } from "@azure/msal-browser";
    
     /**
      * Configuration object to be passed to MSAL instance on creation. 
      * For a full list of MSAL.js configuration parameters, visit:
      * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
      */
    
     export const graphqlConfig = {
         graphqlEndpoint: "`Enter_the_GraphQL_Endpoint_Here"
     };
    
     export const msalConfig = {
         auth: {
             clientId: "Enter_the_Application_Id_Here",
             authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
             redirectUri: "http://localhost:3000",
         },
         cache: {
             cacheLocation: "sessionStorage", // This configures where your cache will be stored
             storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
         },
         system: {	
             loggerOptions: {	
                 loggerCallback: (level, message, containsPii) => {	
                     if (containsPii) {		
                         return;		
                     }		
                     switch (level) {
                         case LogLevel.Error:
                             console.error(message);
                             return;
                         case LogLevel.Info:
                             console.info(message);
                             return;
                         case LogLevel.Verbose:
                             console.debug(message);
                             return;
                         case LogLevel.Warning:
                             console.warn(message);
                             return;
                         default:
                             return;
                     }	
                 }	
             }	
         }
     };
    
     /**
      * Scopes you add here will be prompted for user consent during sign-in. 
      * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
      * For more information about OIDC scopes, visit: 
      * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
      */
     export const loginRequest = {
         scopes: ["https://analysis.windows.net/powerbi/api/Item.Execute.All","https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All"]
     };
    
     /**
      * Add here the scopes to request when obtaining an access token for MS Graph API. For more information, see:
      * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
      */
     export const graphConfig = {
         graphMeEndpoint: "https://graph.microsoft.com/v1.0/me",
     };
    

    Как видно из приведенного выше кода, важно использовать правильную область для доступа к приложению. В нашем случае https://analysis.windows.net/powerbi/api/Item.Execute.All и https://analysis.windows.net/powerbi/api/Datamart.ReadWrite.All.

    Внимание

    Области могут изменяться во время предварительной версии API Microsoft Fabric для GraphQL.

  3. Замените следующие значения значениями из Центра администрирования Microsoft Entra.

    • clientId — идентификатор приложения, который также называется клиентом. Замените Enter_the_Application_Id_Here значение идентификатора приложения (клиента), записанное ранее на странице обзора зарегистрированного приложения Entra.
    • authority — Это состоит из двух частей:
      • Экземпляр — конечная точка поставщика облачных служб. Ознакомьтесь с различными доступными конечными точками в национальных облаках.
      • Идентификатор клиента — это идентификатор клиента, в котором зарегистрировано приложение. Замените Enter_the_Tenant_Info_Here значением идентификатора каталога (клиента), записанного ранее на странице обзора зарегистрированного приложения.
    • graphQLEndpoint — API Fabric для конечной точки GraphQL. Замените Enter_the_GraphQL_Endpoint_Here конечную точку API GraphQL, записанную ранее.
  4. Сохраните файл.

  5. В той же папке src откройте файл App.js и замените содержимое файла следующим фрагментом кода:

     import React, { useState } from 'react';
     import { PageLayout } from './components/PageLayout';
     import { loginRequest, graphqlConfig } from './authConfig';
     import { ProfileData } from './components/ProfileData';
     import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal } from '@azure/msal-react';
     import './App.css';
     import Button from 'react-bootstrap/Button';
     import Spinner from 'react-bootstrap/Spinner';
    
     /**
     * Renders information about the signed-in user or a button to retrieve data about the user
     */
     const ProfileContent = () => {
       const { instance, accounts } = useMsal();
       const [graphqlData, setGraphqlData] = useState(null);
       const [display, setDisplay] = useState(false);
    
       function RequestGraphQL() {
           // Silently acquires an access token which is then attached to a request for GraphQL data
           instance
               .acquireTokenSilent({
                   ...loginRequest,
                   account: accounts[0],
               })
               .then((response) => {
                   callGraphQL(response.accessToken).then((response) => setGraphqlData(response));
               });
       }
    
     async function callGraphQL(accessToken) {
       setDisplay(true);
       const query = `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
           }
         }
       }`;
       fetch(graphqlConfig.graphqlEndpoint, {
               method: 'POST',
               headers: {
                   'Content-Type': 'application/json',
                   'Authorization': `Bearer ${accessToken}`,
               },
               body: JSON.stringify({ 
                   query: query
               })
           })
           .then((res) => res.json())
           .then((result) => setGraphqlData(result));
     }
    
       return (
           <>
               <h5 className="card-title">Welcome {accounts[0].name}</h5>
               <br/>
               {graphqlData ? (
                   <ProfileData graphqlData={graphqlData} />
               ) : (
                   <Button variant="primary" onClick={RequestGraphQL}>
                       Query Fabric API for GraphQL Data 
                       {display ? (
                             <Spinner
                                 as="span"
                                 animation="border"
                                 size="sm"
                                 role="status"
                                 aria-hidden="true"
                             />
                         ) : null}
                   </Button>
               )}
           </>
       );
     };
    
     /**
     * If a user is authenticated the ProfileContent component above is rendered. Otherwise a message indicating a user is not authenticated is rendered.
     */
     const MainContent = () => {
       return (
           <div className="App">
               <AuthenticatedTemplate>
                   <ProfileContent />
               </AuthenticatedTemplate>
    
               <UnauthenticatedTemplate>
                   <h5>
                       <center>
                           Please sign-in to see your profile information.
                       </center>
                   </h5>
               </UnauthenticatedTemplate>
           </div>
       );
     };
    
     export default function App() {
       return (
           <PageLayout>
               <center>
                   <MainContent />
               </center>
           </PageLayout>
       );
     }
    
  6. Сохраните файл.

  7. Наконец, в папке src/components откройте файл ProfileData.jsx и замените содержимое файла следующим фрагментом кода:

     import React from "react";
     import ListGroup from 'react-bootstrap/ListGroup'; 
     import Table from 'react-bootstrap/Table';
     /**
      * Renders information about the user obtained from MS Graph 
      * @param props
      */
     export const ProfileData = (props) => {
       const holidays = props.graphqlData.data.publicholidays.items;
       return (
         <Table striped bordered hover responsive>
         <thead>
           <tr>
             <th>Country</th>
             <th>Holiday</th>
             <th>Date</th>
           </tr>
         </thead>
         <tbody>
           {holidays.map((item,i) => (
           <tr key={i}>
             <td>{item.countryOrRegion}</td>
             <td>{item.holidayName}</td>
             <td>{item.date}</td>
           </tr>
           ))}
           </tbody>
         </Table>
     )};
    
  8. Сохраните все изменения файла.

  9. В выбранном приложении терминала перейдите в корневую папку проекта React и выполните команду npm start для локального тестирования приложения.

  10. После загрузки приложения в браузере http://localhost:3000выполните действия, описанные в последней части руководства по вызову API из приложения для проверки подлинности.

  11. После входа нажмите кнопку API Query Fabric для данных GraphQL.

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

  12. Успешно прошедший проверку подлинности запрос к API GraphQL в Fabric возвращает данные из запроса GraphQL в Lakehouse в клиентском приложении React:

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

Остальные языки

Найдите C#, Python и другие языковые примеры для подключения к API GraphQL в репозитории GitHub примеров Microsoft Fabric.