Udostępnij przez

Tworzenie aplikacji GraphQL w programie Visual Studio Code

Dowiedz się, jak utworzyć aplikację front-end, korzystając z React, Apollo Client i TypeScript, która integruje się z API GraphQL hostowanym w Microsoft Fabric. W tym samouczku opisano konfigurowanie lokalnych narzędzi programistycznych, w tym uzupełnianie automatyczne, generowanie kodu i funkcję IntelliSense, w celu uzyskania optymalnego środowiska programisty.

Kto powinien używać narzędzi programistycznych programu VS Code

Programowanie lokalne za pomocą programu VS Code jest przeznaczone dla:

  • Deweloperzy platformy React tworzący aplikacje internetowe korzystające z usługi Fabric lakehouse i danych magazynu za pośrednictwem języka GraphQL
  • Deweloperzy języka TypeScript , którzy potrzebują bezpiecznego generowania kodu klienta dla interfejsów API GraphQL usługi Fabric
  • Deweloperzy full-stack tworzący niestandardowe aplikacje analityczne na platformie Fabric z lokalnym wsparciem dla środowiska IDE
  • Zespoły programistyczne, które chcą korzystać z nowoczesnych narzędzi z funkcjami IntelliSense i debugowania dla aplikacji dostępu do danych Fabric

Użyj tego podejścia podczas kompilowania aplikacji React, które wymagają rozbudowanej obsługi środowiska IDE, generowania kodu i lokalnego debugowania przy użyciu języków TypeScript i Apollo Client.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz:

  • Dostęp do obszaru roboczego usługi Microsoft Fabric: należy być członkiem obszaru roboczego Fabric z co najmniej rolą Współpracownik (lub wyższą: Administrator, Członek), aby utworzyć i modyfikować elementy interfejsu API GraphQL.
  • Uprawnienia źródła danych: uprawnienia do odczytu/zapisu w źródłach danych, które planujesz uwidocznić za pośrednictwem interfejsu API GraphQL
  • Node.js zainstalowane na komputerze deweloperskim (w tym npm)
  • Program Visual Studio Code zainstalowany na komputerze deweloperskim
  • Podstawowa wiedza na temat pojęć związanych z platformami React, TypeScript i GraphQL

Krok 1. Tworzenie interfejsu API GraphQL w usłudze Microsoft Fabric

Uwaga / Notatka

W tym przewodniku przedstawiono tworzenie interfejsu API graphQL z kontekstu bazy danych SQL. Najpierw utworzysz bazę danych SQL, a następnie utworzysz interfejs API GraphQL bezpośrednio z poziomu tej bazy danych. Jeśli masz już istniejący interfejs API GraphQL i chcesz się z nim połączyć, postępuj zgodnie z przewodnikiem Wprowadzenie , w którym najpierw utworzysz interfejs API, a następnie połącz się z bazą danych SQL lub innym źródłem danych.

Tworzenie bazy danych SQL

Aby utworzyć bazę danych SQL zawierającą przykładowe dane dla interfejsu API graphQL:

  1. W obszarze roboczym Fabric wybierz pozycję Nowy element.
  2. Wybierz pozycję Baza danych SQL (wersja zapoznawcza).
  3. Podaj nazwę bazy danych.
  4. Wybierz pozycję Przykładowe dane , aby automatycznie tworzyć tabele i wypełniać je przykładowymi danymi. Spowoduje to utworzenie przykładowej bazy danych AdventureWorksLT ze schematem SalesLT, w tym tabel, takich jak SalesLT.Customer, SalesLT.Product i SalesLT.SalesOrderHeader.

Wskazówka

Jeśli masz już bazę danych SQL z przykładowymi danymi z poprzedniego samouczka lub tworzenie interfejsu API GraphQL, możesz ponownie użyć tej samej bazy danych. Pojedyncza baza danych może obsługiwać wiele interfejsów API GraphQL, dlatego nie ma potrzeby tworzenia nowej bazy danych, jeśli masz już jeden ze schematem SalesLT.

Tworzenie interfejsu API GraphQL

Teraz, gdy masz bazę danych SQL z przykładowymi danymi, utwórz interfejs API GraphQL:

  1. W bazie danych SQL wybierz pozycję Nowy interfejs API dla języka GraphQL na wstążce.

    Zrzut ekranu przedstawiający opcję Nowy interfejs API dla języka GraphQL na wstążce bazy danych SQL.

  2. Podaj nazwę interfejsu API.

  3. Wybierz wszystkie tabele SalesLT z bazy danych.

  4. Wybierz pozycję Załaduj , aby wygenerować interfejs API.

Interfejs API GraphQL jest teraz gotowy i dostępny w obszarze roboczym Fabric.

Krok 2. Konfigurowanie środowiska projektowego

Aby wykonać czynności opisane w tym samouczku, wykonaj następujące kroki, aby skonfigurować aplikację starter platformy React, zainstalować niezbędne zależności i skonfigurować program Visual Studio Code z obsługą języka GraphQL.

  1. Sklonuj aplikację startową — pobierz aplikację startową platformy React z repozytorium przykładów Microsoft Fabric:

    git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/React-Apollo-TS

  2. Zainstaluj zależności — zainstaluj wymagane pakiety na potrzeby tworzenia, autouzupełniania i generowania kodu w języku GraphQL:

    npm install

  3. Zainstaluj wymagane rozszerzenie programu Visual Studio Code — zainstaluj rozszerzenie GraphQL: obsługa funkcji językowych w programie Visual Studio Code, aby włączyć wyróżnianie składni, walidację i funkcję IntelliSense dla operacji GraphQL.

Krok 3. Konfigurowanie schematu GraphQL

Schemat graphQL definiuje strukturę interfejsu API — jakie dane są dostępne, jakie operacje można wykonać i jakie są relacje między różnymi typami danych. Narzędzia programistyczne używają tego schematu, aby zapewnić funkcję IntelliSense, uzupełnianie kodu i generowanie typów, co znacznie ułatwia pisanie poprawnych zapytań i mutacji graphQL.

Schemat GraphQL można uzyskać na dwa sposoby:

Opcja 1. Eksportowanie schematu jako pliku statycznego

  1. W swoim Fabric GraphQL API wybierz pozycję Eksportuj schemat na wstążce.
  2. Pobrana nazwa pliku zawiera identyfikator interfejsu API GraphQL (na przykład GraphQL_your-api-id_schema.graphql). Zapisz go w katalogu głównym projektu i zmień jego nazwę na schema.graphql — jest to nazwa pliku używana w kolejnych krokach konfiguracji.

Opcja 2. Używanie zdalnego punktu końcowego

  1. Uzyskaj dostęp do interfejsu API GraphQL utworzonego w Fabric Portal.
  2. Uzyskiwanie tokenu autoryzacji przy użyciu programu PowerShell za pomocą polecenia Get-PowerBIAccessToken

Uwaga / Notatka

Chociaż opcja zdalnego końca punktu zawsze zapewnia najbardziej aktualny schemat, pobrany token jest tymczasowy i ma czasowe wygaśnięcie co godzinę. Powinny one być używane tylko do celów testowania i programowania, jeśli to możliwe, użyj pliku statycznego, aby uniknąć problemów z wygaśnięciem tokenu.

Krok 4. Konfigurowanie funkcji IntelliSense i autouzupełniania

Teraz skonfigurujesz funkcję IntelliSense przy użyciu schematu z kroku 3. Plik schematu (niezależnie od tego, czy jest statyczny, czy z zdalnego punktu końcowego), umożliwia programowi VS Code dostarczanie sugestii dotyczących kodu w czasie rzeczywistym, wykrywania błędów i walidacji pól podczas pisania zapytań GraphQL.

Utwórz plik konfiguracji w katalogu głównym projektu:

Używanie pliku schematu statycznego

Użyj następującej konfiguracji, jeśli schemat został wyeksportowany jako plik statyczny:

Utwórz .graphqlrc.yml:

schema: './schema.graphql'
documents: 'src/**/*.{ts,tsx,graphql,gql}'

Używanie zdalnego punktu końcowego

Użyj następującej konfiguracji, jeśli wolisz pobrać schemat bezpośrednio z punktu końcowego interfejsu API GraphQL:

Utwórz graphql.config.yml:

schema:
  - https://your-graphql-endpoint.com/graphql:
      headers:
        Authorization: Bearer YOUR_ACCESS_TOKEN
documents: src/**/*.{ts,tsx,graphql,gql}

Opcje konfiguracji

  • schema: określa lokalizację schematu GraphQL
  • documents: określa, które pliki powinny obsługiwać funkcję IntelliSense

Po utworzeniu pliku konfiguracji uruchom ponownie program Visual Studio Code, aby upewnić się, że zmiany zostaną zastosowane.

Krok 5. Konfigurowanie generowania kodu

Generowanie kodu GraphQL automatycznie tworzy silnie typizowane interfejsy TypeScript i hooki React ze schematu i operacji, zmniejszając błędy i poprawiając efektywność rozwoju. Jego głównym celem jest zwiększenie bezpieczeństwa typów i usprawnienie programowania w projektach GraphQL, szczególnie w przypadku pracy z silnie typizowanym językami, takimi jak TypeScript.

Utwórz konfigurację codegen

Opcja pliku statycznego

Jeśli schemat został wyeksportowany jako plik statyczny, utwórz codegen.yml w katalogu głównym projektu:

schema: './schema.graphql'
documents: './src/**/*.graphql'
generates:
  src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

Opcja zdalnego punktu końcowego

Jeśli używasz podejścia zdalnego punktu końcowego, utwórz codegen.yml w katalogu głównym projektu:

schema:
  - https://your-graphql-endpoint.com/graphql:
      headers:
        Authorization: Bearer YOUR_ACCESS_TOKEN
documents: 'src/**/*.{ts,tsx,graphql,gql}'
generates:
  src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

Podział konfiguracji

  • schema: ścieżka do pliku schematu lub zdalnego punktu końcowego
  • dokumenty: wzorzec globu do lokalizowania plików operacji GraphQL
  • generates: określa plik wyjściowy dla wygenerowanego kodu
  • wtyczki: określają rodzaj kodu do wygenerowania (typy TypeScript i hooki React Apollo)

Dodaj skrypt codegen

Dodaj skrypt generowania kodu do package.json pliku w katalogu projektu (ten plik został uwzględniony podczas klonowania repozytorium w kroku 2):

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.yml"
  }
}

Krok 6. Zapisywanie operacji graphQL

Utwórz .graphql pliki w katalogu src/operations aby zdefiniować zapytania i mutacje. Funkcja IntelliSense zapewnia autouzupełnianie i walidację.

Przykłady zapytań

Utwórz src/operations/queries.graphql i wprowadź następujące zapytania:

Oto przykładowe zapytanie do pobierania danych klienta:

query GET_CUSTOMERS(
  $after: String
  $first: Int
  $filter: CustomerFilterInput
  $orderBy: CustomerOrderByInput
) {
  customers(after: $after, first: $first, filter: $filter, orderBy: $orderBy) {
    items {
      CustomerID
      FirstName
      LastName
    }
  }
}

Oto przykładowa mutacja:

mutation ADD_CUSTOMER($input: CreateCustomerInput!) {
  createCustomer(item: $input) {
    CustomerID
    FirstName
    LastName
    Title
    Phone
    PasswordHash
    PasswordSalt
    rowguid
    ModifiedDate
    NameStyle
  }
}

Krok 7. Generowanie typów i punktów zaczepienia

Uruchom polecenie generowania kodu, aby utworzyć typy języka TypeScript i haki React:

npm run codegen

Po pomyślnym zakończeniu masz wygenerowany kod w src/generated/graphql.tsx, który zawiera:

  • Interfejsy TypeScript dla wszystkich typów GraphQL
  • Silnie typizowane hooki React dla każdej operacji
  • Definicje typów danych wejściowych i wyjściowych

Krok 8. Używanie wygenerowanego kodu w składnikach react

Zaimportuj i użyj wygenerowanych punktów zaczepienia w składnikach platformy React, na przykład:

import React from 'react';
import { useGetCustomersQuery, useAddCustomerMutation } from '../generated/graphql';

const CustomersComponent: React.FC = () => {
  const { data, loading, error } = useGetCustomersQuery({
    variables: { first: 10 }
  });

  const [addCustomer] = useAddCustomerMutation();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data?.customers?.items?.map(customer => (
        <div key={customer.CustomerID}>
          {customer.FirstName} {customer.LastName}
        </div>
      ))}
    </div>
  );
};

export default CustomersComponent;

Krok 9. Konfigurowanie uwierzytelniania

Skonfiguruj uwierzytelnianie identyfikatora Entra firmy Microsoft dla aplikacji:

  1. Utwórz aplikację Microsoft Entra zgodnie z sekcją Tworzenie aplikacji Microsoft Entra w sekcji Łączenie aplikacji z Fabric API dla GraphQL.

  2. authConfig.ts Zaktualizuj plik w projekcie przy użyciu wymaganych parametrów:

export const AUTH_CONFIG = {
    clientId: "<Enter_the_Application_Id_Here>",
    tenantId: "<Enter_the_Tenant_Id_Here>",
    clientSecret: "<Enter_the_Client_Secret_Here>", //optional
}
export const GRAPHQL_ENDPOINT = '<Enter_the_GraphQL_Endpoint_Here>';

// The scope required for Fabric GraphQL API access
export const DEFAULT_SCOPE = "https://analysis.windows.net/powerbi/api/.default";

Pełny plik konfiguracji można znaleźć w przykładzie authConfig.ts w repozytorium.

Krok 10. Uruchamianie aplikacji

Uruchom serwer deweloperów:

npm run dev

Aplikacja zostanie uruchomiona w przeglądarce pod adresem http://localhost:3000. Zostanie wyświetlony monit o zalogowanie się przy użyciu poświadczeń firmy Microsoft w celu uzyskania dostępu do danych interfejsu API GraphQL. Po pomyślnym uwierzytelnieniu zobaczysz dane klienta z tabeli bazy danych SalesLT.Customer SQL fabric wyświetlanej w aplikacji React.

Treści powiązane

  • Last updated on