Resource Manager 템플릿에서 사용자 지정 매개 변수 사용
적용 대상:
Azure Data Factory 
Azure Synapse Analytics
팁
기업용 올인원 분석 솔루션인 Microsoft Fabric의 Data Factory를 사용해 보세요. Microsoft Fabric은 데이터 이동부터 데이터 과학, 실시간 분석, 비즈니스 인텔리전스 및 보고에 이르기까지 모든 것을 다룹니다. 무료로 새 평가판을 시작하는 방법을 알아봅니다!
개발 인스턴스에 연결된 Git 리포지토리가 있는 경우 템플릿을 게시하거나 내보내 생성된 Resource Manager 템플릿의 기본 Resource Manager 템플릿 매개 변수를 재정의할 수 있습니다. 다음 시나리오에서 기본 Resource Manager 매개 변수 구성을 재정의할 수 있습니다.
자동화 CI/CD를 사용하고 Resource Manager 배포 중에 일부 속성을 변경하려고 하지만 속성은 기본적으로 매개 변수화되지 않습니다.
팩터리가 너무 커서 허용되는 최대 매개 변수(256)를 초과했기 때문에 기본 Resource Manager 템플릿이 유효하지 않습니다.
다음 세 가지 옵션을 사용하여 사용자 지정 매개 변수 256 제한을 처리할 수 있습니다.
- 사용자 지정 매개 변수 파일을 사용하여 매개 변수화가 필요하지 않은 속성(예: 기본값을 유지할 수 있는 속성)을 제거하면 매개 변수 개수를 줄일 수 있습니다.
- 데이터 흐름의 논리를 리팩터링하여 매개 변수를 줄입니다. 예를 들어 파이프라인 매개 변수는 모두 동일한 값을 가지며, 대신 전역 매개 변수를 사용할 수 있습니다.
- 하나의 데이터 팩터리를 여러 데이터 팩터리로 분할합니다.
기본 Resource Manager 매개 변수 구성을 재정의하려면 관리 허브로 이동하고 “소스 제어” 섹션의 ARM 템플릿을 선택합니다. ARM 매개 변수 구성 섹션 아래 “매개 변수 구성 편집”의 편집 아이콘을 클릭하여 Resource Manager 매개 변수 구성 코드 편집기를 엽니다.
참고 항목
ARM 매개 변수 구성은 “GIT 모드”에서만 사용하도록 설정됩니다. 현재 “라이브 모드” 또는 “Data Factory” 모드에서는 사용할 수 없습니다.
사용자 지정 Resource Manager 매개 변수 구성을 생성하면 git 분기의 루트 폴더에 arm-template-parameters-definition.json이라는 파일이 생성됩니다. 정확한 파일 이름을 사용해야 합니다.
협업 분기에서 게시하는 경우 Data Factory가 이 파일을 읽고 해당 구성을 사용하여 매개 변수화된 속성을 생성합니다. 파일이 없는 경우 기본 템플릿이 사용됩니다.
Resource Manager 템플릿을 내보낼 때 Data Factory는 협업 분기가 아니라 현재 작업 중인 모든 분기에서 이 파일을 읽습니다. 프라이빗 분기에서 파일을 만들거나 편집할 수 있습니다. 여기서 UI의 ARM 템플릿 내보내기를 선택하여 변경 내용을 테스트할 수 있습니다. 그런 다음 협업 분기에 파일을 병합할 수 있습니다.
참고 항목
사용자 지정 Resource Manager 매개 변수 구성에서 ARM 템플릿 매개 변수 제한(256)을 변경하지 않습니다. 이를 통해 매개 변수화된 속성의 개수를 선택하고 줄일 수 있습니다.
사용자 지정 매개 변수 구문
다음은 사용자 지정 매개 변수 파일 arm-template-parameters-definition.json을 만들 때 따라야 할 지침입니다. 이 파일은 각 엔터티 형식에 대한 섹션(트리거, 파이프라인, 연결된 서비스, 데이터 세트, 통합 런타임 및 데이터 흐름)으로 구성되어 있습니다.
- 관련 엔터티 형식 아래에 속성 경로를 입력합니다.
- 속성 이름을
*로 설정하면 해당 속성 아래(재귀적이 아닌 첫 번째 수준까지만)의 모든 속성을 매개 변수화하려고 함을 나타냅니다. 이 구성에 대한 예외를 제공할 수도 있습니다. - 문자열로 속성의 값을 설정하면 속성을 매개 변수화하려고 함을 나타냅니다.
<action>:<name>:<stype>형식을 사용합니다.<action>은 다음 문자 중 하나일 수 있습니다.=는 현재 값을 매개 변수의 기본값으로 유지함을 의미합니다.-는 매개 변수의 기본값을 유지하지 않음을 의미합니다.|는 연결 문자열 또는 키와 관련한 Azure Key Vault의 비밀에 대한 특수 사례입니다.
<name>은 매개 변수의 이름입니다. 비어 있는 경우 속성의 이름을 사용합니다. 값이-문자로 시작하는 경우에는 이름이 짧아집니다. 예를 들어AzureStorage1_properties_typeProperties_connectionString에서AzureStorage1_connectionString으로 줄어듭니다.<stype>은 매개 변수의 형식입니다.<stype>이 비어 있는 경우 기본 형식은string입니다. 지원되는 값은string,securestring,int,bool,object,secureobject,array입니다.
- 정의 파일에서 배열을 지정하면 템플릿의 일치하는 속성이 배열임을 나타냅니다. Data Factory는 배열의 Integration Runtime 개체에 지정된 정의를 사용하여 배열에 있는 모든 개체를 반복합니다. 두 번째 개체, 문자열은 각 반복에 대한 매개 변수의 이름으로 사용되는 속성의 이름이 됩니다.
- 정의는 리소스 인스턴스와 관련될 수 없습니다. 모든 정의는 해당 형식의 모든 리소스에 적용됩니다.
- 기본적으로 Key Vault 비밀과 같은 모든 보안 문자열과 연결 문자열, 키, 토큰 등의 보안 문자열은 매개 변수화됩니다.
샘플 매개 변수화 템플릿
Resource Manager 매개 변수 구성의 예는 다음과 같습니다. 파이프라인 내에서 중첩된 활동의 매개 변수화 및 연결된 서비스 매개 변수의 defaultValue 변경을 포함하여 가능한 여러 사용의 예가 포함되어 있습니다.
{
"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": "="
}
}
}
}
다음은 리소스 종류별로 분할된 이전 템플릿의 구성 방법에 대한 설명입니다.
Pipelines
activities/typeProperties/waitTimeInSeconds경로에 있는 모든 속성은 매개 변수화됩니다.waitTimeInSeconds라는 코드 수준 속성(예:Wait작업)이 있는 파이프라인의 모든 작업은 기본 이름을 가진 숫자로 매개 변수화됩니다. 그러나 Resource Manager 템플릿에는 기본값이 없습니다. Resource Manager 배포 중에 입력해야 할 필수 항목입니다.- 마찬가지로
headers(예:Web작업)라는 속성은 형식object(JObject)로 매개 변수화됩니다. 이 값은 원본 팩터리의 값과 동일한 기본값을 갖습니다.
IntegrationRuntimes
typeProperties경로 아래에 있는 모든 속성은 해당 기본값을 사용하여 매개 변수화됩니다. 예를 들어IntegrationRuntimes형식 속성에는computeProperties및ssisProperties의 두 가지 속성이 있습니다. 두 속성 유형 모두 해당 기본값과 유형(Object)으로 만들어집니다.
트리거
typeProperties에서 두 개의 속성은 매개 변수화됩니다. 첫 번째 값은 기본값을 갖도록 지정된maxConcurrency이며string형식입니다. 이 값은 기본 매개 변수 이름<entityName>_properties_typeProperties_maxConcurrency를 갖습니다.recurrence속성도 매개 변수화됩니다. 이 속성 아래 수준의 모든 속성은 문자열로 매개 변수화되어 기본값 및 매개 변수 이름으로 지정됩니다. 단,int형식으로 매개 변수화되는interval속성은 예외입니다. 매개 변수 이름에는<entityName>_properties_typeProperties_recurrence_triggerSuffix가 접미사로 붙습니다. 마찬가지로freq속성은 문자열이며 문자열로 매개 변수화됩니다. 그러나freq속성은 기본값 없이 매개 변수화됩니다. 이름이 단축되고 접미사가 붙습니다. 예:<entityName>_freq.
LinkedServices
- 연결된 서비스는 고유합니다. 연결된 서비스 및 데이터 세트에는 다양한 형식이 있어 형식별로 사용자 지정할 수 있습니다. 이 예에서는
AzureDataLakeStore형식의 연결된 모든 서비스에 대해 특정 템플릿이 적용됩니다.*을 통한 다른 모든 서비스에 대해서는 다른 템플릿이 적용됩니다. connectionString속성은securestring값으로 매개 변수화됩니다. 기본값이 없습니다.connectionString이 접미사로 사용되는 축약된 매개 변수 이름이 포함됩니다.- 속성
secretAccessKey는AzureKeyVaultSecret(예: Amazon S3에 연결된 서비스)가 됩니다. 자동으로 Azure Key Vault 비밀로 매개 변수화되고 구성된 키 자격 증명 모음에서 페치됩니다. 키 자격 증명 모음을 자체적으로 매개 변수화할 수도 있습니다.
데이터 집합
- 데이터 세트에 대해 형식별 사용자 지정을 사용할 수 있지만, *-수준 구성을 명시적으로 사용하지 않고도 구성을 제공할 수 있습니다. 이전 예에서
typeProperties아래의 모든 데이터 세트 속성은 매개 변수화됩니다.
참고 항목
Azure 경고 및 매트릭스가 파이프라인에 대해 구성된 경우 현재 ARM 배포의 매개 변수로 지원되지 않습니다. 새 환경에서 경고 및 매트릭스를 다시 적용하려면 Data Factory 모니터링, 경고 및 매트릭스를 따르세요.
기본 매개 변수화 템플릿
다음은 현재의 기본 매개 변수화 템플릿입니다. 몇 개의 매개 변수만 추가해야 하는 경우 기존 매개 변수화 구조를 유지하므로 이 템플릿을 직접 편집하는 것이 좋습니다.
{
"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": {
"*": "="
}
}
}
예: 기존 Azure Databricks 대화형 클러스터 ID 매개 변수화
다음 예에서는 기본 매개 변수화 템플릿에 단일 값을 추가하는 방법을 보여 줍니다. Databricks 연결된 서비스의 기존 Azure Databricks 대화형 클러스터 ID를 매개 변수 파일에 추가하려고 합니다. 이 파일은 Microsoft.DataFactory/factories/linkedServices의 속성 필드에 existingClusterId를 추가하는 것을 제외하고 이전 파일과 동일합니다.
{
"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": "="
}
}
}}
}
관련 콘텐츠
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기