🚀 CI/CD для Microsoft Fabric с помощью Azure DevOps и fabric-cicd пакета Python

В этом руководстве вы используете библиотеку Python fabric-cicd для перемещения измененных элементов (например, конкретной записной книжки) из рабочей области разработки в тестовую рабочую область и в конечном итоге в производственную.

1. Обзор сценария

Познакомьтесь с Алексом — ведущим разработчиком, работающим с Microsoft Fabric.

Команда Алекса создает записные книжки, конвейеры данных, семантические модели и отчеты в рабочей области development Fabric. Когда функции готовы, Алекс должен продвигать измененные элементы (например, определенную записную книжку) из рабочей области разработки в тестовую рабочую область, а в конечном итоге в рабочую область прод.

Задача

Записные книжки Алекса используют магическую %%configure команду для присоединения к конкретному Lakehouse. Это означает, что определения блокнота содержат жесткие идентификаторы GUID — идентификаторы рабочих областей, идентификаторы Lakehouse и идентификаторы конечных точек SQL, которые различаются в каждой среде.

Что ожидает Алекс

Требование Решение
Разверните измененные элементы, объединенные в ветвь fabric-cicd publish_all_items() Развертывает все виды элементов в рамках области охвата
Явное определение типа элемента Параметр items_in_scope конвейера — необходимо указать, какие типы элементов необходимо развернуть
Рабочий процесс утверждения перед развертыванием в test/prod Среды ADO с утверждающими шлюзами
Автоматическая смена GUID (разработка → тест/продакшн) fabric-cicd файлы параметров (parameter.yml)
Безопасное управление учетными данными Azure Key Vault и группы переменных ADO
Автоматический триггер при слиянии в ветвь Конвейер ADO с триггерами веток

Средства

Tool Цель
Azure DevOps (ADO) Оркестрация CI/CD, размещение Git, утверждения
fabric-cicd Пакет Python Библиотека с открытым кодом Майкрософт для развертывания элементов Fabric
Azure Key Vault Надежно сохраняет учетные данные сервисного принципала
Субъект-служба (SPN) Выполняет аутентификацию через API Fabric REST

2. Схема архитектуры

На следующей схеме показана структура учебника.

Концептуальный поток архитектуры учебника.

3. Предварительные требования

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

# Предпосылка Сведения
1 Организация и проект Azure DevOps Проект с включенными репозиториями и конвейерами
2 Рабочие области Microsoft Fabric Три рабочих области — по одному для разработки, тестирования и prod
3 Субъект-служба (SPN) Регистрация приложения в Entra ID (Azure AD) с секретом клиента
4 Разрешения SPN в Fabric SPN необходимо добавить в каждую целевую рабочую область Fabric в качестве участника или администратора.
5 Azure Key Vault Хранилище ключей с тремя секретами: Идентификатор арендатора, идентификатор клиента и секрет клиента.
6 Интеграция Fabric Git Рабочее пространство dev должно быть подключено к dev ветви репозитория ADO
7 Python 3.12+ Используется агентом конвейера для выполнения скрипта развертывания
8 fabric-cicd Пакет Python Библиотека развертывания с открытым кодом Майкрософт (PyPI)
9 Параметры администратора Fabric для имени основного объекта службы Администратор Fabric должен включить "Субъекты-службы могут использовать API Fabric" на портале администрирования Fabric в разделе "Параметры клиента"

💡 Совет: Чтобы включить доступ для сервисного принципала в Fabric, администратор Fabric должен активировать параметр "Сервисные принципалы могут использовать API Fabric" на портале администрирования Fabric в разделе "Параметры клиента".

Скачивание исходных файлов

  1. Создайте форк репозитория Fabric-samples в вашем аккаунте GitHub.
  2. Клонируйте форк на ваш локальный компьютер.
git clone https://github.com/<your-account>/fabric-samples.git
cd fabric-samples

4. Начальная настройка Azure DevOps

В этом разделе описаны все ресурсы Azure DevOps, которые необходимо настроить перед запуском конвейера.


4.1 Интеграция Azure Key Vault

Учетные данные учетной записи службы (идентификатор арендатора, идентификатор клиента и секрет) никогда не должны храниться в виде обычного текста. Вместо этого сохраните их в Azure Key Vault.

Действия по настройке Azure Key Vault

  1. Создайте Key Vault на портале Azure (или используйте существующую).
  2. Добавьте три секрета:
Имя секрета Description Пример значения
aztenantid Идентификатор клиента Azure AD / Entra ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
azclientid Идентификатор приложения сервисного принципала (клиент) xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
azspnsecret Значение секрета клиента субъекта-службы your-secret-value
  1. Предоставление доступа: Подключение службы ADO (или удостоверение проекта ADO) должно иметь разрешения на получение и перечисление секретов в политиках доступа Key Vault (или роли Key Vault Secrets UserRBAC).

    Снимок экрана: добавление переменных в конвейер.


4.2 Группа переменных: fabric_cicd_group_sensitive

Эта группа переменных связана с Azure Key Vault, т. е. значения секретов извлекаются во время выполнения и никогда не предоставляются в пользовательском интерфейсе ADO.

Шаги для создания

  1. Перейдите в библиотеку конвейеров → в проекте ADO.
  2. Нажмите + Группа переменных.
  3. Назовите его: fabric_cicd_group_sensitive
  4. Включите опцию Использовать секреты из хранилища ключей Azure как переменные.
  5. Выберите подписку Azure и Key Vault.
  6. Нажмите кнопку +Добавить и выберите три секрета:
  • aztenantid
  • azclientid
  • azspnsecret
  1. Нажмите кнопку Сохранить.
Variable Исходный материал Чувствительный?
aztenantid Azure Key Vault ✅ Да
azclientid Azure Key Vault ✅ Да
azspnsecret Azure Key Vault ✅ Да

Снимок экрана: группа переменных.

Это важно

Так как эти переменные связаны с Key Vault, доступ к ним выполняется в YAML конвейера как $(aztenantid), $(azclientid) и $(azspnsecret). Они автоматически маскируются в журналах.


4.3 Группа переменных: fabric_cicd_group_non_sensitive

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

Шаги по созданию

  1. Перейдите в библиотеку конвейеров → в проекте ADO.
  2. Нажмите + Группа переменных.
  3. Назовите его: fabric_cicd_group_non_sensitive
  4. Добавьте следующие переменные:
Имя переменной Ценность Description
devWorkspaceName MyProject-Dev Имя рабочей области DEV Fabric
testWorkspaceName MyProject-Test Имя рабочей области TEST Fabric
prodWorkspaceName MyProject-Prod Имя рабочей области PROD Fabric
gitDirectory fabric Папка в репозитории, содержащая определения элементов Fabric
  1. Нажмите кнопку Сохранить.

    Снимок экрана: группа нечувствительных переменных.

💡 Как это работает в коде: Скрипт Python считывает эти значения с помощью os.environ. Например, при развертывании на test в скрипте создается имя переменной testWorkspaceName, преобразуется в верхний регистр (TESTWORKSPACENAME) и считывается из среды, поскольку ADO автоматически внедряет значения группы нечувствительных переменных в качестве переменных среды в верхнем регистре.


4.4 Среды ADO и шлюзы утверждения

Среды ADO позволяют добавлять проверки утверждения вручную перед продолжением развертывания. Это важно для продвижения к test и prod.

Действия по созданию сред

  1. Перейдите к Конвейеры → Среды в проекте ADO.
  2. Создайте три среды с точными именами , соответствующими именам ветви:
Название окружения Требуется утверждение? Утверждающие
dev ❌ Нет (автоматическое развертывание)
test ✅ Да Команда администрирования / ведущий
prod ✅ Да Команда администрирования / ведущий
  1. Для test и prod, нажмите на среду → ⋮ (Дополнительные параметры) Утверждения и проверки+ Добавить проверкуУтверждения.

  2. Добавьте требуемых утверждающих лиц.

    Снимок экрана: среды ado.

Пример представления состояния среды:

Окружающая среда Состояние
разработчик ✅ #20260211.1 на fabric_cicd_pipeline
test ✅ #20260216.8 на fabric_cicd_pipeline
продакшен ✅ #20260131.12 на fabric_cicd_pipeline

💡 Почему среды? В YAML-конвейере используются задания с deploymentenvironment: $(target_env). Когда target_env равняется test или prod, ADO приостанавливает поток и ожидает утверждения предварительно настроенных утверждающих перед продолжением.


Стратегия веток Git 4.5

Стратегия ветвления имеет ключевое значение для этой установки CI/CD. Вам потребуется три длительно существующих ветви:

Концептуальная схема стратегии ветвления.

Основные моменты

Branch Подключено к рабочей области Fabric? Цель
dev "Да" синхронизировано с рабочей областью DEV Источник истины. Изменения, внесенные в рабочую область РАЗРАБОТКи, фиксируются здесь.
test Нет Получает продвигаемые элементы через слияние PR. Отслеживает, что развернуто в TEST.
prod Нет Получает продвигаемые элементы через слияние PR. Отслеживает, что развернуто в PROD.

Почему подключено только dev

  • Интеграция Fabric с Git двунаправленно синхронизирует элементы рабочей области с ветвью Git.
  • Ветви test и prodне подключены к рабочим областям, так как пакет fabric-cicd обрабатывает развертывание непосредственно через REST API Fabric.
  • Эти ветви служат учетом того, какие версии элементов были размещены в каждой среде.

Настройка конвейера ADO 4.6

Создайте конвейер в ADO, который ссылается на ФАЙЛ YAML в репозитории.

Этапы

  1. Перейдите к конвейерам → Конвейеры →новый конвейер.
  2. Выберите Azure Repos Git и выберите репозиторий.
  3. Выберите существующий YAML-файл Azure Pipelines.
  4. Наведите указатель на путь: Deploy-To-Fabric.yml (или туда, куда вы его разместили).
  5. Присвойте конвейеру имя. fabric_cicd_pipeline
  6. В разделе "Разрешения конвейера" убедитесь, что у него есть доступ к:
  • Обе группы переменных (fabric_cicd_group_sensitive и fabric_cicd_group_non_sensitive)
  • Все три среды (dev, test, prod)
  1. Сохраните (пока не запускайте).

️ Совет по разрешениям: При первом запуске конвейера может потребоваться разрешить доступ ADO к группам переменных и средам. Администратор ADO может предварительно авторизовать эти параметры в разделе "Параметры конвейера →".


5. Глубокое погружение кода: ADO Pipeline YAML

Файл:Deploy-To-Fabric.yml- находится в репозитории GitHub, скачанном ранее.

Ниже приведен полный пиплайн с построчными аннотациями.

# ──────────────────────────────────────────────────────────────
# TRIGGER: Runs automatically when code is pushed to dev, test, or prod
# Only triggers when changes are in the "fabric/" folder
# ──────────────────────────────────────────────────────────────
trigger:
 branches:
 include: [test, prod]
 paths:
 include:
  - fabric/**

🔍 Объяснение-Триггер

  • Конвейер автоматически запускается при фиксациях в ветках test или prod. Он не активируется из-за devтого, что dev исходная ветвь подключена к интеграции Fabric Git.
  • Фильтр paths гарантирует, что он активируется только при изменении файлов в fabric/ каталоге, что предотвращает ненужные запуски из-за изменений в документации, скриптах и т. д.
  • На практике: при объединении PR из dev в test коммит слияния попадает на ветку test, активируя конвейер, нацеленный на среду TEST.

# ──────────────────────────────────────────────────────────────
# PARAMETERS: Runtime input-which Fabric item types to deploy
# ──────────────────────────────────────────────────────────────
parameters:
 - name: items_in_scope
 displayName: Enter Fabric items to be deployed
 type: string
 default: '["Notebook","DataPipeline","Lakehouse","SemanticModel","Report","VariableLibrary"]'

🔍 Пояснение-Параметры

  • Это определяет параметр среды выполнения , который определяет, какие типы элементов Fabric находятся в области развертывания.
  • Если этот параметр не указан, все типы элементов, поддерживаемые пакетом fabric-cicd , будут развернуты.
  • Это также служит вариантом выборочного развертывания, например, можно передать только ["Notebook"], чтобы развернуть только ноутбуки.

⚠️ Предупреждение о выборочном развертывании: Если вы сузите items_in_scope в процессе выборочного развертывания, не следует вызывать unpublish_all_orphan_items() в скрипте Python, так как он удаляет элементы указанных в items_in_scope типов, которые существуют в рабочей области, но отсутствуют в ветке релиза. Например, если вы развертываете только ["Notebook"], и в рабочей области есть записные книжки, отсутствующие в ветви, они будут удалены, даже если они всё ещё могут быть актуальными. Он не удаляет элементы других типов (например, конвейеры, отчеты и т. д.). Используйте unpublish_all_orphan_items() только в том случае, если ветвь представляет полное требуемое состояние для типов элементов в данной области.


# ──────────────────────────────────────────────────────────────
# VARIABLES: Environment-specific config & secrets
# ──────────────────────────────────────────────────────────────
variables:
 - name: target_env
 value: ${{ replace(variables['Build.SourceBranch'], 'refs/heads/', '') }}
 - group: fabric_cicd_group_sensitive
 - group: fabric_cicd_group_non_sensitive

🔍 Объясняющие переменные

Variable Принцип работы
target_env Динамически извлекает имя ветви из Build.SourceBranch. Например, refs/heads/testtest. Эта отдельная переменная управляет всем поведением с учетом среды.
fabric_cicd_group_sensitive Извлекает aztenantid, azclientid и azspnsecret из Azure Key Vault во время выполнения.
fabric_cicd_group_non_sensitive Извлекает имена рабочих областей и gitDirectory в виде простейших переменных среды.

# ──────────────────────────────────────────────────────────────
# STAGES & JOBS: Single deployment stage
# ──────────────────────────────────────────────────────────────
stages:
 - stage: DeployToFabric
 displayName: "Deploy to Fabric Workspace"
 jobs:
  - deployment: Deployment
  displayName: "Deploy Resources"
  environment: $(target_env)  # ◀── THIS triggers the approval gate!
  pool:
   name: Azure Pipelines
  strategy:
   runOnce:
   deploy:
    steps:

🔍 Задание Explanation-Deployment

Элемент Цель
deployment: (не job:) Задание развертывания требуется для использования сред ADO. Он включает шлюзы утверждения, журнал развертывания и следы аудита.
environment: $(target_env) Сопоставляется с средой ADO, соответствующей имени ветви (devилиtestprod). Если одобрения проводятся в этой среде, конвейер приостанавливается до утверждения.
strategy: runOnce Выполняет шаги развертывания ровно один раз (в отличие от канарной или последовательной стратегии).

    steps:
    # Step 1: Checkout the source code
    - checkout: self

    # Step 2: Set up Python 3.12
    - task: UsePythonVersion@0
     inputs:
     versionSpec: '3.12'
     addToPath: true
     displayName: "Set up Python Environment"

    # Step 3: Install dependencies
    - script: |
     python -m pip install --upgrade pip
     pip install fabric-cicd
     displayName: "Install Fabric CICD Library"

    # Step 4: Run the deployment script
    - task: PythonScript@0
     inputs:
     scriptSource: 'filePath'
     scriptPath: '.deploy/deploy-to-fabric.py'
     arguments: >-
      --aztenantid $(aztenantid)
      --azclientid $(azclientid)
      --azspsecret $(azspnsecret)
      --items_in_scope ${{ parameters.items_in_scope }}
      --target_env $(target_env)
     displayName: 'Run deployment using fabric-cicd'

🔍 Пояснение-Шаги

Step Как это работает
Оформление заказа Клонирует репозиторий, чтобы конвейер получил доступ к определениям элементов Fabric в папке fabric/ и скрипте развертывания.
Настройка Python Устанавливает Python 3.12 на агент сборки. Для fabric-cicd пакета требуется Python 3.10+.
Установка зависимостей Устанавливает пакет fabric-cicd из PyPI. Это официальная библиотека Майкрософт для автоматизированных развертываний Fabric.
запуск скрипта Выполняет скрипт развертывания Python, передавая все необходимые аргументы: учетные данные SPN (из Key Vault), список типов элементов для развертывания и имя целевой среды.

️ Примечание по безопасности: Значения $(aztenantid), $(azclientid) и $(azspnsecret) получены из связанной с Key Vault группы переменных. Они автоматически маскируются в журналах конвейера— вы увидите *** вместо фактических значений.


6. Подробный анализ кода: скрипт развертывания Python

Файл:.deploy/deploy-to-fabric.py — расположен в репозитории GitHub, скачанном ранее.

Это ядро развертывания. Рассмотрим каждый раздел.


6.1 Импорт и зависимости

import os, argparse, requests, ast
from fabric_cicd import (
 FabricWorkspace,
 publish_all_items,
 unpublish_all_orphan_items,
 change_log_level,
 append_feature_flag,
)
from azure.identity import ClientSecretCredential
Import Цель
os Доступ к переменным среды (нечувствительные значения группы переменных)
argparse Анализ аргументов командной строки, передаваемых из конвейера
requests Выполняйте HTTP вызовы к REST API Fabric (для поиска ID рабочей области)
fabric_cicd Библиотека Майкрософт — берёт на себя основную работу по развертыванию компонентов Fabric
ClientSecretCredential Библиотека идентификации Azure — аутентификация с помощью учетных данных службы (SPN)

6.2 Функция подстановки идентификатора рабочей области

def get_workspace_id(p_ws_name, p_token):
 url = "https://api.fabric.microsoft.com/v1/workspaces"
 headers = {
  "Authorization": f"Bearer {p_token.token}",
  "Content-Type": "application/json"
 }
 response = requests.get(url, headers=headers)
 ws_id = ''
 if response.status_code == 200:
  workspaces = response.json()["value"]
  for workspace in workspaces:
   if workspace["displayName"] == p_ws_name:
    ws_id = workspace["id"]
    return workspace["id"]
  if ws_id == '':
   return f"Error: Workspace {p_ws_name} could not found."
 else:
  return f"Error: {response.status_code}, {response.text}"

Что это делает:

  1. Вызывает REST API Fabric (GET /v1/workspaces) для перечисления всех рабочих областей, к которым имеется доступ у идентификатора обслуживающей учетной записи.
  2. Ищет рабочую область, имя displayName которой соответствует имени целевой рабочей области.
  3. Возвращает GUID рабочей области, если он найден, или сообщение об ошибке, если нет.

💡 Почему не жёстко прописать идентификатор рабочей области? Если осуществлять динамический поиск рабочей области по имени, это делает скрипт более устойчивым к воссозданию рабочей области и позволяет избежать хранения идентификаторов GUID в группе переменных.


6.3 Флаги функций и ведение журнала

append_feature_flag("enable_shortcut_publish")
change_log_level("DEBUG")
Setting Цель
enable_shortcut_publish Включает развертывание сочетаний клавиш Lakehouse — функция, которая включена с помощью флага fabric-cicdфункции.
DEBUG Уровень журнала Предоставляет подробные выходные данные во время развертывания— очень полезно для устранения неполадок. Аргумент "DEBUG" необязателен — вызов change_log_level() без него позволяет включить более подробное ведение журнала. Удалите change_log_level(), если журналы отладки не требуются.

Синтаксический анализ аргументов 6.4

parser = argparse.ArgumentParser(description='Process Azure Pipeline arguments.')
parser.add_argument('--aztenantid', type=str, help='tenant ID')
parser.add_argument('--azclientid', type=str, help='SP client ID')
parser.add_argument('--azspsecret', type=str, help='SP secret')
parser.add_argument('--target_env', type=str, help='target environment')
parser.add_argument('--items_in_scope', type=str, help='Defines the item types to be deployed')
args = parser.parse_args()

Эти аргументы передаются из шага YAML конвейера. Средство синтаксического анализа делает их доступными как args.aztenantid, args.azclientidи т. д.


Проверка подлинности 6.5

token_credential = ClientSecretCredential(
 client_id=args.azclientid,
 client_secret=args.azspsecret,
 tenant_id=args.aztenantid,
)

При этом создается объект учетных данных Azure с помощью идентификатора клиента, секретного ключа и идентификатора арендатора для субъекта-службы. Эти учетные данные используются для:

  1. Вызов Fabric REST API (поиск рабочей области)
  2. Передача FabricWorkspace к fabric-cicd для развертывания

6.6 Разрешение динамической рабочей области

tgtenv = args.target_env       # e.g., "test"
ws_name = f'{tgtenv}WorkspaceName'    # e.g., "testWorkspaceName"
workspace_name = os.environ[ws_name.upper()]  # reads TESTWORKSPACENAME from env vars

Умная часть: Группа переменных fabric_cicd_group_non_sensitive содержит такие переменные, как devWorkspaceName, testWorkspaceNameи т. д. ADO внедряет их в качестве переменных среды верхнего регистра. Скрипт динамически создает имя переменной на основе целевой среды.

# Generate a token and look up the workspace ID
resource = 'https://api.fabric.microsoft.com/'
scope = f'{resource}.default'
token = token_credential.get_token(scope)

lookup_response = get_workspace_id(workspace_name, token)
if lookup_response.startswith("Error"):
 raise ValueError(f"{lookup_response}. Perhaps workspace name is set incorrectly...")
else:
 wks_id = lookup_response

6.7 Инициализация FabricWorkspace и развертывание

repository_directory = os.environ["GITDIRECTORY"] # e.g., "fabric"

item_types = args.items_in_scope.strip("[]").split(",") # Convert string to list

target_workspace = FabricWorkspace(
 workspace_id=wks_id,
 environment=tgtenv,
 repository_directory=repository_directory,
 item_type_in_scope=item_types,
 token_credential=token_credential,
)

# Deploy!
publish_all_items(target_workspace)
unpublish_all_orphan_items(target_workspace)
Метод Как это работает
FabricWorkspace(...) Инициализирует контекст развертывания — считывает определения элементов из репозитория Git, загружает файлы параметров для замены GUID и подготавливает план развертывания.
publish_all_items() Развертывает все элементы в рамке охвата в целевой рабочей области. Обрабатывает создание новых элементов и обновление существующих.
unpublish_all_orphan_items() Удаляет элементы из целевой рабочей области, которая больше не присутствует в ветви Git, сохраняя очистку рабочей области.

⚠️ ВНИМАНИЕ — Понимание unpublish_all_orphan_items(): Этот метод удалит элементы указанных типов в items_in_scope из целевой рабочей области, которые не присутствуют в ветке выпуска (то есть в ветке, используемой как источник для пакета fabric-cicd). Он не будет касаться элементов других типов. В этом руководстве ветвь test содержит все элементы, предназначенные для рабочей области TEST, поэтому безопасно вызвать unpublish_all_orphan_items() — будут удалены только те элементы, которые были намеренно удалены из ветви.

Однако если вы выполняете выборочное развертывание (например, развертывание только записных книжек через сокращенный items_in_scope), будьте осторожны с unpublish_all_orphan_items() — он удалит все записные книжки в рабочей области, которые не включены в ветвь, даже если они по-прежнему действительны и просто не были частью выборочного релиза.

💡 Совет:unpublish_all_orphan_items() поддерживает исключение определенных элементов из удаления путем передачи шаблона регулярных выражений. Все элементы, имена которых соответствуют regex, будут сохранены в рабочей области, даже если они не в исходной ветви. Дополнительные сведения и примеры использования см. в официальном справочнике по API.


7. Глубокое описание кода: файлы параметров (замена GUID)

Вот где происходит магия — как %%configure идентификаторы GUID меняются в зависимости от среды.

Принцип работы

Пакет fabric-cicd ищет файл с именем parameter.yml в каталоге .deploy (или корневом каталоге репозитория). Этот файл определяет правила поиска и замены , применяемые к определениям элементов перед развертыванием.

💡 Совет: Функция parameter.yml поиск-и-замена поддерживает множество подходов помимо того, что представлено в этом руководстве, включая шаблоны регулярных выражений, замены в области файлов и многое другое. Для полного списка параметров и подробного описания см. официальную документацию: 👉документация по файлам параметров fabric-cicd.

💡 Совет — библиотека переменных: Рекомендуется использовать библиотеку переменных , если это возможно для управления значениями среды, а не использовать исключительно find_replace в файлах параметров. Библиотеки переменных предоставляют централизованный и многократно используемый способ управления конфигурацией в разных средах. Дополнительные сведения см. в статье "Начало работы с библиотеками переменных".

Файл:parameter.yml — расположен в репозитории GitHub, скачанном ранее.

Структура файла параметров 7.1

find_replace:
 - find_value: "bfddf0b6-5b74-461a-a963-e89ddc32f852"  # DEV Workspace ID
 replace_value:
  test: " $workspace.$id"         # Replaced with TEST workspace ID
  prod: " $workspace.$id"         # Replaced with PROD workspace ID

🔍 Общие сведения о каждой записи

Элемент 1 — Замена идентификатора рабочей области

- find_value: "bfddf0b6-5b74-461a-a963-e89ddc32f852" # DEV Workspace ID
 replace_value:
 test: " $workspace.$id" # Auto-resolves to the TEST workspace's actual ID
 prod: " $workspace.$id" # Auto-resolves to the PROD workspace's actual ID
  • find_value: GUID, найденный в команде %%configure записной книжки, — это идентификатор рабочей области DEV.
  • replace_value: $workspace.$id это встроенный маркер в fabric-cicd, который автоматически преобразуется в идентификатор целевой рабочей области во время развертывания.
  • Так как dev не указан в replace_value, GUID заменяется только при развертывании в test или prod.

Запись 2 — замена идентификатора Lakehouse

- find_value: "981f2f9a-0436-4942-b158-019bd73cdf1c" # DEV DemoLakehouse GUID
 replace_value:
 test: "$items.Lakehouse.DemoLakehouse.$id" # Resolves to TEST Lakehouse ID
 prod: "$items.Lakehouse.DemoLakehouse.$id" # Resolves to PROD Lakehouse ID
  • $items.Lakehouse.DemoLakehouse.$id — это динамический маркер, который ищет Lakehouse с именем DemoLakehouse в целевой рабочей области и возвращает его идентификатор.
  • Узор:$items.<ItemType>.<ItemName>.$id

Элемент 3 — Замена идентификатора конечной точки SQL (динамическая нотация)

- find_value: "91280ad0-b76e-4c98-a656-95d8f09a5e28" # DEV SQL Endpoint GUID
 replace_value:
 test: $items.Lakehouse.DemoLakehouse.$sqlendpointid # Resolved dynamically at deploy time
 prod: $items.Lakehouse.DemoLakehouse.$sqlendpointid # Resolved dynamically at deploy time
  • Вместо жесткого кода GUID конечной точки SQL для каждой среды (например, 204fd20c-e34c-4bef-9dce-4ecf53b0e878 для TEST или 29bda5ec-ebc7-466e-a618-ef5bbea75e13 для PROD), эта запись использует динамическую нотацию . $items.Lakehouse.DemoLakehouse.$sqlendpointid
  • Пакет fabric-cicd решает эту задачу во время развертывания, находя идентификатор SQL-конечной точки Lakehouse в целевой рабочей области. Это устраняет необходимость вручную находить и поддерживать идентификаторы GUID конечной точки SQL в разных средах.

7.2 Сводка динамических токенов

Токен Разрешает в
$workspace.$id GUID целевой рабочей области
$items.Lakehouse.<name>.$id GUID озера с именем <name> в целевой рабочей области
$items.<ItemType>.<ItemName>.$id Универсальный шаблон для любого типа элемента
$items.Lakehouse.<name>.$sqlendpointid GUID конечной точки SQL в Lakehouse (динамически разрешаемый)

Файл параметров ветви компонентов 7.3 (дополнительно)

Для команд, использующих фичевую ветку (не только dev), существует файл параметров варианта, где все три среды (dev, test, prod) имеют замены:

- find_value: "d34e3a2a-96ba-4461-9a80-496894ca4cda" # Feature branch Workspace ID
 replace_value:
 dev: " $workspace.$id"
 test: " $workspace.$id"
 prod: " $workspace.$id"

Это полезно, если разработчики работают в собственных рабочих областях Fabric и нуждаются в том, чтобы глобальные уникальные идентификаторы (GUID) заменялись даже когда происходит развертывание в среду разработки (DEV).


8. Поток развертывания: полное руководство от начала до конца

Вот полный процесс, когда Алекс хочет перевести записную книжку из разработки в тестирование:


Шаг 1. 🔧 Разработчик вносит изменения в DEV

Алекс изменяет записную книжку IngestApiData в рабочей области DEV Fabric (например, добавляет новую ячейку). Git-интеграция Fabric синхронизирует это изменение с dev веткой автоматически (или с помощью ручного коммита).


Шаг 2. 📋 Создать Pull Request (разработка → тест)

Алекс создает Pull Request в ADO:

  • Исходная ветвь:dev
  • Целевая ветвь:test
  • Название: "Перевод измененных элементов записной книжки на тестирование"

Pr содержит все измененные элементы, которые Алекс хочет развернуть в тестовой среде.


Шаг 3. ✅ Утверждение pr и слияние

Рецензент (или администратор Алекса) проверяет pr:

  • Проверяет изменения в файлах определения ноутбука
  • Утверждает PR
  • Завершает слияние → изменения теперь находятся в ветви.test

Шаг 4. 🚀 Автоматическое активация конвейера

Фиксация слияния на ветке test запускает fabric_cicd_pipeline потому что:

  • Ветвь test находится в списке include триггера
  • Изменения находятся внутри fabric/ пути

Конвейер начинает выполнение:

Pipeline Variable: target_env = "test"

Шаг 5. ⏸️ Ворота утверждения

Так как конвейер использует environment: $(target_env) и target_env = test, ADO проверяет тестовую среду для шлюзов согласования.

  • Конвейер приостанавливается и отправляет уведомление настроенным утверждающим лицам.
  • Администратор проверяет и нажимает кнопку "Утвердить".

Шаг 6. ⚡ Выполнение скрипта

После утверждения конвейер:

  1. ⚙️ Настройка Python 3.12
  2. 📦 Устанавливает fabric-cicd
  3. ▶️ Выполняется deploy-to-fabric.py с помощью:
  • Учетные данные SPN из хранилища ключей Key Vault
  • --target_env test
  • --items_in_scope ["Notebook","Lakehouse",...]

Скрипт Python:

  1. 🔐 Аутентификация с использованием SPN
  2. 🔍 testWorkspaceName Разрешает → ищет идентификатор рабочей области
  3. 📄 Загрузка parameter.yml и выполнение замен GUID
  4. 📤 Публикует элементы в рабочей области TEST
  5. 🧹 Очистка потерянных элементов

Шаг 7. ✅ Завершение развертывания

Записная книжка теперь развернута в рабочей области TEST с помощью следующих компонентов:

  • ✅ Добавленная ячейка присутствует
  • ✅ Все GUID заменены значениями из тестовой среды %%configure

9. Проверка: подтверждение успешного развертывания

После завершения конвейера убедитесь, что развертывание выполнено успешно:

Проверка 1. Состояние конвейера

В ADO → Конвейеры → Запуски убедитесь, что выполнение конвейера показано как ✅ успешное для test среды.

Проверка 2. Содержимое записной книжки в рабочей области TEST

Откройте записную книжку IngestApiData в рабочей области TEST Fabric и проверьте:

  1. Новая ячейка присутствует: Недавно добавленная ячейка, разработанная в DEV, должна появиться в тестовой версии записной книжки.

  2. Идентификаторы GUID заменяются в ячейке 1: В команде %%configure (обычно в ячейке 1), убедитесь, что:

Тип GUID Должно отображаться Не должно отображаться
Идентификатор рабочей области Идентификатор рабочей области TEST ID рабочей области DEV
Идентификатор DemoLakehouse ТЕСТ Lakehouse ID Идентификатор DEV Lakehouse
Идентификатор конечной точки SQL Идентификатор TEST SQL конечной точки (разрешается динамически) Идентификатор конечной точки SQL DEV (91280ad0-...)

Успех! Теперь %%configure ячейка указывает на тестовые lakehouses, и новая работа по разработке была успешно продвинута.


10. Устранение неполадок и распространенных ошибок

Проблема Причина Решение
Пайплайн завершается сбоем с ошибкой "Рабочая область не найдена". Имя рабочей области в группе переменных не соответствует Fabric Перепроверьте testWorkspaceName в группе fabric_cicd_group_non_sensitive переменных
Идентификаторы GUID не заменяются parameter.yml не в ожидаемом расположении Убедитесь, что файл находится в .deploy/ папке вместе со скриптом или в корневом каталоге репозитория
Permission denied ошибки из API Fabric SPN не имеет доступа к рабочей области. Добавление имени субъекта-службы в качестве участника или администратора в целевой рабочей области Fabric
Пайплайн не запускается при слиянии Несоответствие фильтра путей Убедитесь, что элементы Fabric находятся в каталоге fabric/ в репозитории
ModuleNotFoundError: fabric_cicd Пакет не установлен Убедитесь, что pip install fabric-cicd шаг присутствует и успешно выполнен
Уведомление об утверждении не получено Среда не настроена Убедитесь, что имя среды ADO точно совпадает с target_env (с учетом регистра)
GUID конечной точки SQL не заменен Динамическая нотация неправильно настроена Убедитесь, что синтаксис $items.Lakehouse.<name>.$sqlendpointid правильный и Lakehouse существует в целевой рабочей области
os.environ ошибка ключа Группа переменных, не связанная с конвейером Авторизуйте конвейер для доступа fabric_cicd_group_non_sensitive
Ошибки флага компонента для сочетаний клавиш fabric-cicd слишком старая версия Обновление fabric-cicd до последней версии: pip install fabric-cicd --upgrade

11. Сводка

В этом учебном руководстве демонстрируется рабочий процесс CI/CD промышленного уровня для Microsoft Fabric с помощью Azure DevOps.

Компонент То, что мы настроили
Azure Key Vault Безопасно сохраняет учетные данные SPN (идентификатор арендатора, идентификатор клиента, секрет)
Группы переменных ADO Один Key Vault привязан (конфиденциальный), один простой (имена рабочих пространств)
Среды ADO dev, testprod с воротами утверждения и testprod
Ветви Git dev (подключено к Fabric) test и prod (целевые объекты развертывания)
Конвейер YAML Автоматические триггеры при слиянии ветви, параметризованный выбор элемента
Скрипт Python Выполняет проверку подлинности с помощью SPN, разрешает рабочую область, развертывает с помощью fabric-cicd
Файл параметров Замена GUID DEV на значения, специфичные для окружения, с помощью динамических токенов

Общие выводы

  1. Только dev ветвь подключена к рабочей области Fabrictest и prod ветви служат в качестве записей развертывания.
  2. fabric-cicdФайлы параметров обрабатывают замену GUID автоматически с помощью динамических маркеров, таких как $workspace.$id и $items.Lakehouse.<name>.id.
  3. Среды ADO с утверждениями обеспечивают управление — развертывание в более высокие среды не осуществляется без явного утверждения.
  4. Проверка подлинности сервисного принципала через Azure Key Vault гарантирует, что учетные данные никогда не раскрываются в коде и журналах.

📚 Дополнительные сведения: