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

成果物は、Azure DevTest Labs VM に追加できるツール、アクション、またはソフトウェアです。たとえば、成果物では、スクリプトの実行、ツールのインストール、ドメインへの参加などのアクションを実行できます。 DevTest Labs ユーザーは VM に成果物を追加できます。ラボ管理者は、すべてのラボ VM に追加する必須の成果物を指定できます。

この記事では、ラボ VM をプロビジョニングする成果物を作成する方法について説明します。成果物は、アーティファクト定義 JSON ファイルと、Git リポジトリフォルダーに格納されている他のスクリプトファイルで構成されます。アーティファクトは、プライベートまたはパブリックの Git リポジトリに格納できます。ラボ管理者は、すべてのラボユーザーがラボにアクセスできるように、ラボにアーティファクトリポジトリを追加できます。

[前提条件]

アーティファクト定義ファイルを作成して操作するには、JSON エディターが必要です。 Visual Studio Code は、Windows、Linux、macOS で使用できます。
アーティファクト定義とスクリプトファイルを格納するには、GitHub アカウントが必要です。

アーティファクト定義ファイルについて

アーティファクト定義ファイルは、VM に対して実行するアクションを指定する JSON 式で構成されます。このファイルは、成果物名、実行するコマンド、およびコマンドで使用できるパラメーターを定義します。成果物に他のスクリプトファイルが含まれている場合は、成果物定義ファイル内の名前でファイルを参照できます。

次の例は、 artifactfile.json 成果物定義ファイルの基本的な構造を示しています。

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "<title>",
    "description": "<description>",
    "iconUri": "",
    "targetOsType": "<os>",
    "parameters": {
      "<paramName>": {
        "type": "<type>",
        "displayName": "<display name>",
        "description": "<description>"
      }
    },
    "runCommand": {
      "commandToExecute": "<command>"
    }
  }

定義には、次の必須要素と省略可能な要素があります。

要素名	Description
`$schema`	定義ファイルの有効性をテストするのに役立つ JSON スキーマファイルの場所。
`title`	表示する必須のアーティファクト名。
`description`	必須の成果物の説明。
`iconUri`	表示するアーティファクトアイコン URI。
`targetOsType`	インストールに必要なオペレーティングシステム。サポートされている値は、`Windows` または `Linux`です。
`parameters`	インストール中に使用可能な成果物のカスタマイズ。
`runCommand`	VM に成果物をインストールするために必要なコマンド。

成果物のパラメーター

定義ファイルの parameters セクションでは、ユーザーが成果物をインストールするときに指定できるオプションと値を定義します。これらのパラメーターは、 runCommandで参照できます。

次の構造体は、パラメーターを定義します。

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

各パラメーターには名前が必要であり、パラメーター定義には次の要素が必要です。

要素名	Description
`type`	必須のパラメーター値の型。この型には、任意の有効な JSON `string`、整数 `int`、ブール `bool`、または `array`を指定できます。
`displayName`	ユーザーに表示するために必要なパラメーター名。
`description`	必須のパラメーターの説明。

セキュリティで保護された文字列パラメーター

アーティファクト定義にシークレットを含めるには、定義ファイルの secureStringParam セクションのparameters構文を使用して、シークレットをセキュリティで保護された文字列として宣言します。 description要素は、スペースを含む任意のテキスト文字列を許可し、UI 内の文字列をマスクされた文字として表示します。


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

次の runCommand では、 ConvertTo-SecureString コマンドを使用して作成されたセキュリティで保護された文字列を受け取る PowerShell スクリプトを使用します。このスクリプトはデバッグ用の出力をキャプチャするため、セキュリティのために出力をコンソールに記録しません。

  "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)として書式設定されます。

一般的な関数は次のとおりです。

機能	Description
`parameters(parameterName)`	アーティファクトコマンドの実行時に使用するパラメーター値を返します。
`concat(arg1, arg2, arg3, ...)`	複数の文字列値を結合し、さまざまな引数を受け取ることができます。

次の例では、 concat 関数で式を使用して値を構築します。

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

カスタム成果物を作成する

カスタム成果物は、サンプル のartifactfile.json 定義ファイルから開始して作成できます。パブリック DevTest Labs アーティファクトリポジトリには、成果物のライブラリがあります。成果物定義ファイルをダウンロードし、独自の成果物を作成するようにカスタマイズできます。

https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypesからartifactfile.json定義ファイルとartifact.ps1 PowerShellスクリプトをダウンロードします。
アーティファクト定義ファイルを編集して、要素と値にいくつかの有効な変更を加えます。 Visual Studio Code では、IntelliSense を使用して有効な要素と値のオプションを表示できます。たとえば、 targetOsType 要素を編集すると、IntelliSense に Windows または Linux オプションが表示されます。
パブリックまたはプライベートの Git アーティファクトリポジトリにアーティファクトを格納します。
- 各 artifactfile.json 成果物定義ファイルを、成果物名と同じ名前の個別のディレクトリに格納します。
- インストールコマンドが参照するスクリプトを成果物定義ファイルと同じディレクトリに格納します。
次のスクリーンショットは、アーティファクトフォルダーの例を示しています。

注

カスタム成果物をパブリック DevTest Labs アーティファクトリポジトリに追加するには、リポジトリに対するプル要求を開きます。

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-16