你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Synapse Analytics 工作区的持续集成和持续交付

项目
11/06/2024

持续集成 (CI) 是每次团队成员将更改提交到版本控制时自动生成和测试代码的过程。持续交付 (CD) 指从多个测试或过渡环境到生产环境的生成、测试、配置和部署过程。

在 Azure Synapse Analytics 工作区中，CI/CD 将所有实体从一个环境（开发、测试、生产）移到另一个环境。将你的工作区提升到另一个工作区的过程包括两个步骤。首先，使用 Azure 资源管理器模板（ARM 模板）创建或更新工作区资源（池和工作区）。然后，在 Azure DevOps 或 GitHub 中使用 Azure Synapse 工作区部署工具来迁移 SQL 脚本、笔记本、Spark 作业定义、管道、数据集和数据流等项目。

本文概述了如何使用 Azure DevOps 发布管道和 GitHub 操作自动将 Azure Synapse 工作区部署到多个环境。

先决条件

若要自动将 Azure Synapse 工作区部署到多个环境，必须准备好以下先决条件和配置。可以根据偏好或现有设置选择使用 Azure DevOps 或 GitHub。

Azure DevOps

如果使用 Azure DevOps：

准备好一个用于运行发布管道的 Azure DevOps 项目。
为将签入代码的用户授予组织级别的“基本”访问权限，以便他们能够查看存储库。
授予对 Azure Synapse 存储库的“所有者”权限。
确保已创建自承载 Azure DevOps VM 代理，或使用 Azure DevOps 托管代理。
授予为资源组创建 Azure 资源管理器服务连接的权限。
Microsoft Entra 管理员必须在 Azure DevOps 组织中安装 Azure DevOps Synapse 工作区部署代理扩展。
创建或指定现有服务帐户，以便管道以该服务帐户的身份运行。你可以使用个人访问令牌，而不是服务帐户，但在删除用户帐户后，你的管道将不起作用。

GitHub

如果使用 GitHub：

创建包含 Azure Synapse 工作区项目和工作区模板的 GitHub 存储库。
确保已创建自承载运行器，或者使用 GitHub 承载的运行器。

Microsoft Entra ID

如果使用服务主体，请在 Microsoft Entra ID 中创建用于部署的服务主体。
如果使用托管标识，请在 Azure 中的 VM 上启用系统分配的托管标识作为代理或运行器，然后将其作为 Synapse 管理员添加到 Azure Synapse Studio。
请使用 Microsoft Entra 管理员角色来完成这些操作。

Azure Synapse Analytics

注意

可以通过使用相同的管道、ARM 模板或 Azure CLI 来自动化和部署这些必备组件，但本文不介绍这些过程。

必须在 Azure Synapse Studio 中为用于开发的“源”工作区配置 Git 存储库。有关详细信息，请参阅 Azure Synapse Studio 中的源代码管理。
设置要部署到的空白工作区，以便：
1. 创建新的 Azure Synapse 工作区。
2. 向服务主体授予对新 Synapse 工作区的以下权限：
  - Microsoft.Synapse/workspaces/integrationruntimes/write
  - Microsoft.Synapse/workspaces/operationResults/read
  - Microsoft.Synapse/workspaces/read
3. 在该工作区中，请不要配置 Git 存储库连接。
4. 在 Azure Synapse 工作区中，转到“Studio”>“管理”>“访问控制” 。将“Synapse 工件发布者”分配给服务主体。如果部署管道需要部署托管专用终结点，请改为分配“Synapse 管理员”。
5. 使用其连接信息存储在 Azure Key Vault 中的链接服务时，建议为不同的环境保留不同的密钥保管库。此外，可为每个密钥保管库单独配置权限级别。例如，你可能不希望团队成员有权访问生产机密。如果采用此方法，我们建议在所有阶段中保留相同的机密名称。如果保留相同的机密名称，则无需在 CI/CD 环境中参数化每个连接字符串，因为只需更改密钥保管库名称，而该名称是一个单独的参数。

其他先决条件

未在工作区部署任务中创建 Spark 池和自承载集成运行时。如果有使用自承载集成运行时的链接服务，请在新的工作区中手动创建该运行时。
如果开发工作区中的项与特定池连接，请确保在参数文件中为目标工作区中的池创建或参数化相同的名称。
如果在尝试部署时预配的 SQL 池已暂停，则部署可能会失败。

有关详细信息，请参阅 Azure Synapse Analytics 中的 CI CD 第 4 部分 - 发布管道。

在 Azure DevOps 中设置发布管道

本部分介绍如何在 Azure DevOps 中部署 Azure Synapse 工作区。

在 Azure DevOps 中，打开你创建的用于发布的项目。
在左侧菜单中，选择“管道”>“发布” 。
选择“新建管道”。如果你有现有的管道，请选择“新建”>“新建发布管道” 。
选择“空作业”模板。
在“阶段名称”中，输入你的环境名称。
选择“添加项目”，然后选择在开发环境中使用 Azure Synapse Studio 配置的 Git 存储库。选择要在其中管理池和工作区 ARM 模板的 Git 存储库。如果使用 GitHub 作为源，请为 GitHub 帐户和拉取存储库创建服务连接。有关详细信息，请参阅服务连接。
选择资源 ARM 模板分支。对于“默认版本”，请选择“默认分支中的最新版本”。
对于项目“默认分支”，请选择存储库发布分支或其他包含 Synapse 项目的非发布分支。默认情况下，发布分支为 workspace_publish。对于“默认版本”，请选择“默认分支中的最新版本”。

为 ARM 模板设置阶段任务，以创建和更新资源

如果你有用于部署资源（例如 Azure Synapse 工作区、Spark 池、SQL 池或密钥保管库）的 ARM 模板，请添加 Azure 资源管理器部署任务来创建或更新这些资源：

在阶段视图中选择“查看阶段任务”。
创建新任务。搜索“ARM 模板部署”，然后选择“添加”。
在部署“任务”选项卡上，选择工作区的订阅、资源组和位置。根据需要提供凭据。
对于“操作”，请选择“创建或更新资源组” 。
对于“模板”，请选择省略号按钮 (...) 。转到工作区的 ARM 模板。
对于“模板参数”，请选择“…”以选择参数文件。
对于“替代模板参数”，请选择“...”，然后输入要用于工作区的参数值。
对于“部署模式”，请选择“增量” 。
（可选）添加“Azure PowerShell”以便授予和更新工作区角色分配。如果使用发布管道创建 Azure Synapse 工作区，则会将管道的服务主体添加为默认工作区管理员。可以运行 PowerShell 来向其他帐户授予对工作区的访问权限。

警告

在完整部署模式下，将会删除资源组中的、尚未在新 ARM 模板中指定的资源。有关详细信息，请参阅 Azure 资源管理部署模式。

为 Azure Synapse 项目部署设置阶段任务

使用 Synapse 工作区部署扩展在 Azure Synapse 工作区中部署其他项。可以部署的项包括数据集、SQL 脚本和笔记本、spark 作业定义、集成运行时、数据流、凭据和其他工作区中的项目。

安装和添加部署扩展

从 Visual Studio Marketplace 搜索并获取该扩展。
选择要在其中安装该扩展的 Azure DevOps 组织。
确保已向 Azure DevOps 管道的服务主体授予“订阅”权限，并已将该服务主体分配为工作区的 Synapse 工作区管理员。
若要创建新任务，请搜索“Synapse 工作区部署”，然后选择“添加” 。

配置部署任务

部署任务支持 3 种类型的操作：仅验证、部署，以及验证和部署。

注意

此工作区部署扩展不向后兼容。请确保已安装和使用最新版本。可以在 Azure DevOps 的概述和 GitHub 操作的最新版本中阅读发行说明。

验证是指使用任务来验证非发布分支中的 Synapse 项目，并生成工作区模板和参数模板文件。验证操作仅适用于 YAML 管道。下面是示例 YAML 文件：

   pool:
     vmImage: ubuntu-latest

   resources:
     repositories:
     - repository: <repository name>
       type: git
       name: <name>
       ref: <user/collaboration branch>

   steps:
     - checkout: <name>
     - task: Synapse workspace deployment@2
       continueOnError: true    
       inputs:
         operation: 'validate'
         ArtifactsFolder: '$(System.DefaultWorkingDirectory)/ArtifactFolder'
         TargetWorkspaceName: '<target workspace name>'

验证和部署可用于使用项目根文件夹从非发布分支直接部署工作区。

注意

将操作类型选为“验证”或“验证并部署”时，部署任务需要从此终结点下载依赖项 JS 文件 web.azuresynapse.net。如果在 VM 上启用了网络策略，请确保已允许 web.azuresynapse.net 终结点。

验证和部署操作适用于经典和 YAML 管道。下面是示例 YAML 文件：

   pool:
     vmImage: ubuntu-latest

   resources:
     repositories:
     - repository: <repository name>
       type: git
       name: <name>
       ref: <user/collaboration branch>

   steps:
     - checkout: <name>
     - task: Synapse workspace deployment@2
       continueOnError: true    
       inputs:
         operation: 'validateDeploy'
         ArtifactsFolder: '$(System.DefaultWorkingDirectory)/ArtifactFolder'
         TargetWorkspaceName: 'target workspace name'
         azureSubscription: 'target Azure resource manager connection name'
         ResourceGroupName: 'target workspace resource group'
         DeleteArtifactsNotInTemplate: true
         OverrideArmParameters: >
           -key1 value1
           -key2 value2

部署操作部署的输入包括 Synapse 工作区模板和参数模板，可以在工作区发布分支或验证后创建该模板。它与版本 1.x 相同。

可以根据用例选择操作类型。以下部分是部署的示例。

在任务中，选择操作类型作为部署。
在任务中的“模板”旁边，选择“…”以选择模板文件。
在“模板参数”旁边，选择“…”以选择参数文件。
选择连接、资源组，以及工作区的名称。
在“替代模板参数”旁边，选择“…”。输入要用于工作区的参数值，包括在链接服务中使用的连接字符串和帐户密钥。有关详细信息，请参阅 Azure Synapse Analytics 中的 CI/CD。
仅版本 2.x 支持部署托管专用终结点。请确保选择正确的版本，并选中“在模板中部署托管专用终结点”。
若要管理触发器，可以在部署之前使用触发器切换开关来停止触发器。此外，还可以添加一个任务，在部署任务之后重启触发器。

重要

在 CI/CD 方案中，不同环境中的集成运行时类型必须相同。例如，如果你在开发环境中有一个自承载集成运行时，则在其他环境（例如测试和生产）中也必须自承载该集成运行时。同样，如果你跨多个阶段共享集成运行时，则必须在所有环境（例如开发、测试和生产）中链接并自承载这些集成运行时。

创建发布进行部署

保存所有更改后，可以选择“创建发布”以手动创建发布。若要了解如何自动创建发布，请参阅 Azure DevOps 发布触发器。

在 GitHub Actions 中设置发布

本部分介绍如何使用 GitHub Actions 为 Azure Synapse 工作区部署创建 GitHub工作流。

可以使用 Azure 资源管理器模板的 GitHub Actions 将用于工作区和计算池的 ARM 模板自动部署到 Azure。

工作流文件

在存储库的 /.github/workflows/ 路径下的 YAML (.yml) 文件中定义 GitHub Actions 工作流。定义包含构成工作流的各个步骤和参数。

.yml 文件包含两个部分：

部分	任务
身份验证	1.定义服务主体。 2. 创建 GitHub 机密。
部署	部署工作区项目。

配置 GitHub Actions 机密

GitHub Actions 机密是已加密的环境变量。对此存储库拥有“协作者”权限的任何人都可以使用这些机密来与该存储库中的操作交互。

在 GitHub 存储库中选择“设置”选项卡，然后选择“机密”>“新建存储库机密” 。
如果使用服务主体进行部署，请为客户端 ID 添加新机密，并添加新的客户端机密。还可以选择保存订阅 ID 和租户 ID 作为机密。

添加工作流

在 GitHub 存储库中，转到“操作”。

选择“自己设置工作流”。
在工作流文件中，删除 on: 部分后面的所有内容。例如，剩下的工作流可能如以下示例所示：
```
name: CI

on:
push:
    branches: [ master ]
pull_request:
    branches: [ master ]
```
重命名工作流。在“Marketplace”选项卡上，搜索 Synapse 工作区部署操作，然后添加该操作。

设置所需的值和工作区模板：

name: workspace deployment

on:
    push:
        branches: [ publish_branch ]
jobs:
    release:
        # You also can use the self-hosted runners.
        runs-on: windows-latest
        steps:
        # Checks out your repository under $GITHUB_WORKSPACE, so your job can access it.
        - uses: actions/checkout@v2
        - uses: azure/synapse-workspace-deployment@release-1.0
        with:
          TargetWorkspaceName: 'target workspace name'
          TemplateFile: './path of the TemplateForWorkspace.json'
          ParametersFile: './path of the TemplateParametersForWorkspace.json'
          OverrideArmParameters: './path of the parameters.yaml'
          environment: 'Azure Public'
          resourceGroup: 'target workspace resource group'
          clientId: ${{secrets.CLIENTID}}
          clientSecret:  ${{secrets.CLIENTSECRET}}
          subscriptionId: 'subscriptionId of the target workspace'
          tenantId: 'tenantId'
          DeleteArtifactsNotInTemplate: 'true'
          managedIdentity: 'False'

现在可以提交更改。选择“开始提交”，输入标题，并添加说明（可选）。然后选择“提交新文件”。

该文件将显示在存储库的 github/workflows 文件夹中。

注意

只有 Azure 中的自承载 VM 才支持托管标识。请务必将运行器设置为“自承载”。为 VM 启用系统分配的托管标识，并将其作为 Synapse 管理员添加到 Azure Synapse Studio。

查看部署

在 GitHub 存储库中，转到“操作”。
若要查看工作流的详细运行日志，请打开第一条结果：

在工作区模板中创建自定义参数

如果你使用自动化 CI/CD，并想要在部署期间更改某些属性，但这些属性在默认情况下并未参数化，则你可以替代默认参数模板。

若要替代默认参数模板，请在 Git 分支的根文件夹中创建名为 template-parameters-definition.json 的自定义参数模板。必须使用与此完全相同的文件名。 Azure Synapse 工作区从协作分支发布，或部署任务验证其他分支中的项目时，将会读取此文件，并使用其配置来生成参数。如果 Azure Synapse 工作区找不到该文件，则会使用默认参数模板。

自定义参数语法

可以使用以下准则来创建自定义参数文件：

输入相关实体类型下的属性路径。
将属性名称设置为 * 表示你要参数化该属性下的所有属性（只参数化到第一个级别，而不是递归性参数化）。可为此配置设置例外情况。
将属性值设置为字符串表示你希望参数化该属性。使用格式 <action>:<name>:<stype>。
- <action> 可以是以下字符之一：
  - = 表示将当前值保留为参数的默认值。
  - - 表示不保留参数的默认值。
  - | 是 Azure Key Vault 中的机密的特例，用于连接字符串或密钥。
- <name> 是参数的名称。如果为空，将采用属性的名称。如果值以 - 字符开头，则会简写名称。例如，AzureStorage1_properties_typeProperties_connectionString 将简写为 AzureStorage1_connectionString。
- <stype> 是参数的类型。如果 <stype> 为空，则默认类型为 string。支持的值：string、securestring、int、bool、object、secureobject 和 array。
在该文件中指定数组，则表示模板中的匹配属性是数组。 Azure Synapse 会通过使用指定的定义来循环访问该数组中的所有对象。第二个对象（一个字符串）成为属性的名称，这用作每次遍历的参数的名称。
定义不能特定于资源实例。任何定义都将应用到该类型的所有资源。
默认情况下，会参数化密钥保管库机密等安全字符串，以及连接字符串、密钥和令牌等安全字符串。

参数模板定义示例

下面是参数模板定义的示例：

{
    "Microsoft.Synapse/workspaces/notebooks": {
        "properties": {
            "bigDataPool": {
                "referenceName": "="
            }
        }
    },
    "Microsoft.Synapse/workspaces/sqlscripts": {
        "properties": {
            "content": {
                "currentConnection": {
                    "*": "-"
                }
            }
        }
    },
    "Microsoft.Synapse/workspaces/pipelines": {
        "properties": {
            "activities": [{
                "typeProperties": {
                    "waitTimeInSeconds": "-::int",
                    "headers": "=::object",
                    "activities": [
                        {
                            "typeProperties": {
                                "url": "-:-webUrl:string"
                            }
                        }
                    ]
                }
            }]
        }
    },
    "Microsoft.Synapse/workspaces/integrationRuntimes": {
        "properties": {
            "typeProperties": {
                "*": "="
            }
        }
    },
    "Microsoft.Synapse/workspaces/triggers": {
        "properties": {
            "typeProperties": {
                "recurrence": {
                    "*": "=",
                    "interval": "=:triggerSuffix:int",
                    "frequency": "=:-freq"
                },
                "maxConcurrency": "="
            }
        }
    },
    "Microsoft.Synapse/workspaces/linkedServices": {
        "*": {
            "properties": {
                "typeProperties": {
                    "accountName": "=",
                    "username": "=",
                    "connectionString": "|:-connectionString:secureString",
                    "secretAccessKey": "|"
                }
            }
        },
        "AzureDataLakeStore": {
            "properties": {
                "typeProperties": {
                    "dataLakeStoreUri": "="
                }
            }
        },
        "AzureKeyVault": {
            "properties": {
                "typeProperties": {
                    "baseUrl": "|:baseUrl:secureString"
                },
                "parameters": {
                    "KeyVaultURL": {
                        "type": "=",
                        "defaultValue": "|:defaultValue:secureString"
                    }
                }
            }
        }
    },
    "Microsoft.Synapse/workspaces/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }
    },
    "Microsoft.Synapse/workspaces/credentials" : {
        "properties": {
            "typeProperties": {
                "resourceId": "="
            }
        }
    }
}

下面说明如何按资源类型构造上述模板。

notebooks

properties/bigDataPool/referenceName 路径中的任何属性均使用其默认值进行参数化。可为每个笔记本文件参数化附加的 Spark 池。

sqlscripts

在 properties/content/currentConnection 路径中，poolName 和 databaseName 属性参数化为在模板中没有默认值的字符串。

pipelines

将参数化 activities/typeProperties/waitTimeInSeconds 路径中的任何属性。包含名为 waitTimeInSeconds 的代码级属性的管道中的任一活动（例如 Wait 活动）将以默认名称参数化为数字。该属性在资源管理器模板中没有默认值。在资源管理器部署期间，需要为该属性提供输入。
headers 属性（例如在 Web 活动中）将以 object（对象）类型参数化。 headers 属性具有默认值，该值与源工厂的默认值相同。

integrationRuntimes

typeProperties 路径中的所有属性以其各自的默认值参数化。例如，IntegrationRuntimes 类型属性下有两个属性：computeProperties 和 ssisProperties。这两个属性类型是使用各自的默认值和类型 (Object) 创建的。

triggers

typeProperties 下的两个属性将参数化：
- maxConcurrency 属性具有默认值，其类型为 string。 maxConcurrency 属性的默认参数名称为 <entityName>_properties_typeProperties_maxConcurrency。
- 另外还会参数化 recurrence 属性。 recurrence 属性下的所有属性均设置为参数化为字符串，并具有默认值和参数名称。 interval 属性例外，它将参数化为 int 类型。参数名称带有 <entityName>_properties_typeProperties_recurrence_triggerSuffix 后缀。同样，freq 属性是字符串，将参数化为字符串。但是，将参数化 freq 属性且不提供默认值。名称将会简写并带有后缀，例如 <entityName>_freq。
注意

目前最多支持 50 个触发器。

linkedServices

链接服务是独特的。由于链接服务和数据集的类型多种多样，你可以提供类型特定的自定义。在上面的示例中，对于 AzureDataLakeStore 类型的所有链接服务，将应用特定的模板。对于所有其他链接服务（使用 * 字符标识），将应用不同的模板。
connectionString 属性将参数化为 securestring 值。该属性没有默认值。参数名称将会简写并带有 connectionString 后缀。
secretAccessKey 属性将参数化为 AzureKeyVaultSecret 值（例如，在 Amazon S3 链接服务中）。该属性自动参数化为 Azure 密钥保管库机密，可从配置的密钥保管库提取。还可以参数化密钥保管库本身。

datasets

尽管可以自定义数据集中的类型，但不需要进行显式的 * 级配置。在前面的示例中，typeProperties 下的所有数据集属性都将参数化。

CI/CD 最佳做法

如果使用 Azure Synapse 工作区的 Git 集成，并且某个 CI/CD 管道会将更改从开发环境依次转移到测试和生产环境，则我们建议采用以下最佳做法：

仅将开发工作区与 Git 集成。如果你使用 Git 集成，请仅将开发 Azure Synapse 工作区与 Git 集成。对测试和生产工作区所做的更改将通过 CI/CD 进行部署，不需要 Git 集成。
在迁移项目之前准备好池。如果已将 SQL 脚本或笔记本附加到开发工作区中的池，请为不同环境中的池使用相同的名称。
在基础结构即代码方案中同步版本控制。若要在描述性模型中管理基础结构（网络、虚拟机、负载均衡器和连接拓扑），请使用 DevOps 团队对源代码所用的相同版本控制。
查看Azure 数据工厂最佳做法。如果使用数据工厂，请参阅数据工厂项目的最佳做法。

排查项目部署问题

使用 Synapse 工作区部署任务部署 Synapse 工件

在 Azure Synapse 中，不同于数据工厂中的情况，工件不是资源管理器资源。不能使用 ARM 模板部署任务来部署 Azure Synapse 项目，请改用 Synapse 工作区部署任务来部署工件，并使用 ARM 部署任务部署 ARM 资源（池和工作区）。同时，此任务仅支持资源具有类型 Microsoft.Synapse 的 Synapse 模板。通过此任务，用户可以自动部署任何分支的更改，而无需手动单击 Synapse Studio 中的发布。以下是一些常见问题。

1.发布失败：工作区 arm 文件大小超过 20 MB

Git 提供程序中存在文件大小限制，例如，在 Azure DevOps 中，最大文件大小为 20 Mb。工作区模板文件大小超过 20 Mb 后，在 Synapse Studio 中发布更改时就会发生此错误，其中会生成工作区模板文件并会将该文件同步到 git。若要解决此问题，可以使用具有“验证”或“验证和部署”操作的 Synapse 部署任务，将工作区模板文件直接保存到管道代理中，而无需在 synapse Studio 中手动发布。

2. 发布中出现意外的标记错误

如果参数文件包含未转义的参数值，则发布管道将无法分析该文件，并会生成 unexpected token 错误。建议替代参数，或使用密钥保管库来检索参数值。也可以使用双转义字符来解决该问题。

3. 集成运行时部署失败

如果从已启用虚拟网络的托管工作区生成了工作区模板，并尝试将其部署到常规工作区（反之亦然），则会发生此错误。

4. 分析值时遇到意外的字符

模板无法分析模板文件。请尝试使用转义反斜杠，例如 \\Test01\Test

5. 未能提取工作区信息（找不到）

未正确配置目标工作区信息。确保所创建的服务连接的范围限定为具有工作区的资源组。

6. 删除工件失败

该扩展会将发布分支中存在的工件与模板进行比较，并根据差异将其删除。确保你没有尝试删除发布分支中存在的任何项目，并且某些其他项目具有对它的引用或依赖项。

7.部署失败并出现错误：json 位置 0

如果尝试手动更新模板，会出现此错误。确保尚未手动编辑模板。

8.由于无效的引用，文档创建或更新失败

Synapse 中的工件可以由另一个工件引用。如果已将项目中引用的属性参数化，请确保为其提供正确的非 null 值

9.未能在笔记本部署中提取部署状态

尝试部署的笔记本附加到工作区模板文件中的 Spark 池，而在部署中，目标工作区中没有该池。如果未将池名称参数化，请确保环境之间的池具有相同的名称。

通过