DevTest Labs のカスタム成果物を作成する

  • [アーティクル]

この記事では、Azure DevTest Labs 仮想マシン (VM) のカスタム成果物を作成する方法について説明します。 DevTest Labs 成果物を使用して、VM をプロビジョニングするために実行するアクションを指定します。 成果物は、Git リポジトリ内のフォルダーに保存されている成果物定義ファイルとその他のスクリプト ファイルで構成されます。

成果物定義ファイル

成果物定義ファイルは、VM にインストールするものを指定する 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 スキーマ ファイルの場所。 JSON スキーマ ファイルは、定義ファイルの有効性をテストする際に役立ちます。
title ラボに表示する成果物の名前。 必須。
description ラボに表示する成果物の説明。 必須。
iconUri ラボに表示する成果物アイコンの URI。
targetOsType 成果物をインストールする VM のオペレーティング システム。 サポートされる値: Windows、Linux。 必須。
parameters VM にインストールするときに成果物をカスタマイズする値。
runCommand VM で実行する成果物インストール コマンド。 必須。

アーティファクトのパラメーター

定義ファイルの parameters セクションでは、成果物のインストール時にユーザーが入力できる値を指定します。 アーティファクトのインストール コマンドでこれらの値を参照できます。

パラメーターを定義するには、次の構造を使用します。

  "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 配列

セキュリティで保護された文字列としてのシークレット

UI でマスクされた文字を使用してシークレットをセキュリティで保護された文字列パラメーターとして宣言するには、artifactfile.json ファイルの parameters セクションで次の構文を使用します。


    "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 値を返します。 式は、角かっこ [ ] で囲みます。 角かっこで始まるリテラル文字列を使用する必要がある場合は、2 つの角かっこ [[ を使用します。

通常は、関数と共に式を使用して値を構成します。 関数呼び出しは、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 成果物リポジトリには、使用できる成果物の豊富なライブラリがあります。 成果物定義ファイルをダウンロードしてカスタマイズし、独自の成果物を作成できます。

    この記事では、https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes にある artifactfile.json 定義ファイルと artifact.ps1 PowerShell スクリプトを使用します。

  • IntelliSense を使用して、アーティファクト定義ファイルの作成に使用できる有効な要素と値のオプションを確認します。 たとえば、targetOsType 要素を編集する場合、IntelliSense によって Windows または Linux のオプションが表示されます。

  • パブリックまたはプライベートの Git 成果物リポジトリに成果物を保存します。

    • 各 artifactfile.json 成果物定義ファイルを、成果物名と同じ同じ名前の別のディレクトリに保存します。
    • インストール コマンドが参照するスクリプトを、成果物定義ファイルと同じディレクトリに保存します。

    次のスクリーンショットは、成果物フォルダーの例を示しています。

    成果物フォルダーの例を示すスクリーンショット。

  • カスタム成果物をパブリック DevTest Labs 成果物リポジトリに保存するには、リポジトリに対して pull request を開きます。

  • プライベート成果物リポジトリをラボに追加するには、DevTest Labs でラボにアーティファクト リポジトリを追加するに関するページを参照してください。

次の手順