Utilizar parâmetros personalizados com o modelo do Resource Manager
APLICA-SE A:
Azure Data Factory 
Azure Synapse Analytics
Gorjeta
Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde a movimentação de dados até ciência de dados, análises em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!
Se sua instância de desenvolvimento tiver um repositório Git associado, você poderá substituir os parâmetros padrão do modelo do Resource Manager do modelo do Resource Manager gerado pela publicação ou exportação do modelo. Talvez você queira substituir a configuração de parâmetro padrão do Resource Manager nestes cenários:
Você usa CI/CD automatizado e deseja alterar algumas propriedades durante a implantação do Gerenciador de Recursos, mas as propriedades não são parametrizadas por padrão.
Sua fábrica é tão grande que o modelo padrão do Gerenciador de Recursos é inválido porque tem mais do que os parâmetros máximos permitidos (256).
Para lidar com o limite de parâmetro personalizado 256, há três opções:
- Use o arquivo de parâmetros personalizado e remova 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 parâmetros, por exemplo, os parâmetros de pipeline todos têm o mesmo valor, você pode simplesmente usar parâmetros globais.
- Divida uma fábrica de dados em várias fábricas de dados.
Para substituir a configuração de parâmetros padrão do Gerenciador de Recursos, vá para o hub Gerenciar e selecione o modelo ARM na seção "Controle do código-fonte". Na seção de configuração de parâmetros ARM, clique no ícone Editar em "Editar configuração de parâmetro" para abrir o editor de código de configuração de parâmetros do Gerenciador de Recursos.
Nota
A configuração do parâmetro ARM só é ativada no "modo GIT". Atualmente, está desativada nos modos “em direto” e “Data Factory”.
A criação de uma configuração de parâmetro personalizada do Resource Manager cria um arquivo chamado arm-template-parameters-definition.json na pasta raiz da ramificação git. Você deve usar esse nome de arquivo exato.
Ao publicar a partir da ramificação de colaboração, o Data Factory lerá esse arquivo e usará sua configuração para gerar quais propriedades serã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 ramificação em que você esteja trabalhando no momento, não da ramificação de colaboração. Você pode criar ou editar o arquivo de uma ramificação privada, onde pode testar suas alterações selecionando Exportar modelo ARM na interface do usuário. Em seguida, você pode mesclar o arquivo na ramificação de colaboração.
Nota
Uma configuração de parâmetro personalizada do Resource Manager não altera o limite de parâmetros do modelo ARM de 256. Ele permite que você escolha e diminua o número de propriedades parametrizadas.
Sintaxe do parâmetro personalizado
A seguir estão algumas diretrizes a serem seguidas ao criar o arquivo de parâmetros personalizados, arm-template-parameters-definition.json. O arquivo consiste em uma seção para cada tipo de entidade: gatilho, pipeline, serviço vinculado, conjunto de dados, tempo de execução 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. Utilize o formato
<action>:<name>:<stype>.<action>pode ser um destes personagens:=significa manter o valor atual como o valor padrão para o parâmetro.-significa não manter o valor padrão para o parâmetro.|é um caso especial para segredos do Cofre de Chaves do Azure para cadeias de conexão ou chaves.
<name>é o nome do parâmetro. Se estiver em branco, leva o nome da propriedade. Se o valor começar com um-caractere, o nome será encurtado. Por exemplo,AzureStorage1_properties_typeProperties_connectionStringseria encurtado paraAzureStorage1_connectionString.<stype>é o tipo de parâmetro. Se<stype>estiver em branco, o tipo padrão serástring. Valores suportados:string, , , ,objectboolsecureobjectsecurestringinte .array
- Especificar uma matriz no arquivo de definição indica que a propriedade correspondente no modelo é uma matriz. O Data Factory itera através de todos os objetos na matriz usando a definição especificada no objeto de tempo de execução de integração da matriz. O segundo objeto, uma cadeia de caracteres, torna-se o nome da propriedade, que é usado como o nome para o parâmetro para cada iteração.
- Uma definição não pode ser específica para uma instância de recurso. Qualquer definição aplica-se a todos os recursos desse tipo.
- Por padrão, todas as cadeias de caracteres seguras, como segredos do Cofre da Chave, 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 uma configuração de parâmetro do Resource Manager pode parecer. Ele contém exemplos de vários usos possíveis, incluindo parametrização de atividades aninhadas dentro de 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": "="
}
}
}
}
Aqui está 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, aWaitatividade) é parametrizada como um número, com um nome padrão. Mas ele não terá um valor padrão no modelo do Gerenciador de Recursos. Será uma entrada obrigatória durante a implantação do Resource Manager. - Da mesma forma, uma propriedade chamada
headers(por exemplo, em umaWebatividade) é parametrizada com typeobject(JObject). Ele tem um valor padrão, que é o mesmo valor que o da fábrica de origem.
IntegrationRuntimes
- Todas as propriedades sob o caminho
typePropertiessão parametrizadas com seus respetivos valores padrão. Por exemplo, há duas propriedades emIntegrationRuntimespropriedades de tipo:computePropertiesessisProperties. Ambos os tipos de propriedade são criados com seus respetivos valores e tipos padrão (Object).
Acionadores
- Em
typeProperties, duas propriedades são parametrizadas. O primeiro é , que é especificado para ter um valor padrão e émaxConcurrencydo tipostring. Ele tem o nome<entityName>_properties_typeProperties_maxConcurrencyde parâmetro padrão . - A
recurrencepropriedade também é parametrizada. Nele, todas as propriedades nesse nível são especificadas para serem parametrizadas como strings, com valores padrão e nomes de parâmetros. Uma exceção é aintervalpropriedade, que é parametrizada como tipoint. O nome do parâmetro é sufixo com<entityName>_properties_typeProperties_recurrence_triggerSuffix. Da mesma forma, afreqpropriedade é uma string e é parametrizada como uma string. No entanto, afreqpropriedade é parametrizada sem um valor padrão. O nome é abreviado e sufixado. Por exemplo,<entityName>_freq.
Serviços Vinculados
- Os serviços vinculados são únicos. Como os serviços vinculados e os conjuntos de dados têm uma ampla variedade de tipos, você pode fornecer personalização específica do tipo. Neste exemplo, para todos os serviços vinculados do tipo
AzureDataLakeStore, um modelo específico será aplicado. Para todos os outros (via*), um modelo diferente será aplicado. - A
connectionStringpropriedade será parametrizada como umsecurestringvalor. Ele não terá um valor padrão. Ele terá um nome de parâmetro abreviado que é sufixo comconnectionString. - A propriedade
secretAccessKeypassa a ser um (por exemplo, em umAzureKeyVaultSecretserviço vinculado do Amazon S3). Ele é parametrizado automaticamente como um segredo do Cofre de Chaves do Azure e buscado no cofre de chaves configurado. Você também pode parametrizar o próprio cofre de chaves.
Conjuntos de Dados
- Embora a personalização específica do tipo esteja disponível para conjuntos de dados, você pode fornecer configuração sem ter explicitamente uma configuração de nível *. No exemplo anterior, todas as propriedades do conjunto de dados em
typePropertiessão parametrizadas.
Nota
Se os alertas e matrizes do Azure estiverem configurados para um pipeline, eles não terão suporte atualmente como parâmetros para implantações ARM. Para reaplicar os alertas e matrizes em um novo ambiente, siga Data Factory Monitoring, Alerts and Matrices.
Modelo de parametrização padrão
Abaixo está o modelo de parametrização padrão atual. Se você precisar adicionar apenas alguns parâmetros, editar este modelo diretamente pode ser uma boa ideia, porque 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: Parametrizando uma ID de cluster interativo existente do Azure Databricks
O exemplo a seguir mostra como adicionar um único valor ao modelo de parametrização padrão. Queremos apenas adicionar uma ID de cluster interativo existente do Azure Databricks para um serviço vinculado do Databricks ao arquivo de parâmetros. Observe que esse arquivo é o mesmo que o arquivo anterior, exceto para a adição de sob o campo de propriedades de existingClusterIdMicrosoft.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údos relacionados
- Visão geral da integração contínua e da entrega
- Automatize a integração contínua usando versões do Azure Pipelines
- Promover manualmente um modelo do Resource Manager para cada ambiente
- Modelos do Gerenciador de Recursos Vinculados
- Usando um ambiente de produção de hotfix
- Exemplo de script pré e pós-implantação