Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
🚀 CI/CD для Microsoft Fabric с помощью Azure DevOps и
В этом руководстве вы используете библиотеку 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 в разделе "Параметры клиента".
Скачивание исходных файлов
- Создайте форк репозитория Fabric-samples в вашем аккаунте GitHub.
- Клонируйте форк на ваш локальный компьютер.
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
- Создайте Key Vault на портале Azure (или используйте существующую).
- Добавьте три секрета:
| Имя секрета | Description | Пример значения |
|---|---|---|
aztenantid |
Идентификатор клиента Azure AD / Entra ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
azclientid |
Идентификатор приложения сервисного принципала (клиент) | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
azspnsecret |
Значение секрета клиента субъекта-службы | your-secret-value |
Предоставление доступа: Подключение службы ADO (или удостоверение проекта ADO) должно иметь разрешения на получение и перечисление секретов в политиках доступа Key Vault (или роли
Key Vault Secrets UserRBAC).
4.2 Группа переменных: fabric_cicd_group_sensitive
Эта группа переменных связана с Azure Key Vault, т. е. значения секретов извлекаются во время выполнения и никогда не предоставляются в пользовательском интерфейсе ADO.
Шаги для создания
- Перейдите в библиотеку конвейеров → в проекте ADO.
- Нажмите + Группа переменных.
- Назовите его:
fabric_cicd_group_sensitive - Включите опцию Использовать секреты из хранилища ключей Azure как переменные.
- Выберите подписку Azure и Key Vault.
- Нажмите кнопку +Добавить и выберите три секрета:
aztenantidazclientidazspnsecret
- Нажмите кнопку Сохранить.
| 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.
Шаги по созданию
- Перейдите в библиотеку конвейеров → в проекте ADO.
- Нажмите + Группа переменных.
- Назовите его:
fabric_cicd_group_non_sensitive - Добавьте следующие переменные:
| Имя переменной | Ценность | Description |
|---|---|---|
devWorkspaceName |
MyProject-Dev |
Имя рабочей области DEV Fabric |
testWorkspaceName |
MyProject-Test |
Имя рабочей области TEST Fabric |
prodWorkspaceName |
MyProject-Prod |
Имя рабочей области PROD Fabric |
gitDirectory |
fabric |
Папка в репозитории, содержащая определения элементов Fabric |
💡 Как это работает в коде: Скрипт Python считывает эти значения с помощью
os.environ. Например, при развертывании наtestв скрипте создается имя переменнойtestWorkspaceName, преобразуется в верхний регистр (TESTWORKSPACENAME) и считывается из среды, поскольку ADO автоматически внедряет значения группы нечувствительных переменных в качестве переменных среды в верхнем регистре.
4.4 Среды ADO и шлюзы утверждения
Среды ADO позволяют добавлять проверки утверждения вручную перед продолжением развертывания. Это важно для продвижения к test и prod.
Действия по созданию сред
- Перейдите к Конвейеры → Среды в проекте ADO.
- Создайте три среды с точными именами , соответствующими именам ветви:
| Название окружения | Требуется утверждение? | Утверждающие |
|---|---|---|
dev |
❌ Нет (автоматическое развертывание) | — |
test |
✅ Да | Команда администрирования / ведущий |
prod |
✅ Да | Команда администрирования / ведущий |
Для
testиprod, нажмите на среду → ⋮ (Дополнительные параметры) → Утверждения и проверки → + Добавить проверку → Утверждения.Добавьте требуемых утверждающих лиц.
Пример представления состояния среды:
| Окружающая среда | Состояние |
|---|---|
| разработчик | ✅ #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 в репозитории.
Этапы
- Перейдите к конвейерам → Конвейеры →новый конвейер.
- Выберите Azure Repos Git и выберите репозиторий.
- Выберите существующий YAML-файл Azure Pipelines.
- Наведите указатель на путь:
Deploy-To-Fabric.yml(или туда, куда вы его разместили). -
Присвойте конвейеру имя.
fabric_cicd_pipeline - В разделе "Разрешения конвейера" убедитесь, что у него есть доступ к:
- Обе группы переменных (
fabric_cicd_group_sensitiveиfabric_cicd_group_non_sensitive) - Все три среды (
dev,test,prod)
- Сохраните (пока не запускайте).
⚠ ️ Совет по разрешениям: При первом запуске конвейера может потребоваться разрешить доступ 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/test → test. Эта отдельная переменная управляет всем поведением с учетом среды. |
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}"
Что это делает:
- Вызывает REST API Fabric (
GET /v1/workspaces) для перечисления всех рабочих областей, к которым имеется доступ у идентификатора обслуживающей учетной записи. - Ищет рабочую область, имя
displayNameкоторой соответствует имени целевой рабочей области. - Возвращает 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 с помощью идентификатора клиента, секретного ключа и идентификатора арендатора для субъекта-службы. Эти учетные данные используются для:
- Вызов Fabric REST API (поиск рабочей области)
- Передача
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. ⚡ Выполнение скрипта
После утверждения конвейер:
- ⚙️ Настройка Python 3.12
-
📦 Устанавливает
fabric-cicd - ▶️ Выполняется
deploy-to-fabric.pyс помощью:
- Учетные данные SPN из хранилища ключей Key Vault
--target_env test--items_in_scope ["Notebook","Lakehouse",...]
Скрипт Python:
- 🔐 Аутентификация с использованием SPN
-
🔍
testWorkspaceNameРазрешает → ищет идентификатор рабочей области -
📄 Загрузка
parameter.ymlи выполнение замен GUID - 📤 Публикует элементы в рабочей области TEST
- 🧹 Очистка потерянных элементов
Шаг 7. ✅ Завершение развертывания
Записная книжка теперь развернута в рабочей области TEST с помощью следующих компонентов:
- ✅ Добавленная ячейка присутствует
-
✅ Все GUID заменены значениями из тестовой среды
%%configure
9. Проверка: подтверждение успешного развертывания
После завершения конвейера убедитесь, что развертывание выполнено успешно:
Проверка 1. Состояние конвейера
В ADO → Конвейеры → Запуски убедитесь, что выполнение конвейера показано как ✅ успешное для test среды.
Проверка 2. Содержимое записной книжки в рабочей области TEST
Откройте записную книжку IngestApiData в рабочей области TEST Fabric и проверьте:
Новая ячейка присутствует: Недавно добавленная ячейка, разработанная в DEV, должна появиться в тестовой версии записной книжки.
Идентификаторы GUID заменяются в ячейке 1: В команде
%%configure(обычно в ячейке 1), убедитесь, что:
| Тип GUID | Должно отображаться | Не должно отображаться |
|---|---|---|
| Идентификатор рабочей области | Идентификатор рабочей области TEST |
|
| Идентификатор DemoLakehouse | ТЕСТ Lakehouse ID |
|
| Идентификатор конечной точки SQL | Идентификатор TEST SQL конечной точки (разрешается динамически) |
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 на значения, специфичные для окружения, с помощью динамических токенов |
Общие выводы
-
Только
devветвь подключена к рабочей области Fabric —testиprodветви служат в качестве записей развертывания. -
fabric-cicdФайлы параметров обрабатывают замену GUID автоматически с помощью динамических маркеров, таких как$workspace.$idи$items.Lakehouse.<name>.id. - Среды ADO с утверждениями обеспечивают управление — развертывание в более высокие среды не осуществляется без явного утверждения.
- Проверка подлинности сервисного принципала через Azure Key Vault гарантирует, что учетные данные никогда не раскрываются в коде и журналах.
📚 Дополнительные сведения: