Usar parâmetros personalizados com o modelo do Resource Manager
APLICA-SE A:
Azure Data Factory 
Azure Synapse Analytics
Dica
Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!
Se a instância de desenvolvimento tiver um repositório Git associado, você poderá substituir os parâmetros de modelo do ARM padrão do modelo do ARM gerado pela publicação ou exportação do modelo. Você pode querer substituir a configuração padrão de parâmetro do Resource Manager nestes cenários:
Você usa CI/CD automatizadas e deseja alterar algumas propriedades durante a implantação do Resource Manager, mas as propriedades não são parametrizadas por padrão.
Seu alocador é tão grande que o modelo padrão do Resource Manager é inválido porque ele tem mais do que os parâmetros máximos permitidos (256).
Para lidar com o limite 256 do parâmetro personalizado, há três opções:
- Use o arquivo de parâmetro personalizado e remova as propriedades que não precisam de parametrização, ou seja, propriedades que podem manter um valor padrão e, portanto, diminuir a contagem de parâmetros.
- Refatore a lógica no fluxo de dados para reduzir os parâmetros, por exemplo, se todos os parâmetros de pipeline tiverem o mesmo valor, você pode usar apenas parâmetros globais em vez disso.
- Divida um data factory em vários data factories.
Para substituir a configuração padrão de parâmetro do Resource Manager, vá para o Gerenciar hub e selecione modelo do ARM na seção "controle do código-fonte". Na seção configuração do parâmetro ARM, clique no ícone Editar em "Editar configuração de parâmetros" para abrir o editor de código de configuração de parâmetros do Resource Manager.
Observação
A configuração do parâmetro ARM só está habilitada no "modo GIT". Atualmente, ele está desabilitado no "modo ao vivo" ou no modo "Data Factory".
A criação de uma configuração personalizada de parâmetros do Resource Manager gera um arquivo chamado arm-template-parameters-definition.json na pasta raiz do seu branch Git. Você deve usar esse nome de arquivo exato.
Ao publicar do branch de colaboração, o Data Factory lerá esse arquivo e usará a configuração dele para gerar quais propriedades são parametrizadas. Se nenhum arquivo for encontrado, o modelo padrão será usado.
Ao exportar um modelo do Resource Manager, o Data Factory lê esse arquivo de qualquer branch no qual você está trabalhando no momento, não o branch de colaboração. Você pode criar ou editar o arquivo de um branch privado, no qual você pode testar suas alterações selecionando Exportar modelo do ARM na interface do usuário. Em seguida, você pode mesclar o arquivo no branch de colaboração.
Observação
Uma configuração personalizada de parâmetros do Resource Manager não altera o limite 256 do parâmetro do modelo do ARM. Ele permite que você escolha e diminua o número de propriedades parametrizadas.
Sintaxe do parâmetro personalizado
Veja a seguir algumas diretrizes a serem seguidas ao criar o arquivo de parâmetros personalizados, arm-template-parameters-definition.json. O arquivo é composto por uma seção para cada tipo de entidade: gatilho, pipeline, serviço vinculado, conjunto de dados, runtime de integração e fluxo de dados.
- Insira o caminho da propriedade sob o tipo de entidade relevante.
- Definir um nome de propriedade como
*indica que você deseja parametrizar todas as propriedades sob ele (somente até o primeiro nível, não recursivamente). Você também pode fornecer exceções a essa configuração. - Definir o valor de uma propriedade como uma cadeia de caracteres indica que você deseja parametrizar a propriedade. Use o formato
<action>:<name>:<stype>.<action>pode ser um desses caracteres:=significa manter o valor atual como o valor padrão do parâmetro.-significa não manter o valor padrão do parâmetro.|é um caso especial para segredos do Azure Key Vault para cadeias de conexão ou chaves.
<name>é o nome do parâmetro. Se estiver em branco, será usado o nome da propriedade. Se o valor começar com um caractere-, o nome será abreviado. Por exemplo,AzureStorage1_properties_typeProperties_connectionStringseria abreviado comoAzureStorage1_connectionString.<stype>é o tipo de parâmetro. Se<stype>estiver em branco, o tipo padrão serástring. Valores com suporte:string,securestring,int,bool,object,secureobjectearray.
- Especificar uma matriz no arquivo de definição indica que a propriedade correspondente no modelo é uma matriz. O Data Factory itera todos os objetos na matriz usando a definição especificada no objeto do runtime de integração da matriz. O segundo objeto, uma cadeia de caracteres, torna-se o nome da propriedade, que é usada como o nome do parâmetro para cada iteração.
- Uma definição não pode ser específica a uma instância de recurso. Qualquer definição se aplica a todos os recursos desse tipo.
- Por padrão, todas as cadeias de caracteres seguras, como segredos do Key Vault, e cadeias de caracteres seguras, como cadeias de conexão, chaves e tokens, são parametrizadas.
Modelo de parametrização de exemplo
Aqui está um exemplo de como seria a aparência de uma configuração de parâmetro do Resource Manager. Ele contém exemplos de vários usos possíveis, incluindo parametrização de atividades aninhadas em um pipeline e alteração do defaultValue de um parâmetro de serviço vinculado.
{
"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": "="
}
}
}
}
Esta é uma explicação de como o modelo anterior é construído, dividido por tipo de recurso.
Pipelines
- Qualquer propriedade no caminho
activities/typeProperties/waitTimeInSecondsé parametrizada. Qualquer atividade em um pipeline que tenha uma propriedade de nível de código chamadawaitTimeInSeconds(por exemplo, a atividadeWait) é parametrizada como um número, com um nome padrão. Mas ela não terá um valor padrão no modelo do Resource Manager. Será uma entrada obrigatória durante a implantação do Resource Manager. - Da mesma forma, uma propriedade chamada
headers(por exemplo, em uma atividadeWeb) é parametrizada com o tipoobject(JObject). Ela tem um valor padrão, que é o mesmo valor do alocador de origem.
IntegrationRuntimes
- Todas as propriedades no caminho
typePropertiessão parametrizadas com os respectivos valores padrão. Por exemplo, há duas propriedades nas propriedades do tipoIntegrationRuntimes:computePropertiesessisProperties. Ambos os tipos de propriedade são criados com os respectivos valores e tipos padrão (Object).
Gatilhos
- Em
typeProperties, duas propriedades são parametrizadas. A primeira émaxConcurrency, que é especificada para ter um valor padrão e é do tipostring. Ela tem o nome de parâmetro padrão<entityName>_properties_typeProperties_maxConcurrency. - A propriedade
recurrencetambém é parametrizada. Nela, todas as propriedades nesse nível são especificadas para serem parametrizadas como cadeias de caracteres, com valores padrão e nomes de parâmetro. Uma exceção é a propriedadeinterval, parametrizada como tipoint. O nome do parâmetro tem sufixo<entityName>_properties_typeProperties_recurrence_triggerSuffix. Da mesma forma, a propriedadefreqé uma cadeia de caracteres e é parametrizada como uma cadeia de caracteres. No entanto, a propriedadefreqé parametrizada sem um valor padrão. O nome é abreviado e sufixado. Por exemplo,<entityName>_freq.
LinkedServices
- Os serviços vinculados são exclusivos. Como os serviços vinculados e os conjuntos de linhas têm uma ampla gama de tipos, você pode fornecer uma personalização específica de tipo. Neste exemplo, para todos os serviços vinculados do tipo
AzureDataLakeStore, um modelo específico será aplicado. Para todos os outros (por meio de*), um modelo diferente será aplicado. - A propriedade
connectionStringserá parametrizada como um valorsecurestring. Ela não terá um valor padrão. Ele terá um nome de parâmetro abreviado com o sufixoconnectionString. - A propriedade
secretAccessKeyé umaAzureKeyVaultSecret(por exemplo, em um serviço vinculado do Amazon S3). Ela é parametrizada automaticamente como um segredo do Azure Key Vault e buscada do cofre de chaves configurada. Você também pode parametrizar o cofre de chaves em si.
Conjunto de dados
- Embora a personalização específica de tipo esteja disponível para conjuntos de dados, você pode fornecer uma configuração sem ter explicitamente uma configuração de nível *-. No exemplo anterior, todas as propriedades de conjunto de dados em
typePropertiessão parametrizadas.
Observação
Se os alertas e as matrizes do Azure forem configurados para um pipeline, não terão suporte como parâmetros para implantações do ARM no momento. Para reaplicar os alertas e as matrizes em um novo ambiente, siga Monitoramento, alertas e matrizes do Data Factory.
Modelo de parametrização padrão
Veja abaixo o modelo de parametrização padrão atual. Se você precisar adicionar apenas alguns parâmetros, editar esse modelo diretamente pode ser uma boa ideia, pois você não perderá a estrutura de parametrização existente.
{
"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": {
"*": "="
}
}
}
Exemplo: parametrizar uma ID de cluster interativa do Azure Databricks existente
O exemplo a seguir mostra como adicionar um valor ao modelo de parametrização padrão. Queremos apenas adicionar uma ID de cluster interativa do Azure Databricks existente para um serviço vinculado do Databricks ao arquivo de parâmetros. Observe que esse arquivo é o mesmo que o arquivo anterior, exceto pela adição de existingClusterId no campo de propriedades de 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": "="
}
}
}}
}
Conteúdo relacionado
- Visão geral de integração e entrega contínuas
- Automatizar a integração contínua usando versões do Azure Pipelines
- Promover manualmente um modelo do Resource Manager para cada ambiente
- Modelos Vinculados do Resource Manager
- Como usar um ambiente de produção de hotfix
- Script pré e pós-implantação de exemplo