Aangepaste parameters gebruiken met Resource Manager-sjabloon

VAN TOEPASSING OP: Azure Data Factory Azure Synapse Analytics

Tip

Probeer Data Factory uit in Microsoft Fabric, een alles-in-één analyseoplossing voor ondernemingen. Microsoft Fabric omvat alles, van gegevensverplaatsing tot gegevenswetenschap, realtime analyses, business intelligence en rapportage. Meer informatie over het gratis starten van een nieuwe proefversie .

Als uw ontwikkelexemplaar een gekoppelde Git-opslagplaats heeft, kunt u de standaardparameters van de Resource Manager-sjabloon overschrijven die zijn gegenereerd door het publiceren of exporteren van de sjabloon. In deze scenario's kunt u de standaardparameterconfiguratie van Resource Manager overschrijven:

• U gebruikt geautomatiseerde CI/CD en u wilt bepaalde eigenschappen wijzigen tijdens de Implementatie van Resource Manager, maar de eigenschappen worden niet standaard geparameteriseerd.

• Uw fabriek is zo groot dat de standaard Resource Manager-sjabloon ongeldig is omdat deze meer dan de maximaal toegestane parameters (256) heeft.

  Er zijn drie opties om aangepaste parameterlimiet 256 te verwerken:

  • Gebruik het aangepaste parameterbestand en verwijder eigenschappen die geen parameterisatie nodig hebben, d.w.: eigenschappen die een standaardwaarde kunnen behouden en daarom het aantal parameters verlagen.
  • Herstructureer logica in de gegevensstroom om parameters te verminderen, bijvoorbeeld pijplijnparameters hebben allemaal dezelfde waarde. U kunt in plaats daarvan alleen globale parameters gebruiken.
  • Splits één data factory in meerdere data factory's.

Als u de standaardconfiguratie van de Resource Manager-parameter wilt overschrijven, gaat u naar de hub Beheren en selecteert u arm-sjabloon in de sectie Broncodebeheer. Klik in de sectie Configuratie van ARM-parameters op het pictogram Bewerken in Parameterconfiguratie bewerken om de configuratiecode-editor voor de Resource Manager-parameter te openen.

Notitie

Configuratie van ARM-parameters is alleen ingeschakeld in de GIT-modus. Deze is momenteel uitgeschakeld in de modus 'live' of 'Data Factory'.

Als u een aangepaste Resource Manager-parameterconfiguratie maakt, wordt een bestand met de naam arm-template-parameters-definition.json gemaakt in de hoofdmap van uw Git-vertakking. U moet die exacte bestandsnaam gebruiken.

Bij publicatie vanuit de samenwerkingsbranch leest Data Factory dit bestand en gebruikt data factory de configuratie om te genereren welke eigenschappen worden geparameteriseerd. Als er geen bestand wordt gevonden, wordt de standaardsjabloon gebruikt.

Wanneer u een Resource Manager-sjabloon exporteert, leest Data Factory dit bestand uit de vertakking waaraan u momenteel werkt, niet de samenwerkingsvertakking. U kunt het bestand maken of bewerken vanuit een privévertakking, waar u uw wijzigingen kunt testen door ARM-sjabloon exporteren te selecteren in de gebruikersinterface. Vervolgens kunt u het bestand samenvoegen in de samenwerkingsbranch.

Notitie

Een aangepaste Resource Manager-parameterconfiguratie wijzigt niet de parameterlimiet van de ARM-sjabloon van 256. Hiermee kunt u het aantal geparameteriseerde eigenschappen kiezen en verkleinen.

Aangepaste parametersyntaxis

Hier volgen enkele richtlijnen die u moet volgen wanneer u het aangepaste parameterbestand maakt, arm-template-parameters-definition.json. Het bestand bestaat uit een sectie voor elk entiteitstype: trigger, pijplijn, gekoppelde service, gegevensset, integratieruntime en gegevensstroom.

• Voer het eigenschapspad in onder het relevante entiteitstype.
• Als u een eigenschapsnaam instelt om aan te * geven dat u alle eigenschappen eronder wilt parameteriseren (alleen op het eerste niveau, niet recursief). U kunt ook uitzonderingen opgeven voor deze configuratie.
• Als u de waarde van een eigenschap instelt als een tekenreeks, geeft u aan dat u de eigenschap wilt parameteriseren. Gebruik de indeling <action>:<name>:<stype>.
  • <action> kan een van deze tekens zijn:
    • = betekent dat de huidige waarde behouden blijft als de standaardwaarde voor de parameter.
    • - betekent dat de standaardwaarde voor de parameter niet behouden blijft.
    • |is een speciaal geval voor geheimen uit Azure Key Vault voor verbindingsreeks s of sleutels.
  • <name> is de naam van de parameter. Als deze leeg is, wordt de naam van de eigenschap gebruikt. Als de waarde begint met een - teken, wordt de naam ingekort. Zou bijvoorbeeld AzureStorage1_properties_typeProperties_connectionString worden ingekort tot AzureStorage1_connectionString.
  • <stype> is het type parameter. Als <stype> dit leeg is, is stringhet standaardtype . Ondersteunde waarden: string, securestring, int, , bool, en arrayobjectsecureobject .
• Het opgeven van een matrix in het definitiebestand geeft aan dat de overeenkomende eigenschap in de sjabloon een matrix is. Data Factory doorloopt alle objecten in de matrix met behulp van de definitie die is opgegeven in het integration runtime-object van de matrix. Het tweede object, een tekenreeks, wordt de naam van de eigenschap, die wordt gebruikt als de naam voor de parameter voor elke iteratie.
• Een definitie kan niet specifiek zijn voor een resource-exemplaar. Elke definitie is van toepassing op alle resources van dat type.
• Standaard worden alle beveiligde tekenreeksen, zoals Key Vault-geheimen en beveiligde tekenreeksen, zoals verbindingsreeks s, sleutels en tokens, geparameteriseerd.

Voorbeeldsjabloon voor parameterisering

Hier volgt een voorbeeld van hoe een Resource Manager-parameterconfiguratie eruit kan zien. Het bevat voorbeelden van een aantal mogelijke gebruiksgegevens, waaronder parameterisatie van geneste activiteiten in een pijplijn en het wijzigen van de defaultValue van een gekoppelde serviceparameter.

{
    "Microsoft.DataFactory/factories/pipelines": {
        "properties": {
            "activities": [{
                "typeProperties": {
                    "waitTimeInSeconds": "-::int",
                    "headers": "=::object",
                    "activities": [
                        {
                            "typeProperties": {
                                "url": "-:-webUrl:string"
                            }
                        }
                    ]
                }
            }]
        }
    },
    "Microsoft.DataFactory/factories/integrationRuntimes": {
        "properties": {
            "typeProperties": {
                "*": "="
            }
        }
    },
    "Microsoft.DataFactory/factories/triggers": {
        "properties": {
            "typeProperties": {
                "recurrence": {
                    "*": "=",
                    "interval": "=:triggerSuffix:int",
                    "frequency": "=:-freq"
                },
                "maxConcurrency": "="
            }
        }
    },
    "Microsoft.DataFactory/factories/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.DataFactory/factories/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/credentials" : {
        "properties": {
            "typeProperties": {
                "resourceId": "="
            }
        }
    }
}

Hier volgt een uitleg van hoe de voorgaande sjabloon wordt samengesteld, onderverdeeld op resourcetype.

Pipelines

• Een eigenschap in het pad activities/typeProperties/waitTimeInSeconds wordt geparameteriseerd. Elke activiteit in een pijplijn met een eigenschap op codeniveau met de naam waitTimeInSeconds (bijvoorbeeld de Wait activiteit) wordt geparameteriseerd als een getal, met een standaardnaam. Maar deze heeft geen standaardwaarde in de Resource Manager-sjabloon. Dit is een verplichte invoer tijdens de Resource Manager-implementatie.
• Op dezelfde manier wordt een eigenschap met de naam headers (bijvoorbeeld in een Web activiteit) geparameteriseerd met het type object (JObject). Deze heeft een standaardwaarde, die dezelfde waarde is als die van de bronfactory.

IntegrationRuntimes

• Alle eigenschappen onder het pad typeProperties worden geparameteriseerd met hun respectieve standaardwaarden. Er zijn bijvoorbeeld twee eigenschappen onder IntegrationRuntimes typeeigenschappen: computeProperties en ssisProperties. Beide eigenschapstypen worden gemaakt met hun respectieve standaardwaarden en typen (Object).

Triggers

• Onder typePropertiesworden twee eigenschappen geparameteriseerd. De eerste is maxConcurrency, die is opgegeven om een standaardwaarde te hebben en is van het type string. Deze heeft de standaardparameternaam <entityName>_properties_typeProperties_maxConcurrency.
• De recurrence eigenschap wordt ook geparameteriseerd. Daaronder worden alle eigenschappen op dat niveau opgegeven om te worden geparameteriseerd als tekenreeksen, met standaardwaarden en parameternamen. Een uitzondering is de interval eigenschap, die wordt geparameteriseerd als type int. De parameternaam wordt achtervoegseld met <entityName>_properties_typeProperties_recurrence_triggerSuffix. Op dezelfde manier is de freq eigenschap een tekenreeks en wordt deze geparameteriseerd als een tekenreeks. De freq eigenschap wordt echter geparameteriseerd zonder een standaardwaarde. De naam wordt ingekort en achtervoegseld. Bijvoorbeeld: <entityName>_freq.

LinkedServices

• Gekoppelde services zijn uniek. Omdat gekoppelde services en gegevenssets een breed scala aan typen hebben, kunt u typespecifieke aanpassingen bieden. In dit voorbeeld wordt voor alle gekoppelde services van het type AzureDataLakeStoreeen specifieke sjabloon toegepast. Voor alle andere (via *) wordt een andere sjabloon toegepast.
• De connectionString eigenschap wordt geparameteriseerd als een securestring waarde. Deze heeft geen standaardwaarde. Deze heeft een verkorte parameternaam die is achtervoegseld met connectionString.
• De eigenschap secretAccessKey is AzureKeyVaultSecret een (bijvoorbeeld in een gekoppelde Amazon S3-service). Deze wordt automatisch geparameteriseerd als een Azure Key Vault-geheim en opgehaald uit de geconfigureerde sleutelkluis. U kunt ook de sleutelkluis zelf parameteriseren.

Gegevenssets

• Hoewel typespecifieke aanpassing beschikbaar is voor gegevenssets, kunt u configuratie bieden zonder expliciet een configuratie op *-niveau te hebben. In het voorgaande voorbeeld worden alle eigenschappen van de gegevensset onder typeProperties geparameteriseerd.

Notitie

Als Azure-waarschuwingen en matrices zijn geconfigureerd voor een pijplijn, worden deze momenteel niet ondersteund als parameters voor ARM-implementaties. Als u de waarschuwingen en matrices opnieuw wilt toepassen in een nieuwe omgeving, volgt u Data Factory-bewaking, waarschuwingen en matrices.

Standaardparameterisatiesjabloon

Hieronder ziet u de huidige standaardparameterisatiesjabloon. Als u slechts enkele parameters wilt toevoegen, is het bewerken van deze sjabloon mogelijk een goed idee omdat u de bestaande parameterisatiestructuur niet kwijtraakt.

{
    "Microsoft.DataFactory/factories": {
        "properties": {
            "globalParameters": {
                "*": {
                    "value": "="
                }
            }
        },
        "location": "="
    },
    "Microsoft.DataFactory/factories/globalparameters": {
        "properties": {
                "*": { 
                    "value": "=" 
                }
        }
    },
    "Microsoft.DataFactory/factories/pipelines": {
    },
    "Microsoft.DataFactory/factories/dataflows": {
    },
    "Microsoft.DataFactory/factories/integrationRuntimes":{
        "properties": {
            "typeProperties": {
                "ssisProperties": {
                    "catalogInfo": {
                        "catalogServerEndpoint": "=",
                        "catalogAdminUserName": "=",
                        "catalogAdminPassword": {
                            "value": "-::secureString"
                        }
                    },
                    "customSetupScriptProperties": {
                        "sasToken": {
                            "value": "-::secureString"
                        }
                    }
                },
                "linkedInfo": {
                    "key": {
                        "value": "-::secureString"
                    },
                    "resourceId": "="
                },
                "computeProperties": {
                    "dataFlowProperties": {
                        "externalComputeInfo": [{
                                "accessToken": "-::secureString"
                            }
                        ]
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/triggers": {
        "properties": {
            "pipelines": [{
                    "parameters": {
                        "*": "="
                    }
                }
            ],
            "pipeline": {
                "parameters": {
                    "*": "="
                }
            },
            "typeProperties": {
                "scope": "="
            }
        }
    },
    "Microsoft.DataFactory/factories/linkedServices": {
        "*": {
            "properties": {
                "typeProperties": {
                    "accountName": "=",
                    "username": "=",
                    "userName": "=",
                    "accessKeyId": "=",
                    "servicePrincipalId": "=",
                    "userId": "=",
                    "host": "=",
                    "clientId": "=",
                    "clusterUserName": "=",
                    "clusterSshUserName": "=",
                    "hostSubscriptionId": "=",
                    "clusterResourceGroup": "=",
                    "subscriptionId": "=",
                    "resourceGroupName": "=",
                    "tenant": "=",
                    "dataLakeStoreUri": "=",
                    "baseUrl": "=",
                    "database": "=",
                    "serviceEndpoint": "=",
                    "batchUri": "=",
                    "poolName": "=",
                    "databaseName": "=",
                    "systemNumber": "=",
                    "server": "=",
                    "url":"=",
                    "functionAppUrl":"=",
                    "environmentUrl": "=",
                    "aadResourceId": "=",
                    "sasUri": "|:-sasUri:secureString",
                    "sasToken": "|",
                    "connectionString": "|:-connectionString:secureString",
                    "hostKeyFingerprint": "="
                }
            }
        },
        "Odbc": {
            "properties": {
                "typeProperties": {
                    "userName": "=",
                    "connectionString": {
                        "secretName": "="
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/managedVirtualNetworks/managedPrivateEndpoints": {
        "properties": {
            "*": "="
        }
    }
}

Voorbeeld: Een bestaande interactieve Cluster-id van Azure Databricks parameteriseren

In het volgende voorbeeld ziet u hoe u één waarde toevoegt aan de standaardparametersjabloon. We willen alleen een bestaande interactieve Azure Databricks-cluster-id toevoegen voor een Databricks-gekoppelde service aan het parameterbestand. Houd er rekening mee dat dit bestand hetzelfde is als het vorige bestand, met uitzondering van de toevoeging onder existingClusterId het eigenschappenveld van Microsoft.DataFactory/factories/linkedServices.

{
    "Microsoft.DataFactory/factories": {
        "properties": {
            "globalParameters": {
                "*": {
                    "value": "="
                }
            }
        },
        "location": "="
    },
    "Microsoft.DataFactory/factories/pipelines": {
    },
    "Microsoft.DataFactory/factories/dataflows": {
    },
    "Microsoft.DataFactory/factories/integrationRuntimes":{
        "properties": {
            "typeProperties": {
                "ssisProperties": {
                    "catalogInfo": {
                        "catalogServerEndpoint": "=",
                        "catalogAdminUserName": "=",
                        "catalogAdminPassword": {
                            "value": "-::secureString"
                        }
                    },
                    "customSetupScriptProperties": {
                        "sasToken": {
                            "value": "-::secureString"
                        }
                    }
                },
                "linkedInfo": {
                    "key": {
                        "value": "-::secureString"
                    },
                    "resourceId": "="
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/triggers": {
        "properties": {
            "pipelines": [{
                    "parameters": {
                        "*": "="
                    }
                }
            ],
            "pipeline": {
                "parameters": {
                    "*": "="
                }
            },
            "typeProperties": {
                "scope": "="
            }
 
        }
    },
    "Microsoft.DataFactory/factories/linkedServices": {
        "*": {
            "properties": {
                "typeProperties": {
                    "accountName": "=",
                    "username": "=",
                    "userName": "=",
                    "accessKeyId": "=",
                    "servicePrincipalId": "=",
                    "userId": "=",
                    "clientId": "=",
                    "clusterUserName": "=",
                    "clusterSshUserName": "=",
                    "hostSubscriptionId": "=",
                    "clusterResourceGroup": "=",
                    "subscriptionId": "=",
                    "resourceGroupName": "=",
                    "tenant": "=",
                    "dataLakeStoreUri": "=",
                    "baseUrl": "=",
                    "database": "=",
                    "serviceEndpoint": "=",
                    "batchUri": "=",
                    "poolName": "=",
                    "databaseName": "=",
                    "systemNumber": "=",
                    "server": "=",
                    "url":"=",
                    "aadResourceId": "=",
                    "connectionString": "|:-connectionString:secureString",
                    "existingClusterId": "-"
                }
            }
        },
        "Odbc": {
            "properties": {
                "typeProperties": {
                    "userName": "=",
                    "connectionString": {
                        "secretName": "="
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }}
}

Gerelateerde inhoud

• Overzicht van continue integratie en levering
• Continue integratie automatiseren met Azure Pipelines-versies
• Een Resource Manager-sjabloon handmatig promoveren naar elke omgeving
• Gekoppelde Resource Manager-sjablonen
• Een hotfix-productieomgeving gebruiken
• Voorbeeldscript vóór en na implementatie