Системы контроля версий и цепочки развертывания в API для GraphQL

Узнайте, как конвейеры интеграции и развертывания Git работают с API для GraphQL в Microsoft Fabric. В этой статье показано, как настроить подключение к репозиторию, управлять API для GraphQL и развертывать их в разных средах.

Кто использует системы управления версиями и развертывание

Конвейеры интеграции и развертывания Git важны для:

• Инженеры данных управляют конфигурациями API GraphQL Fabric с помощью управления версиями и рабочих процессов CI/CD
• Администраторы рабочей области Fabric координируют развертывания в рабочих областях разработки, тестирования и производства Fabric.
• Команды DevOps , реализующие конвейеры развертывания для API Fabric в нескольких средах и емкостях
• Команды платформы , требующие возможностей управления, отслеживания и отката для изменений API Fabric

Используйте конвейеры управления версиями и развертывания, если необходимо управлять API GraphQL в рамках структурированного жизненного цикла разработки с несколькими средами.

Предпосылки

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

Обзор

Fabric предлагает мощные инструменты для CI/CD (непрерывная интеграция и непрерывное развертывание) и управления жизненным циклом разработки с помощью двух основных компонентов: интеграции Git (CI) и конвейеров развертывания (CD). Рабочие области служат центральными компонентами для этапов синхронизации и развертывания Git.

Интеграция Git (CI): синхронизирует элементы рабочей области (например, код, конфигурации, API) с репозиториями управления версиями, включив управление версиями и отслеживание изменений с помощью Git.

Конвейеры развертывания (CD): включает создание этапов (например, разработка, тестирование, производство) с связанными рабочими областями. Элементы, поддерживаемые на каждом этапе, автоматически реплицируются на последующие этапы, а изменения в рабочей области запускают развертывание в процессе выпуска. Конвейер можно настроить, чтобы убедиться, что изменения тестируются и развертываются эффективно в разных средах.

Fabric поддерживает различные рабочие процессы CI/CD, адаптированные к общим сценариям. Дополнительные сведения см. в разделе "Параметры рабочего процесса CI/CD" в Fabric.

Элементы рабочей области хранятся в ассоциированном репозитории Git как Инфраструктура как код (Infrastructure as Code, IaC). Изменения кода в репозитории могут активировать развертывание в конвейерах. Этот метод позволяет автоматически реплицировать изменения кода на этапах тестирования и выпуска рабочей среды.

Методы проверки подлинности источника данных

При создании API для GraphQL вы выбираете способ проверки подлинности клиентов и доступа к источникам данных. Этот выбор имеет значительные последствия для конвейеров развертывания и автоматической привязки. Понимание этих методов проверки подлинности является важным для планирования рабочего процесса CI/CD. Дополнительные сведения об автоматической привязке и процессе развертывания см. в разделе "Общие сведения о процессе развертывания".

При подключении источников данных к API для GraphQL доступны два варианта подключения: единый вход (SSO) и сохраненные учетные данные.

Единый вход (SSO)

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

Используйте SSO, если:

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

Требования к разрешениям:

• Пользователям API требуются разрешения на выполнение в API GraphQL (выполнение запросов и мутаций)
• Пользователям API требуются разрешения на чтение или запись в источнике данных
• Кроме того, добавьте пользователей в качестве участников рабочей области с ролью участника , где находятся КАК API, так и источник данных

Автоматическое связывание в конвейерах развертывания: При развертывании API с помощью SSO из исходной рабочей области (например, Dev) в целевую рабочую область (например, Test):

• Источник данных и API GraphQL развертываются в целевой рабочей области.
• API в целевой рабочей области автоматически привязывается к локальной копии источника данных в целевой рабочей области.
• Каждая среда (Dev, Test, Production) использует собственный экземпляр источника данных

Сохраненные учетные данные

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

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

• Предоставление источников данных Azure (база данных SQL Azure, внешние базы данных)
• Требуется упрощенное управление разрешениями (пользователям требуется доступ только к API)
• Все пользователи API должны получить доступ к одинаковым данным с одинаковыми разрешениями
• Необходимы согласованные учетные данные во всех запросах API

Требования к разрешениям:

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

Автоматическое связывание в конвейерах развертывания: При развертывании API с помощью сохраненных учетных данных из исходной рабочей области (Dev) в целевую рабочую область (Test):

• Источник данных развертывается в целевой рабочей области
• API в целевой рабочей области остается подключенным к источнику данных в исходной рабочей области (Dev)
• Автоматическое связывание не происходит . Развернутый API продолжает использовать сохраненные учетные данные, указывающие на исходный источник данных.
• Необходимо вручную перенастроить подключения или создать новые сохраненные учетные данные в каждой целевой среде.

Подключения между рабочими областями

Если API в исходной рабочей области (Dev) подключается к источнику данных в другой рабочей области, развернутый API в целевой рабочей области (тест) остается подключенным к внешнему источнику данных независимо от метода проверки подлинности. Автоматическая привязка работает только в том случае, если API и источник данных находятся в одной исходной рабочей области.

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

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

API для интеграции Git с GraphQL

API Fabric для GraphQL поддерживает интеграцию Git, позволяя управлять API GraphQL в виде кода в системе управления версиями. Эта интеграция обеспечивает историю версий, совместную работу с помощью ветвей и пулл-реквестов, возможность отмены изменений и полный аудит изменений API. Используя конфигурацию API GraphQL как инфраструктуру как код (IaC), вы можете применить рекомендации по разработке программного обеспечения к уровню доступа к данным.

Интеграция Git необходима для:

• Управление версиями. Отслеживание всех изменений схемы GraphQL, подключений к источнику данных и связей с течением времени
• Совместная работа: сотрудничество с членами команды с помощью ветвей, пулл-реквестов и проверки кода
• Возможность отката: возврат к предыдущим конфигурациям API при возникновении проблем
• Продвижение среды: Использование Git в качестве источника истины для развертывания API в различных средах

Подключение рабочей области к Git

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

1. Откройте настройки рабочей области для рабочей области, содержащей ваш API для GraphQL
2. Настройте подключение Git к репозиторию (Azure DevOps, GitHub или другой поставщик Git)
3. После подключения все элементы рабочей области, включая API для GraphQL, отображаются на панели управления версиями

Подробные инструкции по настройке см. в статье "Начало работы с интеграцией Git".

Подтверждение и синхронизация ваших API GraphQL

После подключения к Git можно зафиксировать конфигурации API для GraphQL в репозитории. Каждый коммит создает снимок определения вашего API, включая:

• Определения схемы GraphQL
• Подключения к источнику данных и параметры проверки подлинности
• Конфигурации связей
• Определения запросов и мутаций

После фиксации API GraphQL отображаются в репозитории Git с структурированной иерархией папок. На этом этапе можно использовать стандартные рабочие процессы Git, такие как создание pull-запросов, управление ветвями и совместная работа с командой с помощью отзывов о коде. Дополнительные сведения о работе с ветвями см. в разделе "Управление ветвями".

Представление API GraphQL в Git

Каждый API-интерфейс для элемента GraphQL хранится в Git с четко определенной структурой папок, которая представляет все аспекты конфигурации вашего API.

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

Работа с файлами определения API:

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

• Проверки кода: участники команды могут просматривать изменения API в pull request'ах
• Документация. Файлы служат документацией по структуре API
• Автоматизация: конвейеры CI/CD могут считывать эти файлы, чтобы понять конфигурации API
• Аварийное восстановление: полные определения API сохраняются в элементе управления версиями

Подробные сведения о формате определения API GraphQL, синтаксисе и примерах см. в документации по API плоскости управления Fabric:

• Определение API GraphQL
• Создание GraphQLApi с помощью примера общедоступного определения

API для GraphQL в потоке развертывания

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

Основные рекомендации по развертыванию:

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

• API, использующие Единый вход (SSO), могут автоматически привязываться к локальным источникам данных в целевой рабочей области (если источник данных также был развернут из той же исходной рабочей области).
• API-интерфейсы, применяющие сохраненные учетные данные, не подключаются автоматически и остаются подключёнными к источнику данных рабочей области-источника.
• Источники данных межрабочих областей никогда не привязываются автоматически, независимо от метода проверки подлинности

Полное представление о процессе развертывания см. в разделе "Общие сведения о процессе развертывания".

Развертывание API для GraphQL

Чтобы развернуть API для GraphQL с помощью конвейеров развертывания:

1. Создайте новый конвейер развертывания или откройте существующий. Для получения подробных инструкций см. статью "Get started with deployment pipelines".

2. Назначьте рабочие области этапам конвейера (разработка, тестирование, производство) на основе стратегии развертывания. Каждый этап должен иметь выделенную рабочую область.

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

   

4. Выберите API для GraphQL и все связанные элементы (например, подключенные источники данных), которые требуется развернуть. Затем выберите "Развернуть" , чтобы переместить их на следующий этап.

   

5. Просмотрите диалоговое окно подтверждения развертывания, в котором отображаются все элементы, которые будут развернуты. Выберите Развернуть, чтобы продолжить.

   

Текущие ограничения

При развертывании API для GraphQL с помощью конвейеров развертывания автобинирование имеет следующие ограничения:

• Дочерние элементы: автоматическая привязка не работает, когда API подключается к конечной точке аналитики SQL, которая является дочерним элементом родительского источника данных (например, Lakehouse). Развернутый API остается подключенным к конечной точке исходной рабочей области.

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

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

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

• Что такое API Microsoft Fabric для GraphQL?
• Создание и добавление данных в API для GraphQL
• Интеграция Git
• Цепочки развертывания
• Параметры рабочего процесса CI/CD в Fabric