搭配使用自訂參數與 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 限制：

    • 使用自訂參數檔案並移除不需要參數化的屬性，意即可保留預設值的屬性，進而減少參數計數。
    • 重構資料流程中的邏輯以減少參數，例如管線參數都有相同的值，您可使用全域參數取而代之。
    • 將一個資料處理站分割成多個資料處理站。

若要覆寫預設 Resource Manager 參數設定，請移至 [管理] 中樞，然後在「原始檔控制」區段中選取 [ARM 範本]。 在 [ARM 參數設定] 區段下，按一下「編輯參數設定」中的 [編輯] 圖示，開啟 Resource Manager 參數設定程式碼編輯器。

Manage custom parameters

注意

ARM 參數設定 只會在「GIT 模式」中啟用。 目前已在「即時模式」或「Data Factory」模式中停用。

建立自訂 Resource Manager 參數設定後，您的 Git 分支根資料夾中會建立名為 arm-template-parameters-definition.json 的檔案。 您必須使用該確切的檔案名稱。

Custom parameters file

從協作分支發佈時，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 會使用陣列整合執行階段物件中指定的定義，逐一查看陣列中的所有物件。 第二個物件 (字串) 會成為屬性的名稱，該名稱會做為每個反覆項目的參數名稱。
  • 定義不能專屬於資源執行個體。 任何定義都會套用至該類型的所有資源。
  • 根據預設，所有安全字串 (例如 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。 這兩個屬性類型都是使用其各自的預設值和類型 (物件) 來建立。

觸發程序

  • 在 typeProperties 底下，有兩個屬性已參數化。 第一個是 maxConcurrency，其已指定為具有預設值且類型為 string。 其具有預設參數名稱 <entityName>_properties_typeProperties_maxConcurrency。
  • recurrence 屬性也已參數化。 在其底下，該層級的所有屬性都已指定成要參數化為字串，且具有預設值和參數名稱。 interval 屬性為例外狀況，其已參數化為 int 類型。 參數名稱後面會加上 <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 互動式叢集識別碼

下列範例顯示如何將單一值新增至預設參數化範本。 我們只想要將 Databricks 連結服務的現有 Azure Databricks 互動式叢集識別碼新增到 parameters 檔案。 請注意，除了在 Microsoft.DataFactory/factories/linkedServices 的 properties 欄位下新增 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": "="
                }
            }
        }}
}

相關內容