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

API Fabric для анализа и экспорта схем GraphQL

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

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

Подсказка

Хотите увидеть интроспектацию в действии? Ознакомьтесь с руководством по подключению агентов ИИ к API Fabric для GraphQL с локальным сервером протокола контекста модели (MCP). В этом практическом руководстве показано, как агенты ИИ используют интроспекцию для автоматического обнаружения и запроса данных Fabric с помощью естественного языка.

Кто использует интроспекцию и экспорт схемы

Интроспекция и экспорт схем ценны для:

  • Разработчики приложений создающие клиентов, использующих данные Fabric, для чего необходимо создавать типобезопасный код
  • Участники рабочей области Fabric понимают доступные структуры данных и тестируют доступ к данным
  • Средства разработки и интегрированные среды разработки, обеспечивающие автозавершение и IntelliSense для GraphQL API Fabric
  • Интеграции Azure API Management, которые маршрутизируют и защищают трафик GraphQL Fabric на корпоративном уровне
  • Администраторы Фабрики проводят аудит открытых структур данных и проверку элементов управления доступом
  • Агенты ИИ и помощники используют протокол MCP для естественного обнаружения и запроса данных Fabric.
  • Разработчики Power Platform понимают схемы данных Fabric перед созданием интеграции
  • Конвейеры CI/CD отслеживают версии схемы GraphQL Fabric и проверяют совместимость между средами

Выбирайте интроспекцию, когда необходимо запрашивать информацию о схеме программным способом во время выполнения, например для обеспечения работы инструментов разработки, активации агентов ИИ или реализации динамических клиентских функций. Выберите экспорт схемы , если требуется полный файл схемы для автономного использования, управления версиями, интеграции шлюза API или совместного использования с внешними командами.

  • Introspection: запросите вашу схему программным методом с помощью системы интроспекции GraphQL, которая является частью стандарта GraphQL. Запросы интроспекции позволяют динамически обнаруживать типы, поля и связи, а также использовать множество средств разработки GraphQL.

  • Экспорт схемы. Скачайте полный файл SDL (язык определения схемы GraphQL), содержащий полное определение схемы для автономного использования, совместного использования или интеграции инструментов.

Самоанализ

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

Чтобы включить интроспекцию, выполните указанные действия.

  1. Щелкните значок параметров API в виде шестеренки в верхнем меню.

    Снимок экрана: панель портала с кнопкой шестеренки параметров.

  2. В области навигации слева выберите страницу Интроспекция.

    Снимок экрана: ползунок параметра интроспекции.

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

  4. Открывается диалог запроса подтверждения. Нажмите кнопку "Подтвердить" , чтобы включить интроспекцию или отмену , чтобы оставить ее отключенной.

    Снимок экрана: диалоговое окно подтверждения включения интроспекции.

Пример запроса introspection

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

  1. Создайте новый запрос в редакторе GraphQL. Щелкните значок плюса + рядом с существующими вкладками, чтобы открыть новую вкладку запроса.

    Снимок экрана: кнопка нового запроса в редакторе GraphQL.

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

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Нажмите кнопку "Выполнить ", чтобы выполнить запрос.

  4. В области результатов отображается список всех типов, определенных в схеме.

    Снимок экрана: пример запроса интроспекции.

Запросы интроспекции могут возвращать большие объемы информации. Вы можете сузить область запроса, сделав более конкретным ваш инспекционный запрос. Например, вместо запроса всех типов можно запросить конкретный тип:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Выполнение запроса возвращает подробные сведения о типе ProductCategory :

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

Распространенные шаблоны фильтрации при обработке результатов интроспекции включают:

  • Исключая типы, начинающиеся с двойного подчеркивания (__), которые являются системными типами GraphQL.
  • Включение типов, начиная с определенных префиксов, таких как ProductCategory

В этих примерах показан стандартный синтаксис интроспекции GraphQL, который работает в любой из реализаций GraphQL. В этом обзоре рассматриваются основные шаблоны интроспекции— подробные сведения о системе интроспекции, расширенных методах запроса и дополнительных возможностях, см. официальную документацию GraphQL Foundation по интроспекции.

Экспорт схемы

Когда вам потребуется полная автономная копия определения схемы, используйте функцию экспорта схемы непосредственно на портале Fabric. Откройте API для GraphQL и выберите "Экспорт схемы " на панели инструментов. Браузер скачивает файл SDL (язык определения схемы), содержащий полное определение схемы.

Снимок экрана: кнопка экспорта схемы.

Общие сведения о файле SDL

Экспортируемый файл использует язык определения схемы GraphQL (SDL), удобочитаемый человеком формат, определяющий типы, поля и связи API. Файл SDL включает:

  • Типы объектов , представляющие сущности данных с их полями
  • Операции запроса , определяющие способ извлечения данных
  • Операции мутации для создания, обновления или удаления данных
  • Аргументы поля, определяющие входные параметры и их типы
  • Описания типов , предоставляющие документацию для каждого элемента

Чтобы просмотреть структуру схемы, можно открыть SDL-файл в любом текстовом редакторе. Это особенно полезно для понимания полной поверхности API перед интеграцией его в приложения.

Использование экспортируемой схемы

Распространенные варианты использования экспортированного SDL-файла:

  • Интеграция шлюза API: импорт в службу управления API Azure для добавления проверки подлинности, ограничения скорости и кэширования
  • Настройка среды разработки: настройка IntelliSense в Visual Studio Code для автозаполнения и проверки
  • Управление версиями: фиксация в Git или других системах управления версиями для отслеживания эволюции схемы с течением времени
  • Совместная работа с командой. Предоставление общего доступа внешним партнерам или командам разработчиков, которым необходимо понять структуру API
  • Создание кода. Использование генераторов кода GraphQL для создания типобезопасных клиентов в TypeScript, C#, Java или других языках
  • Документация. Создание справочной документации по API с помощью таких средств, как GraphQL Voyager или GraphQL Markdown

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

Управление изменениями схемы

Схемы GraphQL могут развиваться с течением времени при добавлении новых типов, полей или возможностей в API. При изменении схемы экспортированные файлы SDL становятся устаревшими. Рассмотрим следующие методики:

  • Повторно экспортируйте после изменений: скачайте новый SDL-файл всякий раз, когда вы изменяете схему API в Fabric. Изменения схемы включают добавление источников данных, изменение предоставляемых типов или обновление определений полей.
  • Управление версиями: зафиксируйте каждую экспортированную схему в систему управления версиями с описательными сообщениями коммита. Это создает журнал изменений эволюции схемы и позволяет выполнить откат при необходимости.
  • Обмен данными. Если внешние команды или приложения зависят от схемы, сообщите им о существенных изменениях. Хотя GraphQL поддерживает аддитивные изменения без нарушения существующих запросов, удаление или переименование полей может повлиять на клиенты.
  • Автоматизация. Для конвейеров CI/CD рекомендуется автоматизировать экспорт схемы в рамках процесса развертывания, чтобы обеспечить синхронизацию документации и инструментов с API.

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

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

  • Last updated on