Usar parámetros personalizados con la plantilla de Resource Manager
SE APLICA A:
Azure Data Factory 
Azure Synapse Analytics
Sugerencia
Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. Obtenga información sobre cómo iniciar una nueva evaluación gratuita.
Si la instancia de desarrollo tiene un repositorio de Git asociado, puede invalidar los parámetros de plantilla de Resource Manager predeterminados de la plantilla de Resource Manager que se genera mediante la publicación o exportación de la plantilla. Es posible que desee reemplazar la configuración de parámetros de Resource Manager predeterminada en estos escenarios:
Se usa CI/CD automatizada y se quieren cambiar algunas propiedades durante la implementación de Resource Manager, pero las propiedades no están parametrizadas de forma predeterminada.
La fábrica es tan grande que la plantilla de Resource Manager predeterminada no es válida porque contiene más parámetros que el número máximo permitido (256).
Para controlar el límite de 256 parámetros personalizados, hay tres opciones:
- Use el archivo de parámetros personalizado y quite las propiedades que no necesitan parametrización, es decir, las que pueden mantener un valor predeterminado y, por tanto, reducir el recuento de parámetros.
- Refactorice la lógica en el flujo de datos para reducir los parámetros; por ejemplo, todos los parámetros de canalización tienen el mismo valor, solo puede usar parámetros globales en su lugar.
- Divida una factoría de datos en varias factorías de datos.
Para reemplazar la configuración de parámetros de Resource Manager predeterminada, vaya al centro Administrar y seleccione Plantilla de ARM en la sección "Control de código fuente". En la sección Configuración de parámetros de ARM, haga clic en el icono Editar en "Editar configuración de parámetros" para abrir el editor de código de configuración de parámetros de Resource Manager.
Nota:
La configuración del parámetros de ARM solo está habilitada en "modo GIT". Actualmente está deshabilitada en el" modo activo" o el modo de "Data Factory".
Al crear una configuración de parámetros de Resource Manager se crea un archivo denominado arm-template-parameters-definition.json en la carpeta raíz de la rama de Git. Debe usar ese nombre de archivo exacto.
Al realizar la publicación desde la rama de colaboración, Data Factory leerá este archivo y usará su configuración para generar las propiedades que se parametrizarán. Si no se encuentra ningún archivo, se usa la plantilla predeterminada.
Al exportar una plantilla de Resource Manager, Data Factory lee este archivo desde la rama en la que se está trabajando en ese momento, no la rama de colaboración. Puede crear o editar el archivo desde una rama privada, donde pueda probar los cambios si selecciona Export ARM Template (Exportar plantilla de ARM) en la interfaz de usuario. Después, puede combinar el archivo en la rama de colaboración.
Nota
Una configuración de parámetros de Resource Manager personalizada no cambia el límite de 256 parámetros de la plantilla de Resource Manager. Le permite elegir y reducir el número de propiedades parametrizadas.
Sintaxis de los parámetros personalizados
A continuación se indican algunas de las instrucciones que se deben seguir para crear el archivo de parámetros personalizados, arm-template-parameters-definition.json. El archivo consta de una sección para cada tipo de entidad: desencadenador, canalización, servicio vinculado, conjunto de datos, entorno de ejecución de integración i flujo de datos.
- Escriba la ruta de acceso de la propiedad en el tipo de entidad correspondiente.
- El establecimiento de un nombre de propiedad en
*indica que quiere parametrizar todas las propiedades que incluye (solo hasta el primer nivel, no de forma recursiva). También puede proporcionar excepciones a esta configuración. - El establecimiento del valor de una propiedad como una cadena indica que quiere parametrizar la propiedad. Use el formato
<action>:<name>:<stype>.<action>puede ser uno de estos caracteres:=significa que el valor actual se debe conservar como el predeterminado para el parámetro.-significa que no se debe conservar el valor predeterminado para el parámetro.|es un caso especial para los secretos de Azure Key Vault para cadenas de conexión o claves.
<name>es el nombre del parámetro. Si está en blanco, toma el nombre de la propiedad. Si el valor empieza por un carácter-, el nombre está abreviado. Por ejemplo,AzureStorage1_properties_typeProperties_connectionStringse abreviará aAzureStorage1_connectionString.<stype>es el tipo del parámetro. Si<stype>está en blanco, el tipo predeterminado esstring. Valores admitidos:string,securestring,int,bool,object,secureobjectyarray.
- Al especificar una matriz en el archivo de definición indica que la propiedad coincidente en la plantilla es una matriz. Data Factory recorre en iteración todos los objetos de la matriz mediante la definición especificada en el objeto del entorno de ejecución de integración de la matriz. El segundo objeto, una cadena, se convierte en el nombre de la propiedad, que se utiliza como el nombre del parámetro para cada iteración.
- Una definición no puede ser específica de una instancia de recurso. Cualquier definición se aplica a todos los recursos de ese tipo.
- De forma predeterminada, todas las cadenas seguras, como los secretos de Key Vault, las cadenas de conexión, las claves y los tokens, están parametrizadas.
Plantilla de parametrización de ejemplo
Este es un ejemplo del aspecto que podría tener una configuración de parámetros de Resource Manager. Contiene ejemplos de una serie de usos posibles, incluida la parametrización de actividades anidadas en una canalización y el cambio de defaultValue de un parámetro de servicio 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 es una explicación de cómo se construye la plantilla anterior, desglosada por tipo de recurso.
Procesos
- Cualquier propiedad de la ruta de acceso
activities/typeProperties/waitTimeInSecondsestá parametrizada. Cualquier actividad en una canalización que tiene una propiedad de nivel de código denominadawaitTimeInSeconds(por ejemplo, la actividadWait) está parametrizada como un número, con un nombre predeterminado. Sin embargo, no tendrá un valor predeterminado en la plantilla de Resource Manager. Será una entrada obligatoria durante la implementación de Resource Manager. - De forma similar, una propiedad denominada
headers(por ejemplo, en una actividadWeb) está parametrizada con el tipoobject(JObject). Tiene un valor predeterminado, que es el mismo que el de la factoría de origen.
IntegrationRuntimes
- Todas las propiedades bajo la ruta de acceso
typePropertiesestán parametrizadas con sus valores predeterminados correspondientes. Por ejemplo, hay dos propiedades en las propiedades de tipoIntegrationRuntimes:computePropertiesyssisProperties. Ambos tipos de propiedades se crean con sus valores predeterminados y tipos (objeto) respectivos.
Desencadenadores
- En
typeProperties, hay dos propiedades parametrizadas. La primera de ellas esmaxConcurrency, que tiene especificado un valor predeterminado y es de tipostring. Tiene el nombre de parámetro predeterminado<entityName>_properties_typeProperties_maxConcurrency. - La propiedad
recurrencetambién está parametrizada. En ella, se especifica que todas las propiedades de ese nivel están parametrizadas como cadenas, con valores predeterminados y los nombres de parámetro. Una excepción es la propiedadinterval, que está parametrizada como el tipoint. El sufijo del nombre del parámetro es<entityName>_properties_typeProperties_recurrence_triggerSuffix. De forma similar, la propiedadfreqes una cadena y está parametrizada como una cadena. Sin embargo, la propiedadfreqestá parametrizada sin un valor predeterminado. El nombre está abreviado y con un sufijo. Por ejemplo,<entityName>_freq.
LinkedServices
- Los servicios vinculados son únicos. Dado que los servicios vinculados y los conjuntos de datos tienen una gran variedad de tipos, puede proporcionar una personalización específica de tipo. En este ejemplo, para todos los servicios vinculados de tipo
AzureDataLakeStore, se aplicará una plantilla específica. Para todos los demás (a través de*), se aplicará otra plantilla. - La propiedad
connectionStringse parametrizará como un valorsecurestring. No tendrá un valor predeterminado. Tendrá un nombre de parámetro abreviado con el sufijoconnectionString. - La propiedad
secretAccessKeyresulta serAzureKeyVaultSecret(por ejemplo, en un servicio vinculado de Amazon S3). Se parametriza automáticamente como un secreto de Azure Key Vault y se captura desde el almacén de claves configurado. También puede parametrizar el propio almacén de claves.
Conjuntos de datos
- Aunque la personalización específica de tipos está disponible para conjuntos de datos, puede proporcionar la configuración sin necesidad de una configuración explícita de nivel *-. En el ejemplo anterior, todas las propiedades del conjunto de datos de
typePropertiesestán parametrizadas.
Nota
Si las alertas y matrices de Azure están configuradas para una canalización, no se admiten actualmente como parámetros para las implementaciones de ARM. Para volver a aplicar las alertas y las matrices en el nuevo entorno, siga las instrucciones de Supervisión, alertas y matrices de Data Factory.
Plantilla de parametrización predeterminada
A continuación se muestra la plantilla de parametrización predeterminada actual. Si solo tiene que agregar algunos parámetros, la modificación directa de esta plantilla puede ser una buena idea porque no perderá la estructura de parametrización 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": {
"*": "="
}
}
}
Ejemplo: Parametrización de un identificador de clúster interactivo de Azure Databricks existente
En el ejemplo siguiente se muestra cómo agregar un único valor a la plantilla de parametrización predeterminada. Solamente se quiere agregar al archivo de parámetros un identificador de clúster interactivo de Azure Databricks existente para un servicio vinculado de Databricks. Tenga en cuenta que este archivo es el mismo que el anterior, salvo por la adición de existingClusterId en el campo de propiedades 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": "="
}
}
}}
}
Contenido relacionado
- Información general de integración y entrega continuas
- Automatización de la integración continua mediante versiones de Azure Pipelines
- Promoción manual de una plantilla de Resource Manager para cada entorno
- Plantillas vinculadas de Resource Manager
- Uso de un entorno de producción de revisión
- Script de ejemplo anterior y posterior a la implementación
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente las Cuestiones de GitHub como mecanismo de retroalimentación para el contenido y lo sustituiremos por un nuevo sistema de retroalimentación. Para más información, consulta: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de