Używanie parametrów niestandardowych z szablonem Resource Manager

DOTYCZY: Azure Data Factory Azure Synapse Analytics

Wskazówka

Data Factory w usłudze Microsoft Fabric jest następną generacją Azure Data Factory z prostszą architekturą, wbudowaną sztuczną inteligencją i nowymi funkcjami. Jeśli dopiero zaczynasz integrować dane, zacznij od Fabric Data Factory. Istniejące obciążenia ADF można zaktualizować do Fabric, aby uzyskać dostęp do nowych możliwości w zakresie nauki o danych, analiz w czasie rzeczywistym oraz raportowania.

Jeśli wystąpienie programistyczne ma skojarzone repozytorium Git, możesz zastąpić domyślne parametry szablonu usługi Menedżer zasobów wygenerowanego przez opublikowanie lub wyeksportowanie szablonu. W następujących scenariuszach możesz chcieć zastąpić domyślną konfigurację parametrów Resource Manager:

  • Używasz automatycznego CI/CD i chcesz zmienić niektóre właściwości podczas wdrażania przy użyciu Resource Managera, ale właściwości nie są domyślnie sparametryzowane.

  • Twoja fabryka jest tak duża, że domyślny szablon Resource Manager jest nieprawidłowy, ponieważ ma więcej niż maksymalne dozwolone parametry (256).

    Aby obsłużyć limit parametru niestandardowego 256, dostępne są trzy opcje:

    • Użyj pliku parametrów niestandardowych i usuń właściwości, które nie wymagają parametryzacji, czyli właściwości, które mogą zachować wartość domyślną, a tym samym zmniejszyć liczbę parametrów.
    • Logika refaktoryzacji w przepływie danych w celu zmniejszenia parametrów, na przykład parametry potoku mają tę samą wartość. Zamiast tego można po prostu użyć parametrów globalnych.
    • Podziel jedną fabrykę danych na wiele fabryk danych.

Aby zastąpić domyślną konfigurację parametrów Resource Manager, przejdź do centrum Manage i wybierz szablon ARM w sekcji "Kontrola wersji". W sekcji konfiguracja parametrów ARM wybierz ikonę Edytuj w "Edytuj konfigurację parametrów", aby otworzyć edytor kodu konfiguracji parametrów Menadżera Zasobów.

Zarządzanie parametrami niestandardowymi

Uwaga

Konfiguracja parametrów ARM jest włączona tylko w trybie „GIT”. Obecnie jest on wyłączony w trybie "tryb na żywo" lub "Fabryka danych".

Utworzenie niestandardowej konfiguracji parametrów Resource Manager powoduje utworzenie pliku o nazwie arm-template-parameters-definition.json w folderze głównym gałęzi git. Musisz użyć tej dokładnej nazwy pliku.

Plik parametrów niestandardowych

Podczas publikowania z gałęzi współpracy usługa Data Factory odczytuje ten plik i użyje jego konfiguracji, aby wygenerować właściwości, które są sparametryzowane. Jeśli nie znaleziono pliku, zostanie użyty domyślny szablon.

Podczas eksportowania szablonu Resource Manager, usługa Data Factory odczytuje ten plik z gałęzi, nad którą aktualnie pracujesz, a nie z gałęzi collaborative. Możesz utworzyć lub edytować plik z prywatnej gałęzi, gdzie możesz przetestować zmiany, wybierając Eksportuj szablon ARM w interfejsie użytkownika. Następnie możesz scalić plik z gałęzią współpracy.

Uwaga

Niestandardowa konfiguracja parametrów Resource Manager nie zmienia limitu parametrów szablonu ARM wynoszącego 256. Umożliwia wybranie i zmniejszenie liczby sparametryzowanych właściwości.

Składnia parametrów niestandardowych

Poniżej przedstawiono kilka wskazówek, które należy wykonać podczas tworzenia pliku parametrów niestandardowych, arm-template-parameters-definition.json. Plik składa się z sekcji dla każdego typu jednostki: wyzwalacza, potoku, połączonej usługi, zestawu danych, środowiska Integration Runtime i przepływu danych.

  • Wprowadź ścieżkę właściwości dla odpowiedniego typu jednostki.
  • Ustawienie nazwy właściwości na * wskazuje, że chcesz sparametryzować wszystkie właściwości znajdujące się pod nią (tylko do pierwszego poziomu, bez uwzględniania rekurencji). Można również podać wyjątki dla tej konfiguracji.
  • Ustawienie wartości właściwości jako ciągu wskazuje, że chcesz sparametryzować właściwość. Użyj formatu <action>:<name>:<stype>.
    • <action> może być jednym z następujących znaków:
      • = oznacza zachowanie bieżącej wartości jako wartości domyślnej parametru.
      • - oznacza, że wartość domyślna parametru nie jest zachowywana.
      • | jest szczególnym przypadkiem tajemnic przechowywanych w Azure Key Vault, używanych do parametrów połączeń lub kluczy.
    • <name> to nazwa parametru. Jeśli jest ona pusta, przyjmuje nazwę właściwości. Jeśli wartość zaczyna się od - znaku, nazwa zostanie skrócona. Na przykład AzureStorage1_properties_typeProperties_connectionString zostanie skrócony do AzureStorage1_connectionString.
    • <stype> jest typem parametru. Jeśli <stype> wartość jest pusta, domyślnym typem jest string. Obsługiwane wartości: string, , securestring, intbool, objectsecureobject , i array.
  • Określenie tablicy w pliku definicji wskazuje, że zgodna właściwość w szablonie jest tablicą. Usługa Data Factory przechodzi przez wszystkie obiekty w tablicy, używając definicji określonej w obiekcie "integration runtime" dla tablicy. Drugi obiekt, ciąg, staje się nazwą właściwości, która jest używana jako nazwa parametru dla każdej iteracji.
  • Definicja nie może być specyficzna dla wystąpienia zasobu. Każda definicja ma zastosowanie do wszystkich zasobów tego typu.
  • Domyślnie wszystkie bezpieczne ciągi znakowe, takie jak tajemnice Key Vault, oraz bezpieczne ciągi znakowe, takie jak parametry połączenia, klucze i tokeny, są sparametryzowane.

Przykładowy szablon parametryzacji

Oto przykład konfiguracji parametrów Resource Manager. Zawiera przykłady wielu możliwych użyć, w tym parametryzację zagnieżdżonych działań w potoku oraz zmianę wartości domyślnej parametru połączonej usługi.

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

Poniżej przedstawiono wyjaśnienie sposobu konstruowania poprzedniego szablonu podzielonego według typu zasobu.

Pipelines

  • Każda właściwość w ścieżce activities/typeProperties/waitTimeInSeconds jest sparametryzowana. Każda aktywność w potoku, która posiada właściwość na poziomie kodu źródłowego o nazwie waitTimeInSeconds (na przykład aktywność Wait), jest sparametryzowana jako liczba z nazwą domyślną. Nie będzie jednak mieć wartości domyślnej w szablonie Resource Manager. Jest to obowiązkowe dane wejściowe podczas wdrażania Resource Manager.
  • Podobnie, właściwość o nazwie headers (na przykład w aktywności Web) jest sparametryzowana typem object (JObject). Ma wartość domyślną, która jest taka sama jak wartość fabryki źródłowej.

IntegrationRuntimes

  • Wszystkie właściwości w ścieżce typeProperties są sparametryzowane przy użyciu odpowiednich wartości domyślnych. Na przykład, istnieją dwie właściwości pod właściwościami typu IntegrationRuntimes: computeProperties i ssisProperties. Oba typy właściwości są tworzone z odpowiednimi wartościami domyślnymi i typami (Object).

Wyzwalacze

  • Pod typeProperties dwie właściwości są parametryzowane. Pierwszy z nich to maxConcurrency, który jest określony, aby mieć wartość domyślną i jest typu string. Ma domyślną nazwę parametru <entityName>_properties_typeProperties_maxConcurrency.
  • Właściwość recurrence jest również sparametryzowana. W nim wszystkie właściwości na tym poziomie są określane jako parametryzowane jako ciągi z wartościami domyślnymi i nazwami parametrów. Wyjątkiem jest interval właściwość, która jest sparametryzowana jako typ int. Nazwa parametru ma sufiks .<entityName>_properties_typeProperties_recurrence_triggerSuffix freq Podobnie właściwość jest ciągiem i jest sparametryzowana jako ciąg. freq Jednak właściwość jest sparametryzowana bez wartości domyślnej. Nazwa jest skrócona i ma dodany sufiks. Na przykład <entityName>_freq.

Połączoneusługi

  • Połączone usługi są unikatowe. Ponieważ połączone usługi i zestawy danych mają szeroką gamę typów, można zapewnić dostosowanie specyficzne dla typu. W tym przykładzie dla wszystkich połączonych usług typu AzureDataLakeStorejest stosowany określony szablon. W przypadku wszystkich innych (za pośrednictwem *) jest stosowany inny szablon.
  • Właściwość connectionString jest sparametryzowana jako wartość securestring. Nie będzie mieć wartości domyślnej. Ma skróconą nazwę parametru z sufiksem connectionString.
  • Właściwość secretAccessKey ma być właściwością AzureKeyVaultSecret (na przykład w połączonej usłudze Amazon S3). Jest ona automatycznie sparametryzowana jako wpis tajny Azure Key Vault i pobierana ze skonfigurowanego magazynu kluczy. Można również sparametryzować sam magazyn kluczy.

Warning

Właściwość encryptedCredential w definicjach połączonej usługi jest szyfrowana przy użyciu klucza szyfrowania fabryki źródłowej i nie jest przenoszona między fabrykami. Jeśli pliki JSON usługi połączonej kontrolowanej przez źródło zawierają encryptedCredential, wdrożenie w dowolnej innej fabryce zakończy się niepowodzeniem lub połączone usługi nie będą działać. Przed zatwierdzeniem definicji połączonej usługi do systemu kontroli wersji, całkowicie usuń właściwość encryptedCredential. Zamiast tego użyj jednej z następujących przenośnych alternatyw:

  • Referencja Azure Key Vault — przechowywanie tajemnicy w Key Vault i odwoływanie się do niej przy użyciu AzureKeyVaultSecret w definicji połączonej usługi.
  • Tożsamość zarządzana (MSI) — tam, gdzie usługa docelowa ją obsługuje, przełącz typ uwierzytelniania na ManagedServiceIdentity, aby całkowicie usunąć konieczność zarządzania poświadczeniami. Oba podejścia działają w różnych środowiskach bez modyfikacji i są zalecanymi wzorcami dla pipeline'ów CI/CD.

Zestawy danych

  • Mimo że dostępne jest dostosowywanie typowe dla zestawów danych, można określić konfigurację bez jawnej konfiguracji na poziomie danego typu. W poprzednim przykładzie wszystkie właściwości zestawu danych w obszarze typeProperties są sparametryzowane.

Uwaga

Jeśli Azure alerty i macierze są skonfigurowane dla potoku, nie są obecnie obsługiwane jako parametry wdrożeń szablonów ARM. Aby ponownie zastosować alerty i macierze w nowym środowisku, postępuj zgodnie z instrukcjami Monitorowanie, Alerty i Macierze usługi Data Factory.

Domyślny szablon parametryzacji

Poniżej znajduje się bieżący domyślny szablon parametryzacji. Jeśli musisz dodać tylko kilka parametrów, edytowanie tego szablonu bezpośrednio może być dobrym pomysłem, ponieważ nie utracisz istniejącej struktury parametryzacji.

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

Przykład: parametryzacja istniejącego identyfikatora klastra interaktywnego Azure Databricks

W poniższym przykładzie pokazano, jak dodać pojedynczą wartość do domyślnego szablonu parametryzacji. Chcemy dodać istniejący identyfikator klastra interaktywnego Azure Databricks do pliku parametrów dla powiązanej usługi Databricks. Ten plik jest taki sam jak poprzedni plik z wyjątkiem dodawania existingClusterId w polu właściwości 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": "="
                }
            }
        }}
}

Powiązana zawartość

  • Last updated on