Använda anpassade parametrar med Resource Manager-mallen

GÄLLER FÖR: Azure Data Factory Azure Synapse Analytics

Dricks

Prova Data Factory i Microsoft Fabric, en allt-i-ett-analyslösning för företag. Microsoft Fabric omfattar allt från dataflytt till datavetenskap, realtidsanalys, business intelligence och rapportering. Lär dig hur du startar en ny utvärderingsversion kostnadsfritt!

Om din utvecklingsinstans har en associerad Git-lagringsplats kan du åsidosätta standardparametrarna för Resource Manager-mallen som genereras genom att publicera eller exportera mallen. Du kanske vill åsidosätta standardkonfigurationen av Resource Manager-parametern i följande scenarier:

• Du använder automatiserad CI/CD och vill ändra vissa egenskaper under Resource Manager-distributionen, men egenskaperna parametriseras inte som standard.

• Din fabrik är så stor att standardmallen för Resource Manager är ogiltig eftersom den har fler än de högsta tillåtna parametrarna (256).

  Det finns tre alternativ för att hantera gränsen för anpassad parameter 256:

  • Använd den anpassade parameterfilen och ta bort egenskaper som inte behöver parameterisering, d.v.s. egenskaper som kan behålla ett standardvärde och därmed minska antalet parametrar.
  • Refaktorlogik i dataflödet för att minska parametrar, till exempel att pipelineparametrar har samma värde. Du kan bara använda globala parametrar i stället.
  • Dela upp en datafabrik i flera datafabriker.

Om du vill åsidosätta standardkonfigurationen av Resource Manager-parametern går du till hantera hubben och väljer ARM-mall i avsnittet "Källkontroll". Under avsnittet KONFIGURATION av ARM-parameter klickar du på Ikonen Redigera i "Redigera parameterkonfiguration" för att öppna resource manager-parameterns konfigurationskodredigerare.

Kommentar

ARM-parameterkonfigurationen är endast aktiverad i "GIT-läge". För närvarande är den inaktiverad i ”liveläge” och ”Data Factory-läge”.

När du skapar en anpassad Resource Manager-parameterkonfiguration skapas en fil med namnet arm-template-parameters-definition.json i rotmappen för git-grenen. Du måste använda det exakta filnamnet.

När du publicerar från samarbetsgrenen läser Data Factory den här filen och använder dess konfiguration för att generera vilka egenskaper som parametriseras. Om ingen fil hittas används standardmallen.

När du exporterar en Resource Manager-mall läser Data Factory den här filen från vilken gren du arbetar med, inte samarbetsgrenen. Du kan skapa eller redigera filen från en privat gren, där du kan testa ändringarna genom att välja Exportera ARM-mall i användargränssnittet. Du kan sedan sammanfoga filen till samarbetsgrenen.

Kommentar

En anpassad Resource Manager-parameterkonfiguration ändrar inte parametergränsen för ARM-mallen på 256. Med den kan du välja och minska antalet parametriserade egenskaper.

Syntax för anpassad parameter

Följande är några riktlinjer att följa när du skapar filen med anpassade parametrar, arm-template-parameters-definition.json. Filen består av ett avsnitt för varje entitetstyp: utlösare, pipeline, länkad tjänst, datauppsättning, integrationskörning och dataflöde.

• Ange egenskapssökvägen under relevant entitetstyp.
• Om du anger ett egenskapsnamn till * anger du att du vill parameterisera alla egenskaper under den (endast ned till den första nivån, inte rekursivt). Du kan också ange undantag för den här konfigurationen.
• Om du anger värdet för en egenskap som en sträng anger du att du vill parameterisera egenskapen. Använd formatet <action>:<name>:<stype>.
  • <action> kan vara något av följande tecken:
    • = innebär att behålla det aktuella värdet som standardvärde för parametern.
    • - innebär att du inte behåller standardvärdet för parametern.
    • |är ett specialfall för hemligheter från Azure Key Vault för niska veze eller nycklar.
  • <name> är namnet på parametern. Om den är tom tar den namnet på egenskapen. Om värdet börjar med ett - tecken förkortas namnet. Till exempel AzureStorage1_properties_typeProperties_connectionString skulle förkortas till AzureStorage1_connectionString.
  • <stype> är parametertypen. Om <stype> är tom är stringstandardtypen . Värden som stöds: string, securestring, int, bool, secureobject objectoch array.
• Om du anger en matris i definitionsfilen anger du att den matchande egenskapen i mallen är en matris. Data Factory itererar genom alla objekt i matrisen med hjälp av definitionen som anges i matrisens integreringskörningsobjekt. Det andra objektet, en sträng, blir namnet på egenskapen, som används som namn på parametern för varje iteration.
• En definition kan inte vara specifik för en resursinstans. Alla definitioner gäller för alla resurser av den typen.
• Som standard parametriseras alla säkra strängar, till exempel Key Vault-hemligheter och säkra strängar, till exempel niska veze, nycklar och token.

Exempelparameteriseringsmall

Här är ett exempel på hur en Resource Manager-parameterkonfiguration kan se ut. Den innehåller exempel på ett antal möjliga användningar, inklusive parameterisering av kapslade aktiviteter i en pipeline och ändring av defaultValue för en länkad tjänstparameter.

{
    "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": "="
            }
        }
    }
}

Här är en förklaring av hur den föregående mallen konstrueras, uppdelad efter resurstyp.

Pipelines

• Alla egenskaper i sökvägen activities/typeProperties/waitTimeInSeconds parametriseras. Alla aktiviteter i en pipeline som har en kodnivåegenskap med namnet waitTimeInSeconds (till exempel Wait aktiviteten) parametriseras som ett tal med ett standardnamn. Men det har inget standardvärde i Resource Manager-mallen. Det blir en obligatorisk inmatning under Resource Manager-distributionen.
• På samma sätt parametriseras en egenskap som heter headers (till exempel i en Web aktivitet) med typen object (JObject). Det har ett standardvärde, vilket är samma värde som för källfabriken.

IntegrationRuntimes

• Alla egenskaper under sökvägen typeProperties parametriseras med respektive standardvärden. Det finns till exempel två egenskaper under IntegrationRuntimes typegenskaper: computeProperties och ssisProperties. Båda egenskapstyperna skapas med respektive standardvärden och typer (objekt).

Utlösare

• Under typePropertiesparameteriseras två egenskaper. Den första är maxConcurrency, som anges för att ha ett standardvärde och är av typen string. Den har standardparameternamnet <entityName>_properties_typeProperties_maxConcurrency.
• Egenskapen recurrence är också parametriserad. Under den anges alla egenskaper på den nivån som parametriserade som strängar, med standardvärden och parameternamn. Ett undantag är egenskapen interval som parameteriseras som typ int. Parameternamnet är suffixet med <entityName>_properties_typeProperties_recurrence_triggerSuffix. På samma sätt är egenskapen freq en sträng och parametriseras som en sträng. Egenskapen parametriseras dock freq utan ett standardvärde. Namnet förkortas och suffixas. Exempel: <entityName>_freq

LinkedServices

• Länkade tjänster är unika. Eftersom länkade tjänster och datauppsättningar har en mängd olika typer kan du tillhandahålla typspecifik anpassning. I det här exemplet tillämpas en specifik mall för alla länkade tjänster av typen AzureDataLakeStore. För alla andra (via *) tillämpas en annan mall.
• Egenskapen connectionString parameteriseras som ett securestring värde. Det har inget standardvärde. Det har ett förkortat parameternamn som är suffix med connectionString.
• Egenskapen secretAccessKey råkar vara en AzureKeyVaultSecret (till exempel i en länkad Amazon S3-tjänst). Den parametriseras automatiskt som en Azure Key Vault-hemlighet och hämtas från det konfigurerade nyckelvalvet. Du kan också parametrisera själva nyckelvalvet.

Datauppsättningar

• Även om typspecifik anpassning är tillgänglig för datauppsättningar kan du ange konfiguration utan att uttryckligen ha en konfiguration på *-nivå. I föregående exempel parametriseras alla datauppsättningsegenskaper under typeProperties .

Kommentar

Om Azure-aviseringar och matriser har konfigurerats för en pipeline stöds de för närvarande inte som parametrar för ARM-distributioner. Om du vill tillämpa aviseringarna och matriserna på nytt i den nya miljön följer du Data Factory Monitoring, Alerts and Matrices (Data Factory Monitoring, Alerts and Matrices).

Standardparameteriseringsmall

Nedan visas den aktuella standardparameteriseringsmallen. Om du bara behöver lägga till några få parametrar kan det vara en bra idé att redigera mallen direkt eftersom du inte förlorar den befintliga parameteriseringsstrukturen.

{
    "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": {
            "*": "="
        }
    }
}

Exempel: Parameterisera ett befintligt interaktivt Azure Databricks-kluster-ID

I följande exempel visas hur du lägger till ett enda värde i standardparameteriseringsmallen. Vi vill bara lägga till ett befintligt interaktivt Azure Databricks-kluster-ID för en Databricks-länkad tjänst till parameterfilen. Observera att den här filen är samma som föregående fil förutom tillägg av existingClusterId under egenskapsfältet Microsoft.DataFactory/factories/linkedServicesi .

{
    "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": "="
                }
            }
        }}
}

Relaterat innehåll

• Översikt över kontinuerlig integrering och leverans
• Automatisera kontinuerlig integrering med Azure Pipelines-versioner
• Manuellt höja upp en Resource Manager-mall till varje miljö
• Länkade Resource Manager-mallar
• Använda en snabbkorrigeringsproduktionsmiljö
• Exempelskript före och efter distribution