DevTest Labs のカスタム成果物を作成する
この記事では、Azure DevTest Labs 仮想マシン (VM) のカスタム成果物を作成する方法について説明します。 DevTest Labs 成果物を使用して、VM をプロビジョニングするために実行するアクションを指定します。 成果物は、Git リポジトリ内のフォルダーに保存されている成果物定義ファイルとその他のスクリプト ファイルで構成されます。
- 成果物リポジトリをラボに追加する方法については、「ラボへの成果物リポジトリの追加」を参照してください。
- 作成した成果物を VM に追加する方法の詳細については、「DevTest Labs の VM に成果物を追加する」を参照してください。
- すべてのラボ VM に追加する必須成果物を指定する方法については、「Azure DevTest Labs VM の必須の成果物を指定する」を参照してください。
成果物定義ファイル
成果物定義ファイルは、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 でラボにアーティファクト リポジトリを追加するに関するページを参照してください。