Membuat artefak kustom untuk VM DevTest Labs

Artefak adalah alat, tindakan, atau perangkat lunak yang dapat Anda tambahkan ke VM Azure DevTest Labs. Misalnya, artefak dapat menjalankan skrip, menginstal alat, atau mengambil tindakan seperti bergabung dengan domain. Pengguna DevTest Labs dapat menambahkan artefak ke VM mereka, dan administrator lab dapat menentukan artefak wajib yang akan ditambahkan ke semua VM lab.

Artikel ini menjelaskan cara membuat artefak yang memfasilitasi penyediaan VM lab. Artefak terdiri dari file JSON definisi artefak dan file skrip lainnya yang disimpan dalam folder repositori Git. Anda dapat menyimpan artefak di repositori Git privat atau publik. Administrator lab dapat menambahkan repositori artefak ke lab sehingga semua pengguna lab dapat mengaksesnya.

Prasyarat

Untuk membuat dan bekerja dengan file definisi artefak, Anda memerlukan editor JSON. Visual Studio Code tersedia untuk Windows, Linux, dan macOS.
Untuk menyimpan definisi artefak dan file skrip, Anda memerlukan akun GitHub.

Memahami file definisi artefak

File definisi artefak terdiri dari ekspresi JSON yang menentukan tindakan yang akan diambil pada VM. File menentukan nama artefak, perintah untuk dijalankan, dan parameter yang tersedia untuk perintah . Jika artefak berisi file skrip lain, Anda dapat merujuk ke file berdasarkan nama dalam file definisi artefak.

Contoh berikut menunjukkan struktur dasar file definisi artefak 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>"
    }
  }

Definisi memiliki elemen yang diperlukan dan opsional berikut:

Nama elemen	Description
`$schema`	Lokasi file skema JSON, yang dapat membantu Anda menguji validitas file definisi.
`title`	Nama artefak yang diperlukan untuk ditampilkan.
`description`	Deskripsi artefak yang diperlukan.
`iconUri`	URI ikon artefak untuk ditampilkan.
`targetOsType`	Sistem operasi yang diperlukan untuk diinstal. Nilai yang didukung `Windows` atau `Linux`.
`parameters`	Kustomisasi artefak yang tersedia selama penginstalan.
`runCommand`	Perintah yang diperlukan untuk menginstal artefak pada VM.

Parameter artefak

Bagian parameters file definisi menentukan opsi dan nilai yang dapat ditentukan pengguna saat mereka menginstal artefak. Anda dapat merujuk ke parameter ini di runCommand.

Struktur berikut mendefinisikan parameter:

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

Setiap parameter memerlukan nama, dan definisi parameter memerlukan elemen berikut:

Nama elemen	Description
`type`	Jenis nilai parameter yang diperlukan. Jenisnya dapat berupa JSON `string`, bilangan bulat `int`, boolean `bool`, atau `array`.
`displayName`	Nama parameter yang diperlukan untuk ditampilkan kepada pengguna.
`description`	Deskripsi parameter yang diperlukan .

Parameter string yang aman

Untuk menyertakan rahasia dalam definisi artefak, nyatakan rahasia sebagai string aman dengan menggunakan secureStringParam sintaks di bagian parameters file definisi. Elemen ini description memungkinkan string teks apa pun, termasuk spasi, dan menyajikan string di UI sebagai karakter bertopeng.


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

Berikut ini runCommand menggunakan skrip PowerShell yang mengambil string aman yang dibuat dengan menggunakan perintah ConvertTo-SecureString. Skrip menangkap output untuk debugging, jadi untuk keamanan pastikan tidak mencatat output ke konsol.

  "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'), '\"')]"
  }

Ekspresi dan fungsi artefak

Anda dapat menggunakan ekspresi dan fungsi untuk membuat perintah penginstalan artefak. Ekspresi dievaluasi ketika artefak dipasang.

Ekspresi dapat muncul di mana saja dalam nilai string JSON, dan selalu mengembalikan nilai JSON lainnya. Sertakan ekspresi dengan tanda kurung, [ ]. Jika Anda perlu menggunakan string harfiah yang dimulai dengan tanda kurung, gunakan dua tanda kurung [[.

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

Fungsi umum meliputi:

Function	Description
`parameters(parameterName)`	Mengembalikan nilai parameter yang akan digunakan saat perintah artefak berjalan.
`concat(arg1, arg2, arg3, ...)`	Menggabungkan beberapa nilai string dan dapat mengambil berbagai argumen.

Contoh berikut menggunakan ekspresi dengan concat fungsi untuk membuat nilai.

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