Usar parâmetros personalizados com o modelo do Resource Manager

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

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.

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.

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_connectionString seria abreviado como AzureStorage1_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, secureobject e array.
• 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 chamada waitTimeInSeconds (por exemplo, a atividade Wait) é 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 atividade Web) é parametrizada com o tipo object (JObject). Ela tem um valor padrão, que é o mesmo valor do alocador de origem.

IntegrationRuntimes

• Todas as propriedades no caminho typeProperties são parametrizadas com os respectivos valores padrão. Por exemplo, há duas propriedades nas propriedades do tipo IntegrationRuntimes: computeProperties e ssisProperties. 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 recurrence també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 propriedade interval, parametrizada como tipo int. O nome do parâmetro tem sufixo <entityName>_properties_typeProperties_recurrence_triggerSuffix. Da mesma forma, a propriedade freq é uma cadeia de caracteres e é parametrizada como uma cadeia de caracteres. No entanto, a propriedade freq é 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 connectionString será parametrizada como um valor securestring. Ela não terá um valor padrão. Ele terá um nome de parâmetro abreviado com o sufixo connectionString.
• A propriedade secretAccessKey é uma AzureKeyVaultSecret (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 typeProperties são parametrizadas.

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