Udostępnij przez

Łączenie aplikacji z interfejsem API sieci szkieletowej dla języka GraphQL

Łączenie aplikacji z interfejsem API usługi Fabric dla języka GraphQL umożliwia aplikacjom internetowym, mobilnym i zapleczu wykonywanie zapytań o źródła danych usługi Fabric przy użyciu nowoczesnego, wydajnego interfejsu API. Ta integracja wymaga odpowiedniego uwierzytelniania za pośrednictwem identyfikatora Entra firmy Microsoft i konfiguracji aplikacji w celu bezpiecznego wywoływania punktu końcowego GraphQL.

Ten artykuł przeprowadzi Cię przez proces łączenia aplikacji React z interfejsem API GraphQL Fabric za pomocą:

  1. Tworzenie i konfigurowanie aplikacji Microsoft Entra na potrzeby uwierzytelniania
  2. Konfigurowanie przykładowego interfejsu API GraphQL w Fabric z danymi do zapytań
  3. Klonowanie i konfigurowanie kompletnej aplikacji React z usługi GitHub
  4. Testowanie uwierzytelnionych połączeń

W tym samouczku jest używana platforma React, ale pojęcia dotyczące uwierzytelniania mają zastosowanie do dowolnego języka. Przykłady w języku C#, Python lub innych językach można znaleźć w repozytorium GitHub Przykłady usługi Microsoft Fabric.

Kto musi łączyć aplikacje

Konfiguracja połączenia aplikacji jest niezbędna w przypadku:

  • Deweloperzy aplikacji internetowych i mobilnych tworzą aplikacje korzystające z danych z lakehouse'ów i hurtowni Fabric
  • Deweloperzy integracji łączący dane Fabric z aplikacjami niestandardowymi i zautomatyzowanymi przepływami pracy
  • Deweloperzy zaplecza tworzący usługi integrujące się z ujednoliconą platformą analizy usługi Fabric
  • Inżynierowie danych konfigurują zautomatyzowane przepływy pracy przetwarzania danych korzystające z danych Fabric poprzez API

Skorzystaj z tego przewodnika, jeśli musisz uwierzytelnić i autoryzować aplikacje w celu uzyskania dostępu do interfejsów API graphQL usługi Fabric.

Wymagania wstępne

Podsumowanie uwierzytelniania i uprawnień

Dostęp do interfejsu API graphQL wymaga odpowiedniego uwierzytelniania i autoryzacji zarówno na poziomie interfejsu API, jak i bazowego źródła danych. Możesz uwierzytelnić się przy użyciu jednostki użytkownika (reprezentującej pojedynczego użytkownika) lub jednostki usługi (reprezentującej aplikację lub usługę). W przypadku łączności ze źródłem danych można użyć logowania jednokrotnego , w którym tożsamość obiektu wywołującego jest przekazywana do źródła danych lub zapisane poświadczenia , w których jest używane wstępnie skonfigurowane połączenie.

Poniższa tabela zawiera podsumowanie różnych obsługiwanych scenariuszy uwierzytelniania oraz minimalnych wymaganych uprawnień dla klientów, którzy uzyskują dostęp do interfejsu API GraphQL:

Obiekt wywołujący interfejs API Łączność źródeł danych Wymagane uprawnienia interfejsu API GraphQL Wymagane uprawnienia źródła danych Zakres aplikacji Entra firmy Microsoft
Podmiot zabezpieczeń użytkownika (UPN) Logowanie jednokrotne (SSO) Uruchamianie zapytań i mutacji na poziomie interfejsu API Odpowiednie uprawnienia do odczytu/zapisu przyznane do nazwy UPN w źródle danych GraphQLApi.Execute.All
Jednostka usługi (SPN) Logowanie jednokrotne (SSO) Uruchamianie zapytań i mutacji na poziomie interfejsu API Odpowiednie uprawnienia do odczytu/zapisu przyznane głównej nazwy usługi w źródle danych Nie dotyczy
Podmiot zabezpieczeń użytkownika (UPN) Zapisane poświadczenia Uruchamianie zapytań i mutacji na poziomie interfejsu API Odpowiednie uprawnienia do odczytu/zapisu przyznane zapisanym poświadczeniu (połączeniu) w źródle danych GraphQLApi.Execute.All
Jednostka usługi (SPN) Zapisane poświadczenia Uruchamianie zapytań i mutacji na poziomie interfejsu API Odpowiednie uprawnienia do odczytu/zapisu przyznane głównej nazwy usługi w źródle danych Nie dotyczy

Tworzenie aplikacji Microsoft Entra

Zanim aplikacja będzie mogła wywołać interfejs API GraphQL usługi Fabric, musisz zarejestrować go w identyfikatorze Entra firmy Microsoft. Ta rejestracja tworzy tożsamość dla aplikacji i definiuje, jakich uprawnień potrzebuje. Proces rejestracji generuje identyfikator klienta (identyfikator aplikacji) i ustanawia przepływ uwierzytelniania używany przez aplikację do uzyskiwania tokenów dostępu.

W przypadku aplikacji React należy skonfigurować ustawienia aplikacji jednostronicowej (SPA) korzystające z przepływu PKCE — bezpiecznej metody uwierzytelniania przeznaczonej dla aplikacji działających w przeglądarce, w których nie można bezpiecznie przechowywać sekretów klienta.

  1. Zarejestruj aplikację, wykonując kroki opisane w przewodniku Szybki start : rejestrowanie aplikacji za pomocą platformy tożsamości firmy Microsoft.

  2. Wartości w aplikacji Microsoft Entra, identyfikator aplikacji (klienta) oraz identyfikator katalogu (dzierżawy), są wyświetlane w polu Podsumowanie. Zapisz te wartości, ponieważ są one potrzebne podczas konfigurowania aplikacji React.

  3. Skonfiguruj uprawnienia interfejsu API, aby aplikacja mogła uzyskiwać dostęp do GraphQL API Fabric. Na liście Zarządzaj wybierz pozycję Uprawnienia interfejsu API, a następnie Dodaj uprawnienia.

  4. Dodaj usługę PowerBI, wybierz Delegowane uprawnienia, a następnie wybierz uprawnienia GraphQLApi.Execute.All. To uprawnienie umożliwia aplikacji wykonywanie zapytań i mutacji w imieniu zalogowanego użytkownika. Upewnij się, że zgoda administratora nie jest wymagana.

  5. Wróć do listy Zarządzanie, wybierz pozycję Uwierzytelnianie>Dodaj platformę>Aplikacja jednostronicowa.

  6. W celach programowania lokalnego dodaj http://localhost:3000 w obszarze Identyfikatory URI przekierowania i upewnij się, że aplikacja jest włączona dla przepływu kodu autoryzacji z kluczem dowodowym dla wymiany kodu (PKCE). Wybierz przycisk Konfiguruj, aby zapisać zmiany. Jeśli aplikacja napotka błąd związany z żądaniami między źródłami, dodaj platformę aplikacji mobilnych i desktopowych w poprzednim kroku z tym samym identyfikatorem URI przekierowania.

  7. Wróć do Authentication, przewiń w dół do Ustawienia zaawansowane i w obszarze Zezwalaj na przepływy klientów publicznychwybierz opcję Tak dla Włącz następujące przepływy mobilne i na komputery stacjonarne.

Konfigurowanie przykładowego interfejsu API graphQL na potrzeby dostępu do aplikacji

Po zarejestrowaniu aplikacji Microsoft Entra potrzebujesz interfejsu API GraphQL w usłudze Fabric do wykonywania zapytań. W tej sekcji opisano tworzenie przykładowego interfejsu API przy użyciu zestawu danych dni wolnych od pracy w usłudze Fabric. Zapewnia to działający interfejs API do testowania uwierzytelniania i pobierania danych bez konieczności konfigurowania własnych źródeł danych.

Przykładowy interfejs API udostępnia dane świąteczne z tabeli Lakehouse, do których aplikacja React wysyła zapytania w celu wyświetlenia świąt państwowych.

  1. Na stronie głównej portalu sieci szkieletowej wybierz pozycję inżynierowie danych z listy obciążeń.

  2. W środowisku inżynierii danych wybierz pozycję Użyj przykładu i w obszarze Lakehouse wybierz pozycję Święta publiczne , aby automatycznie utworzyć nową usługę Lakehouse z danymi o świętach publicznych.

    Zrzut ekranu przedstawiający wybieranie opcji przykładowej usługi Data Lakehouse.

  3. Wykonaj kroki z sekcji Tworzenie interfejsu API dla języka GraphQL , aby utworzyć nowy interfejs API GraphQL i wybrać utworzoną usługę Lakehouse. Dodaj tabelę dni wolnych, aby klienci mogli uzyskiwać dostęp do tych danych.

    Zrzut ekranu przedstawiający dodawanie przykładowego źródła danych Lakehouse jako źródła danych GraphQL.

  4. Przed utworzeniem aplikacji React sprawdź, czy interfejs API działa prawidłowo, testując go w edytorze interfejsu API. Użyj następującego zapytania — jest to to samo zapytanie, które aplikacja React wykonuje później:

     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. Wybierz pozycję Kopiuj punkt końcowy na pasku narzędzi elementu interfejsu API.

    Zrzut ekranu przedstawiający opcje paska narzędzi dla elementu interfejsu API.

  6. Na ekranie Kopiuj link wybierz pozycję Kopiuj.

    Zrzut ekranu przedstawiający okno dialogowe Kopiowanie linku pokazujące, gdzie wybrać pozycję Kopiuj.

  7. Zarejestruj identyfikator klienta, identyfikator dzierżawy z aplikacji Microsoft Entra oraz URI punktu końcowego. Te wartości są potrzebne podczas konfigurowania aplikacji React.

Klonowanie i konfigurowanie aplikacji React

Teraz, gdy masz już skonfigurowaną aplikację Microsoft Entra i interfejs API GraphQL, możesz skonfigurować aplikację React w celu nawiązania z nimi połączenia. Aplikacja używa biblioteki Microsoft Authentication Library (MSAL) do obsługi uwierzytelniania i wysyła żądania GraphQL z tokenami elementu nośnego.

  1. Sklonuj repozytorium przykładów z usługi GitHub:

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

  2. Przejdź do folderu aplikacji React:

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

    Folder zawiera kompletną aplikację React. Musisz tylko edytować src/authConfig.js , aby skonfigurować określony punkt końcowy i poświadczenia.

  3. Otwórz projekt w edytorze kodu:

    code .

  4. W edytorze przejdź do src folderu i otwórz plik authConfig.js.

  5. Zastąp następujące wartości symboliczne swoimi szczegółowymi danymi:

    Ważne

    W tym samym pliku stała loginRequest obejmuje zakres https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Ten dokładny zakres jest wymagany do dostępu do interfejsów API GraphQL usługi Fabric. Nie usuwaj ani nie modyfikuj tego zakresu; w przeciwnym razie uwierzytelnianie kończy się niepowodzeniem.

  6. Zapisz plik.

  7. W terminalu przejdź do folderu głównego projektu i uruchom polecenie:

    npm install

    Spowoduje to zainstalowanie wszystkich wymaganych zależności.

Testowanie aplikacji

Po skonfigurowaniu aplikacji uruchom ją lokalnie, aby sprawdzić, czy wszystko działa poprawnie:

  1. Uruchom w terminalu:

    npm start

    To polecenie uruchamia serwer deweloperów i otwiera aplikację w przeglądarce.

  2. Ukończ przepływ uwierzytelniania, gdy aplikacja ładuje się pod adresem http://localhost:3000. Postępuj zgodnie z instrukcjami logowania opisanymi w sekcji samouczek Wywoływanie interfejsu API z aplikacji.

  3. Po pomyślnym zalogowaniu wybierz przycisk API Query Fabric dla danych GraphQL. Wywołuje to proces uwierzytelniania, pobiera token dostępu i wykonuje zapytanie GraphQL dla Fabric API.

    Zrzut ekranu przedstawiający przykładową aplikację React po zalogowaniu.

  4. Jeśli wszystko jest poprawnie skonfigurowane, aplikacja wyświetla dni wolne w tabeli. Potwierdza to, że:

    • Twoja aplikacja Microsoft Entra ma odpowiednie uprawnienia
    • Token dostępu został pomyślnie uzyskany
    • GraphQL API uwierzytelniło żądanie
    • Zapytanie wykonywane względem danych usługi Lakehouse

    Zrzut ekranu przedstawiający przykładową aplikację React po otrzymaniu żądania GraphQL.

Inne polecenia npm

Poza npm start i npm install można użyć tych typowych poleceń npm w różnych scenariuszach rozwojowych:

  • npm run dev — Alternatywny sposób uruchamiania serwera programistycznego
  • npm run build — Tworzenie zoptymalizowanej kompilacji produkcyjnej aplikacji
  • npm run preview — Testowanie kompilacji produkcyjnej lokalnie przed wdrożeniem
  • npm test — Uruchamianie testów automatycznych w celu sprawdzenia, czy kod działa poprawnie

Powiązana zawartość

Teraz, gdy masz działającą aplikację połączoną z interfejsem API GraphQL usługi Fabric, zapoznaj się z tymi zasobami, aby utworzyć bardziej zaawansowane rozwiązania:

  • Last updated on