Kontinuierliche Integration und Bereitstellung für einen Azure Synapse Analytics-Arbeitsbereich

Kontinuierliche Integration (Continuous Integration, CI) ist der Prozess, bei dem die Erstellung und das Testen von Code jedes Mal automatisiert wird, wenn ein Teammitglied eine Änderung an die Versionskontrolle überträgt. Kontinuierliche Bereitstellung (Continuous Delivery, CD) ist der Prozess des Erstellens, Testens, Konfigurierens und Bereitstellens von mehreren Test- oder Staging-Umgebungen in eine Produktionsumgebung.

In einem Azure Synapse Analytics-Arbeitsbereich verschiebt CI/CD alle Einheiten von einer Umgebung (Entwicklung, Test, Produktion) in eine andere Umgebung. Das Promoten Ihres Arbeitsbereichs in einen anderen Arbeitsbereich ist ein zweiteiliger Prozess. Im ersten Schritt verwenden Sie eine Azure Resource Manager-Vorlage (ARM-Vorlage), um Arbeitsbereichsressourcen (Pools und Arbeitsbereich) zu erstellen oder zu aktualisieren. Migrieren Sie dann Artefakte wie SQL-Skripts und Notebooks, Spark-Auftragsdefinitionen, Pipelines, Datasets und andere Artefakte mithilfe der Tools zur Bereitstellung von Synapse-Arbeitsbereichen in Azure DevOps oder auf GitHub.

In diesem Artikel wird beschrieben, wie eine Azure DevOps-Release-Pipeline und GitHub Actions verwendet werden können, um die Bereitstellung eines Azure Synapse-Arbeitsbereichs in mehreren Umgebungen zu automatisieren.

Voraussetzungen

Um die Bereitstellung eines Azure Synapse-Arbeitsbereichs in mehreren Umgebungen zu automatisieren, müssen die folgenden Voraussetzungen und Konfigurationen vorhanden sein. Sie können je nach Ihrer Vorliebe bzw. Ihrem vorhandenen Setup entweder Azure DevOps oder GitHub verwenden.

Azure DevOps

Wenn Sie Azure DevOps verwenden:

• Bereiten Sie ein Azure DevOps-Projekt für die Ausführung der Release-Pipeline vor.
• Gewähren Sie allen Benutzern, die Code einchecken werden, Basiszugriff auf Organisationsebene, damit sie das Repository sehen können.
• Erteilen Sie dem Azure Synapse-Repository die Berechtigung Owner.
• Stellen Sie sicher, dass Sie einen selbst gehosteten Azure DevOps VM-Agent erstellt haben oder einen von Azure DevOps gehosteten Agenten verwenden.
• Erteilen Sie die Berechtigung , eine Azure Resource Manager-Dienstverbindung für die Ressourcengruppe zu erstellen.
• Ein Microsoft Entra muss die Agent-Erweiterung für die Azure DevOps Synapse-Arbeitsbereichsbereitstellung in der Azure DevOps-Organisation installieren.
• Erstellen Sie ein Dienstkonto für die Pipelineausführung, oder legen Sie für die Ausführung ein vorhandenes Dienstkonto fest. Sie können anstelle eines Dienstkontos ein persönliches Zugriffstoken verwenden, aber Ihre Pipelines funktionieren nicht mehr, wenn das Benutzerkonto gelöscht wird.

GitHub

Wenn Sie GitHub verwenden:

• Erstellen Sie ein GitHub-Repository, das die Artefakte des Azure-Synapse-Arbeitsbereichs und die Arbeitsbereichsvorlage enthält.
• Stellen Sie sicher, dass Sie einen selbst gehosteten Runner erstellt haben oder einen auf GitHub gehosteten Runner verwenden.

Microsoft Entra ID

• Wenn Sie einen Dienstprinzipal verwenden, erstellen Sie in Microsoft Entra ID einen Dienstprinzipal, der für die Bereitstellung verwendet wird.
• Wenn Sie eine verwaltete Identität verwenden, aktivieren Sie die vom System zugewiesene verwaltete Identität auf Ihrer VM in Azure als Agent oder Runner und fügen Sie diese dann zu Azure Synapse Studio als Synapse-Admin hinzu.
• Verwenden Sie die Microsoft Entra-Administratorrolle, um diese Aktionen durchzuführen.

Azure Synapse Analytics

Hinweis

Sie können diese Voraussetzungen automatisieren und bereitstellen, indem Sie die gleiche Pipeline, eine ARM-Vorlage oder die Azure-Befehlszeilenschnittstelle verwenden, aber diese Prozesse werden in diesem Artikel nicht beschrieben.

• Der "Quell"-Arbeitsbereich, der für die Entwicklung verwendet wird, muss mit einem Git-Repository in Azure Synapse Studio konfiguriert werden. Weitere Informationen finden Sie unter Quellsteuerung in Azure Synapse Studio.

• Richten Sie einen leeren Arbeitsbereich für die Bereitstellung ein:

  1. Erstellen Sie einen neuen Azure Synapse-Arbeitsbereich.
  2. Gewähren Sie dem Dienstprinzipal die folgenden Berechtigungen für den neuen Synapse-Arbeitsbereich:
     • Microsoft.Synapse/workspaces/integrationruntimes/write
     • Microsoft.Synapse/workspaces/operationResults/read
     • Microsoft.Synapse/workspaces/read
  3. Konfigurieren Sie im Arbeitsbereich die Git-Repository-Verbindung nicht.
  4. Gehen Sie im Azure Synapse-Arbeitsbereich zu Studio>Verwaltung>Zugriffskontrolle. Weisen Sie dem Dienstprinzipal den „Synapse Artifact Publisher“ zu. Wenn die Bereitstellungspipeline verwaltete private Endpunkte bereitstellen muss, weisen Sie stattdessen den „Synapse Administrator“ zu.
  5. Wenn Sie verknüpfte Dienste verwenden, deren Verbindungsinformationen in Azure Key Vault gespeichert sind, wird empfohlen, separate Schlüsseltresore für verschiedene Umgebungen beizubehalten. Sie können auch separate Berechtigungsstufen für jeden Schlüsseltresor konfigurieren. Es kann beispielsweise sein, dass Teammitglieder nicht über Berechtigungen für Produktionsgeheimnisse verfügen sollen. Bei diesem Ansatz empfehlen wir Ihnen, in allen Stufen die gleichen Geheimnisnamen beizubehalten. Wenn Sie die gleichen Geheimnisnamen beibehalten, müssen Sie nicht jede einzelne Verbindungszeichenfolge für alle CI/CD-Umgebungen parametrisieren, weil sich lediglich der Name des Schlüsseltresors ändert, und der ist ein separater Parameter.

Weitere Voraussetzungen

• Spark-Pools und selbst gehostete Integrationslaufzeiten werden nicht in einer Arbeitsbereichsbereitstellungsaufgabe erstellt. Wenn Sie einen verknüpften Dienst haben, der eine selbst gehostete Integrationslaufzeit verwendet, erstellen Sie die Laufzeit manuell in dem neuen Arbeitsbereich.
• Wenn die Elemente im Entwicklungsarbeitsbereich mit den spezifischen Pools verknüpft sind, stellen Sie sicher, dass Sie die gleichen Namen für die Pools im Zielarbeitsbereich in der Parameterdatei erstellen oder parametrisieren.
• Wenn Ihre bereitgestellten SQL-Pools zum Zeitpunkt der Bereitstellung angehalten sind, kann die Bereitstellung möglicherweise nicht erfolgreich durchgeführt werden.

Weitere Informationen finden Sie unter CI/CD in Azure Synapse Analytics Teil 4 - Die Release-Pipeline.

Einrichten einer Releasepipeline in Azure DevOps

In diesem Abschnitt erfahren Sie, wie Sie einen Azure Synapse-Arbeitsbereich in Azure DevOps bereitstellen.

1. Öffnen Sie in Azure DevOps das Projekt, das Sie für die Veröffentlichung erstellt haben.

2. Wählen Sie im linken Menü Pipelines>Releases.

   

3. Wählen Sie Neue Pipeline aus. Wenn Sie bestehende Pipelines haben, wählen Sie Neu>Neue Release-Pipeline.

4. Wählen Sie die Vorlage Leere Stufe aus.

   

5. Geben Sie in Stufenname den Namen Ihrer Umgebung ein.

6. Wählen Sie Artefakt hinzufügen, und wählen Sie dann das Git-Repository, das mit Azure Synapse Studio in Ihrer Entwicklungsumgebung konfiguriert ist. Wählen Sie das Git-Repository, in dem Sie Ihre Pools und Ihre Arbeitsbereich-ARM-Vorlage verwalten. Wenn Sie GitHub als Quelle verwenden, erstellen Sie eine Dienstverbindung für Ihr GitHub-Konto und ziehen Sie Repositories. Weitere Informationen finden Sie unter Dienstverbindungen.

   

7. Wählen Sie die Ressource ARM-Vorlagenzweig. Wählen Sie unter Standardversion die Option Letztes Element aus Standardbranch aus.

   

8. Wählen Sie für den Standardbranch der Artefakte das Repository publish branch oder andere nonpublish-Branches aus, die Synapse-Artefakte enthalten. Standardmäßig ist der Veröffentlichungszweig workspace_publish. Wählen Sie unter Standardversion die Option Letztes Element aus Standardbranch aus.

   

Einrichten einer Stage-Task für eine ARM-Vorlage zum Erstellen und Aktualisieren einer Ressource

Wenn Sie eine ARM-Vorlage haben, die eine Ressource bereitstellt, wie z. B. einen Azure Synapse-Arbeitsbereich, einen Spark- und SQL-Pool oder einen Schlüsseltresor, fügen Sie eine Azure Resource Manager-Bereitstellungsaufgabe hinzu, um diese Ressourcen zu erstellen oder zu aktualisieren:

1. Wählen Sie in der Stufenansicht die Option Stufenaufgaben anzeigen aus.

   

2. Erstellen Sie eine neue Aufgabe. Suchen Sie nach AMR-Vorlagenbereitstellung, und wählen Sie dann Hinzufügen aus.

3. Wählen Sie auf der Registerkarte Bereitstellung Aufgaben das Abonnement, die Ressourcengruppe und den Speicherort für den Arbeitsbereich. Geben Sie die Anmeldeinformationen an, falls dies erforderlich ist.

4. Wählen Sie für Aktion die Option Ressourcengruppe erstellen oder aktualisieren.

5. Wählen Sie für Vorlage die Ellipsenschaltfläche ( ... ). Gehen Sie zur ARM-Vorlage des Arbeitsbereichs.

6. Wählen Sie für Vorlagenparameter die Option … aus, um die Parameterdatei auszuwählen.

   

7. Wählen Sie für Vorlagenparameter überschreiben die Option ... und geben Sie dann die Parameterwerte ein, die Sie für den Arbeitsbereich verwenden möchten.

8. Wählen Sie für Entwicklungsmodus die Option Inkrementell.

9. (Optional) Fügen Sie Azure PowerShell für die Berechtigung hinzu und aktualisieren Sie die Zuweisung der Arbeitsbereichsrolle. Wenn Sie eine Freigabe-Pipeline verwenden, um einen Azure Synapse-Arbeitsbereich zu erstellen, wird der Dienstprinzipal der Pipeline als Standard-Arbeitsbereichsadministrator hinzugefügt. Sie können PowerShell ausführen, um anderen Konten Zugriff auf den Arbeitsbereich zu gewähren.

   

Warnung

Im Modus der vollständigen Bereitstellung werden Ressourcen in der Ressourcengruppe, die nicht in der neuen ARM-Vorlage angegeben sind, gelöscht. Weitere Informationen finden Sie unter Azure Resource Manager-Bereitstellungsmodi.

Einrichten einer Bühnenaufgabe für die Bereitstellung von Azure Synapse-Artefakten

Verwenden Sie die Erweiterung Synapse workspace deployment, um andere Elemente in Ihrem Azure Synapse-Arbeitsbereich bereitzustellen. Zu den Elementen, die Sie bereitstellen können, gehören Datasets, SQL-Skripts und Notebooks, Spark-Auftragsdefinitionen, Integration Runtime, Datenfluss, Anmeldeinformationen und andere Artefakte im Arbeitsbereich.

Installieren und Hinzufügen der Bereitstellungserweiterung

1. Suchen Sie nach der Erweiterung auf dem Visual Studio Marketplace und holen Sie diese dort ab.

   

2. Wählen Sie die Azure DevOps-Organisation aus, in der Sie die Erweiterung installieren möchten.

   

3. Vergewissern Sie sich, dass der Dienstprinzipal der Azure DevOps-Pipeline die Berechtigung Abonnement erhalten hat und als Synapse-Arbeitsbereich-Admin für den Arbeitsbereich zugewiesen ist.

4. Um eine neue Aufgabe zu erstellen, suchen Sie nach Synapse-Arbeitsbereichsbereitstellung, und wählen Sie dann Hinzufügen.

   

Konfigurieren der Bereitstellungsaufgabe

Die Bereitstellungsaufgabe unterstützt drei Arten von Vorgängen: „Nur überprüfen“, „Bereitstellen“ und „Überprüfen und Bereitstellen“.

Hinweis

Diese Erweiterung zur Bereitstellung des Arbeitsbereichs ist nicht abwärtskompatibel. Stellen Sie sicher, dass die neueste Version installiert ist und verwendet wird. Sie können die Versionshinweise in der Übersicht in Azure DevOps und die neueste Version in GitHub Actions lesen.

Überprüfen dient dazu, die Synapse-Artefakte im nonpublish-Branch mit der Aufgabe zu überprüfen und die Arbeitsbereichsvorlage und die Parametervorlagendatei zu generieren. Der Überprüfungsvorgang funktioniert nur in der YAML-Pipeline. Dies ist die YAML-Beispieldatei:

   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>'    

Überprüfen und Bereitstellen kann verwendet werden, um den Arbeitsbereich direkt aus dem nonpublish-Branch mit dem Stammordner für Artefakte bereitzustellen.

Hinweis

Die Bereitstellungsaufgabe muss Abhängigkeits-JS-Dateien von diesem Endpunkt web.azuresynapse.net herunterladen, wenn der Vorgangstyp als Überprüfen oder Überprüfen und Bereitstellen ausgewählt ist. Bitte stellen Sie sicher, dass der Endpunkt web.azuresynapse.net zulässig ist, wenn Netzwerkrichtlinien auf der VM aktiviert sind.

Der Überprüfungs- und Bereitstellungsvorgang funktioniert sowohl in der klassischen als auch in der YAML-Pipeline. Dies ist die YAML-Beispieldatei:

   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

Bereitstellen Zu den Eingaben des Vorgangs „Bereitstellen“ gehören die Arbeitsbereichs- und Parametervorlage von Synapse, die nach dem Veröffentlichen im Arbeitsbereich „Branch veröffentlichen“ oder nach der Überprüfung erstellt werden können. Sie entspricht Version 1.x.

Sie können die Vorgangstypen basierend auf dem Anwendungsfall wählen. Der folgende Teil ist ein Beispiel für „Bereitstellen“.

1. Wählen Sie in der Aufgabe den Vorgangstyp Bereitstellen aus.

   

2. Wählen Sie in der Aufgabe neben Vorlage die Option … aus, um die Vorlagendatei auszuwählen.

3. Wählen Sie neben Vorlagenparameter die Option … aus, um die Parameterdatei auszuwählen.

4. Wählen Sie eine Verbindung, eine Ressourcengruppe und einen Namen für den Arbeitsbereich.

5. Wählen Sie neben Vorlagenparameter überschreiben die Option … aus. Geben Sie die Parameterwerte ein, die Sie für den Arbeitsbereich verwenden möchten, einschließlich der Verbindungszeichenfolgen und Kontoschlüssel, die in Ihren verknüpften Diensten verwendet werden. Weitere Informationen finden Sie unter CI/CD in Azure Synapse Analytics.

   

6. Die Bereitstellung eines verwalteten privaten Endpunkts wird nur in Version 2.x unterstützt. Stellen Sie sicher, dass Sie die richtige Version auswählen, und aktivieren Sie die Option Verwaltete private Endpunkte in Vorlage bereitstellen.

   

7. Zum Verwalten von Triggern können Sie den Triggerumschalter verwenden, um die Trigger vor der Bereitstellung zu beenden. Sie können auch eine Aufgabe hinzufügen, um die Trigger nach der Bereitstellung neu zu starten.

   

Wichtig

In CI/CD-Szenarien muss der Typ der Integrationslaufzeit in den verschiedenen Umgebungen derselbe sein. Wenn Sie beispielsweise eine selbst gehostete Integrationslaufzeit in der Entwicklungsumgebung haben, muss dieselbe Integrationslaufzeit in anderen Umgebungen, wie z. B. in Test und Produktion, selbst gehostet sein. Wenn Sie Integrationslaufzeiten über mehrere Stufen hinweg gemeinsam nutzen, müssen die Integrationslaufzeiten in allen Umgebungen, z. B. in der Entwicklungs-, Test- und Produktionsumgebung, verknüpft und selbst gehostet sein.

Erstellen Sie eine Freigabe für die Bereitstellung

Nachdem Sie alle Änderungen gespeichert haben, können Sie Freigabe erstellen wählen, um manuell eine Freigabe zu erstellen. Wie Sie die Erstellung von Releases automatisieren können, erfahren Sie unter Azure DevOps Release Triggers.

Einrichten einer Freigabe in GitHub Actions

In diesem Abschnitt erfahren Sie, wie Sie GitHub-Workflows mithilfe von GitHub Actions für die Bereitstellung von Azure Synapse-Arbeitsbereichen erstellen.

Sie können die GitHub Actions für Azure Resource Manager-Vorlage verwenden, um die Bereitstellung einer ARM-Vorlage in Azure für den Arbeitsbereich und die Compute-Pools zu automatisieren.

Workflowdatei

Definieren Sie einen GitHub Actions-Workflow in einer YAML-Datei (.yml) unter dem Pfad /.github/workflows/ in Ihrem Repository. Die Definition enthält die verschiedenen Schritte und Parameter, aus denen der Workflow besteht.

Die .yml-Datei hat zwei Abschnitte:

`Section`	Aufgaben
Authentifizierung	1. Definieren eines Dienstprinzipals. 2. Erstellen eines GitHub-Geheimnisses.
Bereitstellen	Stellen Sie die Artefakte des Arbeitsbereichs bereit.

Konfigurieren von GitHub Actions-Geheimnissen

GitHub Actions Secrets sind Umgebungsvariablen, die verschlüsselt sind. Jeder, der über Collaborator-Berechtigungen für dieses Repository verfügt, kann diese Geheimnisse verwenden, um mit Aktionen im Repository zu interagieren.

1. Wählen Sie im GitHub-Repository die Registerkarte Einstellungen und dann die Option Geheimnisse>Neues Repository-Geheimnis.

   

2. Fügen Sie ein neues Geheimnis für die Client-ID hinzu, und fügen Sie ein neues Client-Geheimnis hinzu, wenn Sie den Dienstprinzipal für die Bereitstellung verwenden. Sie können auch wählen, ob Sie die Abonnement-ID und die Mandanten-ID als Geheimnisse speichern möchten.

Hinzufügen des Workflows

Gehen Sie in Ihrem GitHub-Repository zu Aktionen.

1. Klicken Sie auf Set up your workflow yourself (Workflow selbst einrichten).

2. Löschen Sie in der Workflow-Datei alles nach dem Abschnitt on:. Ihr verbleibender Arbeitsablauf könnte zum Beispiel so aussehen:

   name: CI
   
   on:
   push:
       branches: [ master ]
   pull_request:
       branches: [ master ]
   

3. Benennen Sie Ihren Arbeitsablauf um. Suchen Sie auf der Registerkarte Marktplatz nach der Aktion zur Bereitstellung des Synapse-Arbeitsbereichs und fügen Sie dann die Aktion hinzu.

   

4. Legen Sie die erforderlichen Werte und die Arbeitsbereichsvorlage fest:

   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'
   

5. Jetzt können Sie Ihre Änderungen festschreiben. Wählen Sie Übertragung starten, geben Sie den Titel ein und fügen Sie eine Beschreibung hinzu (optional). Wählen Sie dann Neue Datei übertragen.

   

   Die Datei erscheint im Ordner .github/workflows in Ihrem Repository.

   Hinweis

   Managed Identity wird nur mit selbst gehosteten VMs in Azure unterstützt. Stellen Sie sicher, dass der Runner auf "self-hosted" eingestellt ist. Aktivieren Sie die vom System zugewiesene verwaltete Identität für Ihre VM und fügen Sie diese zu Azure Synapse Studio als Synapse-Admin hinzu.

Überprüfen der Bereitstellung

1. Gehen Sie in Ihrem GitHub-Repository zu Aktionen.

2. Um detaillierte Protokolle der Ausführung Ihres Workflows zu sehen, öffnen Sie das erste Ergebnis:

   

Erstellen von benutzerdefinierten Parametern in der Arbeitsbereichsvorlage

Wenn Sie automatisiertes CI/CD verwenden und einige Eigenschaften während der Bereitstellung ändern möchten, diese aber nicht standardmäßig parametrisiert sind, können Sie die Standardparametervorlage überschreiben.

Um die Standardparametervorlage außer Kraft zu setzen, erstellen Sie eine benutzerdefinierte Parametervorlage mit dem Namentemplate-parameters-definition.json im Stammordner Ihres Git-Branchs. Sie müssen genau diesen Dateinamen verwenden. Wenn der Azure Synapse-Arbeitsbereich aus dem Kollaborationsbranch veröffentlicht wird oder die Bereitstellungsaufgabe die Artefakte in anderen Branches überprüft, wird diese Datei gelesen, und die Konfiguration wird zum Generieren der Parameter verwendet. Wenn Azure Synapse Arbeitsbereich diese Datei nicht findet, wird die Standardparametervorlage verwendet.

Benutzerdefinierte Parametersyntax

Sie können die folgenden Richtlinien verwenden, um eine benutzerdefinierte Parameterdatei zu erstellen:

• Geben Sie den Eigenschaftenpfad unter dem relevanten Entitätstyp ein.
• Wenn Sie einen Eigenschaftsnamen auf * setzen, bedeutet dies, dass Sie alle Eigenschaften unterhalb der Eigenschaft parametrisieren möchten (nur bis zur ersten Ebene, nicht rekursiv). Sie können Ausnahmen von dieser Konfiguration festlegen.
• Wenn Sie den Wert einer Eigenschaft als Zeichenfolge festlegen, geben Sie damit an, dass die Eigenschaft parametrisiert werden soll. Verwenden Sie das Format <action>:<name>:<stype>.
  • <action> kann für eines dieser Zeichen durchgeführt werden:
    • = bedeutet, dass der aktuelle Wert als Standardwert für den Parameter beibehalten werden soll.
    • - bedeutet, dass der Standardwert für den Parameter nicht beibehalten werden soll.
    • | ist ein Sonderfall für Geheimnisse aus Azure Key Vault für Verbindungszeichenfolgen oder Schlüssel.
  • <name> ist der Name des Parameters. Wenn dieser Wert leer ist, wird der Name der Eigenschaft verwendet. Beginnt der Wert mit dem Zeichen -, wird der Name gekürzt. AzureStorage1_properties_typeProperties_connectionString wird beispielsweise in AzureStorage1_connectionString gekürzt.
  • <stype> ist der Typ des Parameters. Wenn <stype> leer ist, wird standardmäßig der Typ string verwendet. Unterstützte Werte: string, securestring, int, bool, object, secureobject und array.
• Wenn Sie ein Array in der Datei angeben, bedeutet dies, dass die entsprechende Eigenschaft in der Vorlage ein Array ist. Azure Synapse iteriert durch alle Objekte im Array unter Verwendung der angegebenen Definition. Das zweite Objekt (eine Zeichenfolge) wird zum Namen der Eigenschaft, der bei jeder Iteration als Name für den Parameter verwendet wird.
• Eine Definition kann nicht spezifisch für eine Ressourceninstanz sein. Jede Definition gilt für alle Ressourcen dieses Typs.
• Standardmäßig sind alle sicheren Zeichenfolgen (z. B. Key Vault-Geheimnisse) und sicheren Zeichenfolgen (z. B. Verbindungszeichenfolgen, Schlüssel und Token) parametrisiert.

Beispiel für die Definition einer Parametervorlage

Im Folgenden finden Sie ein Beispiel für eine Parametervorlagendefinition:

{
    "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": "="
            }
        }
    }
}

Im Folgenden wird erläutert, wie die vorangehende Vorlage nach Ressourcentyp aufgebaut ist.

notebooks

• Jede Eigenschaft im properties/bigDataPool/referenceName-Pfad wird mit ihrem Standardwert parametrisiert. Sie können einen angehängten Spark-Pool für jede Notebook-Datei parametrisieren.

sqlscripts

• Im properties/content/currentConnection-Pfad werden sowohl die poolName- als auch die databaseName-Eigenschaften als Strings ohne die Standardwerte in der Vorlage parametrisiert.

pipelines

• Jede Eigenschaft im activities/typeProperties/waitTimeInSeconds-Pfad ist parametrisiert. Jede Aktivität in einer Pipeline, die eine Eigenschaft auf Codeebene mit dem Namen waitTimeInSeconds enthält (z. B. die Aktivität Wait), wird als Zahl mit einem Standardnamen parametrisiert. Die Eigenschaft hat keinen Standardwert in der Ressourcenmanager-Vorlage. Stattdessen wird die Eigenschaft während der Bereitstellung des Ressourcenmanagers als Eingabe benötigt.
• Die headers-Eigenschaft (zum Beispiel in einer Web-Aktivität) wird mit dem object-Typ (Objekt) parametrisiert. Die headers-Eigenschaft hat einen Standardwert, der derselbe ist wie der Wert der Quellfabrik.

integrationRuntimes

• Alle Eigenschaften im typeProperties-Pfad sind mit ihren jeweiligen Standardwerten parametrisiert. Zum Beispiel befinden sich zwei Eigenschaften unter IntegrationRuntimes type properties: computeProperties und ssisProperties. Beide Eigenschaftentypen werden mit ihren jeweiligen Standardwerten und -typen (Objekt) erstellt.

triggers

• Unter typeProperties sind zwei Eigenschaften parametrisiert:

  • Die Eigenschaft maxConcurrency hat einen Standardwert und ist vom Typ string. Der Standardparametername der maxConcurrency-Eigenschaft ist <entityName>_properties_typeProperties_maxConcurrency.
  • Die Eigenschaft recurrence wird ebenfalls parametrisiert. Alle Eigenschaften unter der Eigenschaft recurrence werden als Strings parametrisiert, mit Standardwerten und Parameternamen. Eine Ausnahme ist die Eigenschaft interval, die als Typ int parametrisiert ist. An den Parameternamen ist das Suffix <entityName>_properties_typeProperties_recurrence_triggerSuffix angehängt. Analog dazu ist die Eigenschaft freq eine Zeichenfolge und wird als Zeichenfolge parametrisiert. Die Eigenschaft freq wird jedoch ohne Standardwert parametrisiert. Der Name wird abgekürzt und mit einem Suffix versehen, z. B. <entityName>_freq.

  Hinweis

  Derzeit werden maximal 50 Trigger unterstützt.

linkedServices

• Verknüpfte Dienste sind ein Sonderfall. Da verknüpfte Dienste und Datasets eine breite Palette von Typen umfassen, können Sie eine typspezifische Anpassung vornehmen. Im vorangegangenen Beispiel wird für alle verknüpften Dienste des Typs AzureDataLakeStore eine bestimmte Vorlage angewendet. Für alle anderen (identifiziert durch die Verwendung des Zeichens *) wird eine andere Vorlage angewandt.
• Die Eigenschaft connectionString ist als securestring-Wert parametrisiert. Sie hat keinen Standardwert. Der Parametername wird verkürzt und mit dem Suffix connectionString versehen.
• Die secretAccessKey-Eigenschaft wird als AzureKeyVaultSecret-Wert parametrisiert (z. B. in einem mit Amazon S3 verknüpften Dienst). Die Eigenschaft wird automatisch als Azure Key Vault-Geheimnis parametrisiert und aus dem konfigurierten Key Vault abgerufen. Sie können auch den Schlüsseltresor selbst parametrisieren.

datasets

• Obwohl Sie Typen in Datasets anpassen können, ist eine explizite Konfiguration auf *-Ebene nicht erforderlich. Im vorherigen Beispiel werden alle Dataseteigenschaften unter typeProperties parametrisiert.

Bewährte Methoden für CI/CD

Wenn Sie die Git-Integration mit Ihrem Azure Synapse-Arbeitsbereich verwenden und über eine CI/CD-Pipeline verfügen, die Ihre Änderungen von der Entwicklung zum Test und dann zur Produktion weiterleitet, empfehlen wir die folgenden Best Practices:

• Integrieren Sie nur den Entwicklungsarbeitsbereich mit Git. Wenn Sie die Git-Integration verwenden, integrieren Sie nur Ihren Entwicklungs Azure Synapse-Arbeitsbereich in Git. Änderungen an den Test- und Produktionsarbeitsbereichen werden über CI/CD bereitgestellt, und eine Git-Integration wird hierfür nicht benötigt.
• Bereiten Sie Pools vor, bevor Sie Artefakte migrieren. Wenn Sie ein SQL-Skript oder ein Notizbuch haben, das mit Pools im Entwicklungsarbeitsbereich verbunden ist, verwenden Sie denselben Namen für Pools in verschiedenen Umgebungen.
• Synchronisieren Sie die Versionierung in Infrastruktur-als-Code-Szenarien. Um die Infrastruktur (Netzwerke, virtuelle Maschinen, Load Balancer und Verbindungstopologie) in einem beschreibenden Modell zu verwalten, verwenden Sie die gleiche Versionierung, die das DevOps-Team für den Quellcode verwendet.
• Prüfen Sie die Best Practices für Azure Data Factory. Wenn Sie Data Factory verwenden, lesen Sie die Best Practices für Data Factory Artefakte.

Fehlerbehebung bei der Bereitstellung von Artefakten

Verwenden der Bereitstellungsaufgabe des Synapse-Arbeitsbereichs zum Bereitstellen von Synapse-Artefakten

In Azure Synapse sind einige Artefakte, anders als in Data Factory, keine Resource Manager-Ressourcen. Sie können die ARM-Vorlagenbereitungsaufgabe nicht zur Bereitstellung von Azure Synapse-Artefakten verwenden. Verwenden Sie stattdessen die Bereitstellungsaufgabe des Synapse-Arbeitsbereichs zum Bereitstellen der Artefakte, und verwenden Sie für ARM-Ressourcen (Pools und Arbeitsbereiche) die ARM-Bereitstellungsaufgabe. Inzwischen unterstützt diese Aufgabe nur Synapse-Vorlagen, deren Ressourcen den Typ „Microsoft.Synapse“ aufweisen. Und mit dieser Aufgabe können Benutzer Änderungen von allen Branches automatisch bereitstellen, ohne manuell auf die Veröffentlichung in Synapse Studio zu klicken. Nachfolgend sind einige häufig angesprochene Probleme aufgeführt.

1. Fehler beim Veröffentlichen: Die ARM-Datei des Arbeitsbereichs ist größer als 20 MB.

Es gibt eine Einschränkung der Dateigröße vom Git-Anbieter, z. B. beträgt die maximale Dateigröße in Azure DevOps 20 MB. Wenn die Größe der Vorlagendatei für den Arbeitsbereich 20 MB überschreitet, tritt dieser Fehler auf, wenn Sie Änderungen in Synapse Studio veröffentlichen, bei denen die Arbeitsbereichsvorlagendatei generiert und mit Git synchronisiert wird. Zum Beheben des Problems können Sie die Synapse-Bereitstellungsaufgabe mit dem Vorgang Überprüfen oder Überprüfen und Bereitstellen verwenden, um die Arbeitsbereichsvorlagendatei direkt im Pipeline-Agent und ohne manuelle Veröffentlichung in Synapse Studio zu speichern.

2. Unerwarteter Tokenfehler in Release

Wenn Ihre Parameterdatei Parameterwerte enthält, die nicht escaped sind, kann die Freigabe-Pipeline die Datei nicht parsen und erzeugt einen unexpected token-Fehler. Wir schlagen vor, dass Sie Parameter überschreiben oder Key Vault verwenden, um Parameterwerte abzurufen. Sie können auch doppelte Escape-Zeichen verwenden, um das Problem zu beheben.

3. Fehler bei der Bereitstellung der Integration Runtime

Wenn Sie die Arbeitsbereichsvorlage aus einem verwalteten VNet-fähigen Arbeitsbereich generiert haben und versuchen, in einem regulären Arbeitsbereich bereitzustellen oder umgekehrt, tritt dieser Fehler auf.

4. Unerwartetes Zeichen beim Analysieren des Werts

Die Vorlage kann in der Vorlagendatei nicht geparst werden. Versuchen Sie, die umgekehrten Schrägstriche mit Escapezeichen zu versehen, z. B. „\\Test01\Test“.

5. Fehler beim Abrufen von Arbeitsbereichsinformationen, nicht gefunden

Die Informationen zum Zielarbeitsbereich wurden nicht ordnungsgemäß konfiguriert. Vergewissern Sie sich, dass die von Ihnen erstellte Dienstverbindung auf die Ressourcengruppe festgelegt ist, die den Arbeitsbereich enthält.

6. Fehler beim Löschen von Artefakten

Die Erweiterung vergleicht die Artefakte, die im Veröffentlichungsbranch vorhanden sind, mit der Vorlage. Auf der Grundlage des Unterschieds werden die Artefakte gelöscht. Vergewissern Sie sich, dass Sie nicht versuchen, ein Artefakt zu löschen, das im publish-Branch enthalten ist und auf das andere Artefakte verweisen oder von dem sie abhängig sind.

7. Fehler bei der Bereitstellung: JSON-Position 0

Wenn Sie versuchen, die Vorlage manuell zu aktualisieren, tritt dieser Fehler auf. Stellen Sie sicher, dass Sie die Vorlage nicht manuell bearbeitet haben.

8. Fehler bei Dokumenterstellung oder -aktualisierung aufgrund eines ungültigen Verweises

Auf das Artefakt in Synapse kann nicht durch ein anderes verwiesen werden. Wenn Sie ein Attribut parametrisiert haben, auf das in einem Artefakt verwiesen wird, achten Sie darauf, dass Sie einen korrekten Wert ungleich null angeben.

9. Fehler beim Abrufen des Bereitstellungsstatus bei der Notebookbereitstellung

Das Notebook, das Sie bereitstellen möchten, ist an einen Spark-Pool in der Arbeitsbereichsvorlagendatei angefügt, während der Pool im Zielarbeitsbereich in der Bereitstellung nicht vorhanden ist. Wenn Sie den Poolnamen nicht parametrisieren, achten Sie darauf, für die Pools in den beteiligten Umgebungen den gleichen Namen zu verwenden.