Использование пользовательских параметров с шаблоном Resource Manager

Статья
09/26/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: Фабрика данных Azure Azure Synapse Analytics

Совет

Попробуйте использовать фабрику данных в Microsoft Fabric, решение для аналитики с одним интерфейсом для предприятий. Microsoft Fabric охватывает все, от перемещения данных до обработки и анализа данных в режиме реального времени, бизнес-аналитики и отчетности. Узнайте, как бесплатно запустить новую пробную версию !

Если у вашего экземпляра для разработки есть связанный репозиторий Git, можно переопределить параметры шаблона Resource Manager по умолчанию, созданного путем публикации или экспорта шаблона. Возможно, вы захотите обойти параметр конфигурации по умолчанию Resource Manager в этих сценариях:

Вы используете автоматизацию CI/CD и хотите изменить некоторые свойства во время развертывания Resource Manager, но свойства не будут параметризованы по умолчанию.
Ваша фабрика настолько велика, что шаблон Resource Manager по умолчанию является недопустимым, так как он превышает максимально допустимое количество параметров (256).

Три варианта для управления лимитом для пользовательского параметра 256:
- Используйте файл с пользовательским параметром и удалите свойства, которые не требуют параметризации, т. е. свойства сохраняют значения по умолчанию и таким образом количество параметров уменьшается.
- Выполните перепроектирование кода логики в потоке данных для сокращения количества параметров, например, параметры конвейера все имеют одинаковое значение, поэтому вместо них можно использовать глобальные параметры.
- Разделите одну фабрику данных на несколько фабрик данных.

Для того, чтобы обойти параметры по умолчанию конфигурации Resource Manager, перейдите в раздел Управление и выберите шаблон ARM в разделе "Управление ресурсами". В разделе настройка параметров конфигурации ARM щелкните по значку Изменить в разделе "Изменение параметра конфигурации", чтобы открыть редактор кодов параметра конфигурации Resource Manager.

Управление пользовательскими параметрами

Примечание.

Параметр конфигурации ARM включен только в "Режиме GIT". Сейчас она является недоступной в "рабочем режиме" или режиме "Фабрика данных".

При создании пользовательского параметра конфигурации Resource Manager создается файл с именем arm-template-parameters-definition.json в корневой папке вашей ветви git. Необходимо использовать точное имя файла.

Файл пользовательских параметров

При публикации из ветви совместной работы Фабрика данных считывает этот файл и использует его конфигурацию, чтобы определить свойства, которые будут параметризованы. Если файл не найден, используется шаблон по умолчанию.

При экспорте шаблона Resource Manager Фабрика данных считывает этот файл из ветви, в которой вы в данный момент работаете, а не из ветви совместной работы. Вы можете создать или изменить файл из частной ветви, где можно протестировать изменения, выбрав Export ARM Template (Экспорт шаблона 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.
При указании массива в файле определения вы можете указать, что соответствующее свойство в шаблоне является массивом. Фабрика данных выполняет итерацию всех объектов в массиве с помощью определения, указанного в объекте среды выполнения интеграции массива. Второй объект, строка, становится именем свойства, которое используется в качестве имени параметра для каждой итерации.
Определение не может быть указано для экземпляра ресурса. Любое определение применяется ко всем ресурсам этого типа.
По умолчанию все защищенные строки, такие как секреты 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. Для повторного применения оповещений и матриц в новой среде руководствуйтесь статьей Мониторинг, оповещения и матрицы Фабрики данных.

Шаблон параметризации по умолчанию

Ниже приведен текущий шаблон параметризации по умолчанию. Если необходимо добавить только несколько параметров, то рекомендуется изменить этот шаблон напрямую, так как вы не потеряете существующую структуру параметризации.

{
    "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

В следующем примере показано, как добавить одно значение в шаблон параметризации по умолчанию. Нужно только добавить существующий идентификатор интерактивного кластера Azure Databricks для связанной службы Databricks в файле параметров. Обратите внимание, что этот файл совпадает с предыдущим файлом, за исключением добавления existingClusterId в поле свойства 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": "="
                }
            }
        }}
}

Поделиться через

Использование пользовательских параметров с шаблоном Resource Manager

Синтаксис пользовательских параметров

Пример шаблона параметризации

Pipelines

IntegrationRuntimes

Триггеры

LinkedServices

Наборы данных

Шаблон параметризации по умолчанию

Пример. Параметризация существующего идентификатора интерактивного кластера Azure Databricks

Обратная связь

Дополнительные ресурсы

Поделиться через

Использование пользовательских параметров с шаблоном Resource Manager

Синтаксис пользовательских параметров

Пример шаблона параметризации

Pipelines

IntegrationRuntimes

Триггеры

LinkedServices

Наборы данных

Шаблон параметризации по умолчанию

Пример. Параметризация существующего идентификатора интерактивного кластера Azure Databricks

Связанный контент

Обратная связь

Дополнительные ресурсы