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

Разработка приложений GraphQL в Visual Studio Code

Узнайте, как создать интерфейсное приложение с помощью React, Клиента Apollo и TypeScript, который интегрируется с API GraphQL, размещенным в Microsoft Fabric. В этом руководстве описывается настройка локальных средств разработки, включая автозавершение, создание кода и IntelliSense для оптимального интерфейса разработчика.

Кто должен использовать средства разработки VS Code

Локальная разработка с помощью VS Code предназначена для:

  • Разработчики React, создающие веб-приложения, которые используют данные из Fabric lakehouse и хранилищ данных через GraphQL.
  • Разработчики TypeScript, которым нужна генерация типобезопасного клиентского кода для API GraphQL Fabric
  • Фулл-стек разработчики разработки аналитических пользовательских приложений на основе платформы Fabric с поддержкой локальной интегрированной среды разработки
  • Команды разработчиков , которые хотят использовать современные инструменты с IntelliSense и отладкой приложений для доступа к данным Fabric

Используйте этот подход при создании приложений React, требующих полной поддержки интегрированной среды разработки, создания кода и локальных возможностей отладки с помощью TypeScript и Apollo Client.

Предпосылки

Прежде чем начать, убедитесь, что у вас есть следующее:

  • Доступ к рабочей области Microsoft Fabric: быть членом рабочей области Fabric с по крайней мере ролью участника (или более поздней: администратор, член) для создания и изменения элементов API GraphQL
  • Разрешения источника данных: разрешения на чтение и запись в источниках данных, которые вы планируете предоставлять через API GraphQL
  • Node.js установлен на компьютере разработки (включает npm)
  • Visual Studio Code, установленный на машине разработчика
  • Основные знания о понятиях React, TypeScript и GraphQL

Шаг 1. Создание API GraphQL в Microsoft Fabric

Замечание

В этом руководстве показано создание API GraphQL из контекста базы данных SQL. Сначала вы создаете базу данных SQL, а затем создаете API GraphQL непосредственно из этой базы данных. Если у вас уже есть существующий API GraphQL и вы хотите подключиться к нему, следуйте руководству по началу работы , где сначала создается API, а затем подключитесь к базе данных SQL или другому источнику данных.

Создание базы данных SQL

Чтобы создать базу данных SQL, содержащую примеры данных для API GraphQL:

  1. В рабочей области Fabric выберите новый элемент.
  2. Выберите базу данных SQL (предварительная версия).
  3. Укажите имя базы данных.
  4. Выберите примеры данных , чтобы автоматически создавать таблицы и заполнять их примерами данных. При этом создается пример базы данных AdventureWorksLT с схемой SalesLT, включая таблицы SalesLT.Customer, SalesLT.Product и SalesLT.SalesOrderHeader.

Подсказка

Если у вас уже есть база данных SQL с примерами данных из предыдущего руководства или создания API GraphQL, можно повторно использовать ту же базу данных. Одна база данных может поддерживать несколько API GraphQL, поэтому вам не нужно создавать новую базу данных, если у вас уже есть схема SalesLT.

Создание API GraphQL

Теперь, когда у вас есть база данных SQL с примерами данных, создайте API GraphQL:

  1. В базе данных SQL выберите новый API для GraphQL на ленте.

    Снимок экрана: параметр New API for GraphQL на ленте базы данных SQL.

  2. Укажите имя API.

  3. Выберите все таблицы SalesLT из базы данных.

  4. Выберите "Загрузить ", чтобы создать API.

API GraphQL теперь готов и доступен в рабочей области Fabric.

Шаг 2. Настройка среды разработки

Чтобы выполнить инструкции вместе с этим руководством, выполните следующие действия, чтобы настроить начальное приложение React, установить необходимые зависимости и настроить Visual Studio Code с поддержкой GraphQL.

  1. Клонируйте начальное приложение, получите начальное приложение React из репозитория примеров Microsoft Fabric:

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

  2. Установите зависимости. Установите необходимые пакеты для разработки GraphQL, автозаполнения и создания кода:

    npm install

  3. Установите необходимое расширение Visual Studio Code. Установите расширениеGraphQL: расширение поддержки функций языка в Visual Studio Code, чтобы включить выделение синтаксиса, проверку и IntelliSense для операций GraphQL.

Шаг 3. Настройка схемы GraphQL

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

Схему GraphQL можно получить двумя способами:

Вариант 1. Экспорт схемы в виде статического файла

  1. В API GraphQL Fabric выберите "Экспорт схемы " на ленте.
  2. Скачанный файл содержит идентификатор API GraphQL (например, GraphQL_your-api-id_schema.graphql). Сохраните его в корневом каталоге проекта и переименуйте его schema.graphql в . Это имя файла, которое вы используете в следующих шагах конфигурации.

Вариант 2. Использование удаленной конечной точки

  1. Доступ к API GraphQL, созданному на портале Fabric.
  2. Получение маркера авторизации с помощью PowerShell с Get-PowerBIAccessToken

Замечание

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

Шаг 4. Настройка IntelliSense и автозаполнения

Теперь вы настроите IntelliSense с помощью схемы на шаге 3. Файл схемы (статический или из удаленной конечной точки) позволяет VS Code предоставлять предложения кода в режиме реального времени, обнаружение ошибок и проверку полей при написании запросов GraphQL.

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

Использование файла статической схемы

Используйте следующую конфигурацию, если вы экспортировали схему в виде статического файла:

Создание .graphqlrc.yml:

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

Использование удаленной конечной точки

Используйте следующую конфигурацию, если вы предпочитаете получить схему непосредственно из конечной точки API GraphQL:

Создание graphql.config.yml:

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

Параметры конфигурации

  • схема: указывает расположение схемы GraphQL
  • документы: определяет, какие файлы должны поддерживать IntelliSense

После создания файла конфигурации перезапустите Visual Studio Code, чтобы убедиться, что изменения вступили в силу.

Шаг 5. Настройка создания кода

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

Создание конфигурации codegen

Параметр статического файла

Если вы экспортировали схему в виде статического файла, создайте codegen.yml в корневом каталоге проекта:

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

Параметр удаленной конечной точки

Если вы используете подход с удаленной конечной точкой, создайте codegen.yml в корневом каталоге вашего проекта:

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

Разбивка конфигурации

  • схема: Путь к файлу схемы или удаленной конечной точке
  • документы: шаблон Glob для поиска файлов операций GraphQL
  • создает: указывает выходной файл для созданного кода.
  • подключаемые модули: определяет, какой код нужно создать (типы TypeScript и перехватчики React Apollo)

Добавление скрипта codegen

Добавьте скрипт package.json создания кода в файл в каталоге проекта (этот файл был включен при клонирование репозитория на шаге 2):

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

Шаг 6. Запись операций GraphQL

Создайте .graphql файлы в src/operations каталоге, чтобы определить запросы и изменения. IntelliSense обеспечивает автозавершение и проверку.

Примеры запросов

Создайте src/operations/queries.graphql и введите следующие запросы:

Ниже приведен пример запроса для получения данных клиента:

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

Ниже приведен пример изменения:

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

Шаг 7. Создание типов и перехватчиков

Выполните команду создания кода, чтобы создать типы TypeScript и перехватчики React:

npm run codegen

После успешного завершения у вас есть созданный код, src/generated/graphql.tsx содержащий следующее:

  • Интерфейсы TypeScript для всех типов GraphQL
  • Строго типизированные перехватчики React для каждой операции
  • Определения входных и выходных типов

Шаг 8. Использование созданного кода в компонентах React

Импортируйте и используйте созданные перехватчики в компонентах React, например:

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;

Шаг 9. Настройка проверки подлинности

Настройте проверку подлинности идентификатора Microsoft Entra для приложения:

  1. Создайте приложение Microsoft Entra после раздела "Создание приложения Microsoft Entra " в разделе "Подключение приложений к API Fabric для GraphQL".

  2. authConfig.ts Обновите файл в проекте с необходимыми параметрами:

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";

Полный файл конфигурации см. в примере authConfig.ts в репозитории.

Шаг 10. Запуск приложения

Запустите сервер разработки:

npm run dev

Приложение откроется в браузере по адресу http://localhost:3000. Вам будет предложено войти с помощью учетных данных Майкрософт для доступа к данным API GraphQL. После успешной проверки подлинности вы увидите данные клиента из таблицы базы данных SalesLT.Customer SQL Fabric, отображаемой в приложении React.

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

  • Last updated on