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

Создание пользовательских артефактов для виртуальной машины DevTest Labs

  • Статья

В этой статье описывается создание пользовательских файлов артефактов для виртуальных машин Azure DevTest Labs. Артефакты DevTest Labs указывают действия, которые необходимо выполнить для инициализации виртуальной машины. Артефакт состоит из файла определения артефакта и других файлов скриптов, которые хранятся в папке в репозитории Git.

Файлы определения артефактов

Файлы определения артефактов состоят из выражений JSON, позволяющих указать, какие компоненты должны быть установлены на виртуальной машине. Файлы определяют имя артефакта, выполняемую команду и доступные параметры для команды. В файле определения артефакта можно ссылаться на другие файлы скриптов по имени.

В следующем примере показаны разделы, составляющие базовую структуру файла определения артефакта artifactfile.json:

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "",
    "description": "",
    "iconUri": "",
    "targetOsType": "",
    "parameters": {
      "<parameterName>": {
        "type": "",
        "displayName": "",
        "description": ""
      }
    },
    "runCommand": {
      "commandToExecute": ""
    }
  }
Имя элемента Описание
$schema Расположение файла схемы JSON, позволяющего проверять подлинность файла определения.
title Имя артефакта, которое нужно отобразить в лаборатории. Обязательный.
description Описание артефакта, которое нужно отобразить в лаборатории. Обязательный.
iconUri Универсальный код ресурса (URI) значка артефакта, отображаемого в лаборатории.
targetOsType Операционная система виртуальной машины, на которой необходимо установить артефакт. Поддерживаемые значения: Windows, Linux. Обязательный.
parameters Значения для настройки артефакта при установке на виртуальной машине.
runCommand Команда установки артефакта для выполнения на виртуальной машине. Обязательный.

Параметры артефакта

В разделе параметров файла определения укажите значения, которые пользователь может вводить при установке артефакта. Это значения можно использовать в команде установки артефакта.

Параметры определяются с помощью следующей структуры.

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Имя элемента Описание
type Тип значения параметра. Обязательный.
displayName Название параметра, отображаемого для пользователя лаборатории. Обязательный.
description Описание параметра, отображаемого для пользователя лаборатории. Обязательный.

Допустимые типы значений параметров:

Тип Описание
string Любая допустимая строка JSON
int Любое допустимое целое число JSON
bool Любое допустимое логическое значение JSON
array Любой допустимый массив JSON

Секреты в качестве защищенных строк

Чтобы объявить секреты как защищенные строковые параметры с маскированными символами в пользовательском интерфейсе, используйте этот синтаксис в разделе parameters файла artifactfile.json:


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

команда установки артефакта для выполнения скрипта PowerShell, который принимает защищенную строку, созданную с помощью команды ConvertTo-SecureString.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

Не записывайте секреты в консоль, так как скрипт фиксирует выходные данные для отладки пользователей.

Выражения и функции артефактов

Для ограничения команды установки артефактов можно использовать выражения и функции. Выражения оцениваются при установке артефакта. Выражения могут встречаться в любом месте строкового значения JSON и всегда возвращают другое значение JSON. Заключите выражения в квадратные скобки []. Если нужно использовать строковый литерал, который начинается с квадратной скобки, необходимо указать две квадратные скобки: [[.

Как правило, для составления значения используются выражения с функциями. Вызовы функций форматируются как functionName(arg1, arg2, arg3).

К общим функциям относятся:

Функция Описание
parameters(parameterName) Возвращает значение параметра, которое необходимо указать при выполнении команды артефакта.
concat(arg1, arg2, arg3, ...) объединяет несколько строковых значений. Эта функция может принимать различные аргументы.

В примере ниже для создания значения используются выражения и функции:

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

Создание пользовательского артефакта

Для создания пользовательского артефакта:

  • Установите редактор JSON для работы с файлами определения артефакта. Visual Studio Code доступен для Windows, Linux и macOS.

  • Начните с примера файла определения artifactfile.json.

    Общедоступный репозиторий артефактов DevTest Labs содержит обширную библиотеку артефактов, которые можно использовать. Вы можете скачать файл определения артефакта и настроить его для создания собственных артефактов.

    В этой статье используется файл определения artifactfile.json и сценарий artifact.ps1 PowerShell в https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Используйте технологию IntelliSense для просмотра допустимых элементов и вариантов значений, которые можно применять для создания файла определения артефакта. Например, при редактировании элемента targetOsType IntelliSense предлагает два варианта: Windows или Linux.

  • Сохраняйте артефакты в общедоступных или частных репозиториях артефактов Git.

    • Сохраните каждый файл определения артефакта artifactfile.json в отдельном каталоге, имя которого совпадает с именем артефакта.
    • Сохраните скрипты, на которые команда установки ссылается в том же каталоге, что и файл определения артефакта.

    На следующем снимке экрана показан пример папки артефактов:

    Снимок экрана: пример папки артефактов.

  • Чтобы сохранить пользовательские артефакты в общедоступном репозитории артефактов DevTest Labs, откройте запрос на вытягивание для репозитория.

  • Сведения о добавлении частного репозитория артефактов в лабораторию см. в статье Добавление репозитория артефактов в лабораторию в DevTest Labs.

Дальнейшие действия