Buat artefak kustom untuk DevTest Labs

Artikel
09/30/2023

Artikel ini menjelaskan cara membuat file artefak khusus untuk mesin virtual (VM) Azure DevTest Labs. Artefak DevTest Labs menentukan tindakan yang harus diambil untuk menyediakan VM. Artefak terdiri dari file definisi artefak dan file skrip lainnya yang disimpan dalam folder di repositori Git.

Untuk informasi tentang menambahkan repositori artefak Anda ke lab, lihat Menambahkan repositori artefak ke lab Anda.
Untuk informasi tentang menambahkan artefak ke VM, lihat Menambahkan artefak ke VM DevTest Labs.
Untuk informasi tentang menentukan artefak wajib yang akan ditambahkan ke semua VM lab, lihat Menentukan artefak wajib untuk VM DevTest Labs.

File definisi artefak

File definisi artefak terdiri dari ekspresi JSON yang menentukan apa yang ingin Anda instal pada VM. File ini menentukan nama artefak, perintah untuk dijalankan, dan parameter yang tersedia untuk perintah. Anda dapat merujuk ke file skrip lain dalam file definisi artefak berdasarkan nama.

Contoh berikut menunjukkan bagian yang membentuk struktur dasar file definisi artifak 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": ""
    }
  }

Nama elemen	Deskripsi
`$schema`	Lokasi file skema JSON. File skema JSON dapat membantu Anda menguji validitas file definisi.
`title`	Nama artefak yang ditampilkan di laboratorium. Diperlukan.
`description`	Nama artefak yang ditampilkan di laboratorium. Diperlukan.
`iconUri`	URI ikon artefak yang ditampilkan di laboratorium.
`targetOsType`	Sistem operasi VM tempat menginstal artefak. Nilai yang didukung: `Windows`, `Linux`. Diperlukan.
`parameters`	Nilai untuk menyesuaikan artefak saat menginstal pada VM.
`runCommand`	Perintah instalasi artefak untuk dijalankan pada VM. Diperlukan.

Parameter artefak

Di bagian parameter file definisi, tentukan nilai yang dapat dimasukkan pengguna ketika mereka memasang artefak. Anda dapat merujuk ke nilai-nilai ini dalam perintah pemasangan artefak.

Untuk menentukan parameter, gunakan struktur berikut:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

Nama elemen	Deskripsi
`type`	Jenis nilai parameter. Diperlukan.
`displayName`	Nama parameter yang akan ditampilkan ke pengguna lab. Diperlukan.
`description`	Deskripsi parameter yang akan ditampilkan ke pengguna lab. Diperlukan.

Tipe nilai parameter yang diizinkan adalah:

Jenis	Deskripsi
`string`	String JSON yang valid
`int`	Bilangan bulat JSON yang valid
`bool`	Boolean JSON yang valid
`array`	Array JSON yang valid

Rahasia sebagai string aman

Untuk menyatakan rahasia sebagai parameter string aman dengan karakter bertopeng di UI, gunakan sintaks berikut di bagian parameters file 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
    },

Perintah pemasangan artefak untuk menjalankan skrip PowerShell mengambil string aman yang dibuat menggunakan perintah 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'), '\"')]"
  }

Jangan mencatat rahasia ke konsol, karena skrip menangkap output untuk debugging pengguna.

Ekspresi dan fungsi artefak

Anda dapat menggunakan ekspresi dan fungsi untuk membuat perintah pemasangan artefak. Ekspresi mengevaluasi ketika artefak diinstal. Ekspresi dapat muncul di mana saja dalam nilai string JSON, dan selalu mengembalikan nilai JSON lain. Lampirkan ekspresi dengan tanda kurung, [ ]. Jika Anda perlu menggunakan string literal yang dimulai dengan tanda kurung, gunakan dua tanda kurung [[.

Biasanya, Anda menggunakan ekspresi dengan fungsi untuk membangun nilai. Panggilan fungsi diformat sebagai functionName(arg1, arg2, arg3).

Fungsi umum meliputi:

Fungsi	Deskripsi
`parameters(parameterName)`	Mengembalikan nilai parameter untuk diberikan saat perintah artefak berjalan.
`concat(arg1, arg2, arg3, ...)`	Menggabungkan beberapa nilai string. Fungsi ini dapat mengambil berbagai argumen.

Contoh berikut menunjukkan cara menggunakan ekspresi dan fungsi untuk membuat nilai:

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

Membuat artefak kustom

Membuat artefak kustom:

Instal editor JSON untuk bekerja dengan file definisi artefak. Visual Studio Code tersedia untuk Windows, Linux, dan macOS.
Mulai dengan file definisi artifactfile.json sampel.

Repositori artefak DevTest Labs publik memiliki pustaka artefak yang kaya yang dapat Anda gunakan. Anda dapat mengunduh file definisi artefak dan mengkustomnya untuk membuat artefak Anda sendiri.

Artikel ini menggunakan file definisi artifactfile.json dan skrip PowerShell artifact.ps1 pada https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Gunakan IntelliSense untuk melihat elemen dan opsi nilai yang valid yang dapat Anda gunakan untuk membuat file definisi artefak. Misalnya, saat Anda mengedit elemen targetOsType, IntelliSense menunjukkan pilihan Windows da Linux.
Simpan artefak Anda di repositori artefak Git publik atau privat.
- Simpan setiap file definisi artefak artifactfile.json dalam direktori terpisah yang diberi nama sama dengan nama artefak.
- Simpan skrip yang direferensikan perintah penginstalan di direktori yang sama dengan file definisi artefak.
Tangkapan layar berikut menunjukkan folder contoh artefak:
Untuk menyimpan artefak kustom Anda di repositori artefak DevTest Labs publik, buka permintaan tarik terhadap repositori tersebut.
Untuk menambahkan repositori artefak pribadi Anda ke lab, lihat Menambahkan repositori artefak ke lab Anda di DevTest Labs.