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 のデプロイ中にいくつかのプロパティを変更したいが、プロパティが既定でパラメーター化されていない。
ファクトリが非常に大きく、既定の Resource Manager テンプレートが許容されるパラメーターの上限 (256) よりも多いために無効である。
カスタム パラメーターの 256 の上限に対処するには、次の 3 つのオプションがあります。
- カスタム パラメーター ファイルを使用してパラメーター化を必要としない (既定値を保持できる) プロパティを削除して、パラメーターの数を減らします。
- データフローのロジックをリファクタリングして、パラメーターを減らします。たとえば、パイプライン パラメーターの値がすべて同じである場合は、代わりにグローバル パラメーターを使用できます。
- 1 つのデータ ファクトリを複数のデータ ファクトリに分割します。
既定の Resource Manager パラメーター構成をオーバーライドするには、 [管理] ハブに移動し、[ソース管理] セクションで [ARM テンプレート] を選択します。 [ARM パラメーター構成] セクションで、[パラメーター構成の編集] の [編集] アイコンをクリックして、Resource Manager パラメーター構成コード エディターを開きます。
Note
[ARM パラメーター構成] は、"Git モード" でのみ有効になります。 現在のところ、"ライブ モード" や "Data Factory" モードでは無効になります。
カスタムの Resource Manager パラメーター テンプレート構成を作成すると、Git ブランチのルート フォルダーに arm-template-parameters-definition.json という名前のファイルが作成されます。 正確なファイル名を使用する必要があります。
コラボレーション ブランチから発行すると、Data Factory では、このファイルを読み取り、その構成を利用してパラメーター化するプロパティが生成されます。 ファイルが見つからない場合は、既定のテンプレートが使用されます。
Resource Manager テンプレートをエクスポートすると、Data Factory により、コラボレーション ブランチでなく、現在作業中のどのブランチからでもこのファイルを読み取られます。 プライベート ブランチからファイルを作成または編集し、UI の [ARM テンプレートのエクスポート] を選択して変更内容をテストすることができます。 その後、このファイルをコラボレーション ブランチ内にマージできます。
Note
カスタムの 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 は、配列の統合ランタイム オブジェクトに指定された定義を使用することで、配列内のすべてのオブジェクトを反復処理します。 2 番目のオブジェクトである文字列は、各反復処理のパラメーターの名前として使用されるプロパティ名です。
- 定義をリソース インスタンスに固有にすることはできません。 定義はその型のすべてのリソースに適用されます。
- 既定では、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": "="
}
}
}
}
ここでは、前のテンプレートがどのように構築されるかについて、リソースの種類別に説明します。
パイプライン
- パス
activities/typeProperties/waitTimeInSeconds内のすべてのプロパティがパラメーター化されます。waitTimeInSecondsという名前のコードレベルのプロパティを持つパイプライン内のアクティビティ (たとえば、Waitアクティビティ) はすべて、既定の名前を使用して数値としてパラメーター化されます。 ただし、Resource Manager テンプレートにその既定値はありません。 これは Resource Manager デプロイ時に必須の入力になります。 - 同様に、
headersというプロパティ (たとえば、Webアクティビティ内の) は、型object(JObject) でパラメーター化されます。 これは、ソース ファクトリの値と同じ値である既定値を保持します。
IntegrationRuntimes
- パス
typePropertiesの下にあるすべてのプロパティは、それぞれの既定値を使用してパラメーター化されます。 たとえば、IntegrationRuntimes型のプロパティの下にはcomputePropertiesとssisPropertiesという 2 つのプロパティがあります。 両方のプロパティの型は、それぞれの既定の値と型 (Object) で作成されます。
トリガー
typePropertiesの下では、2 つのプロパティがパラメーター化されます。 1 つ目はmaxConcurrencyで、既定値を持つように指定されていて、型はstringです。 既定のパラメーター名<entityName>_properties_typeProperties_maxConcurrencyを持ちます。recurrenceプロパティもパラメーター化されます。 その下にあるそのレベルのすべてのプロパティは、既定の値とパラメーター名を持つ文字列としてパラメーター化されるよう指定されます。 例外は、型intとしてパラメーター化されるintervalプロパティです。 パラメーター名の末尾には<entityName>_properties_typeProperties_recurrence_triggerSuffixが付きます。 同様に、freqプロパティは文字列であり、文字列としてパラメーター化されます。 ただし、freqプロパティは既定値なしでパラメーター化されます。 名前は短縮され、サフィックスが付けられます。 たとえば、「<entityName>_freq」のように入力します。
LinkedServices
- リンクされたサービスは一意です。 リンクされたサービスとデータセットにはさまざまな型があるため、型固有のカスタマイズを行うことができます。 この例では、型
AzureDataLakeStoreのすべてのリンクされたサービスに対して、特定のテンプレートが適用されます。 他のすべての場合 (*を使用)、別のテンプレートが適用されます。 connectionStringプロパティは、securestring値としてパラメーター化されます。 既定値はありません。 これには、末尾にconnectionStringが付く、短縮されたパラメーター名が付けられます。- プロパティ
secretAccessKeyは (たとえば、Amazon S3 のリンクされたサービスでは)AzureKeyVaultSecretになることがあります。 Azure Key Vault シークレットとして自動的にパラメーター化され、構成済みのキー コンテナーからフェッチされます。 キー コンテナー自体もパラメーター化できます。
データセット
- データセットに型固有のカスタマイズを使用できますが、* レベルの構成を明示的に指定しなくても構成を指定できます。 前の例では、
typePropertiesの下にあるすべてのデータセット プロパティがパラメーター化されます。
Note
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 のパラメーター化
次の例は、既定のパラメーター化テンプレートに 1 つの値を追加する方法を示しています。 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": "="
}
}
}}
}