Tworzenie niestandardowych artefaktów dla swojej maszyny wirtualnej w usłudze DevTest LabsCreate custom artifacts for your DevTest Labs virtual machine

Obejrzyj poniższy klip wideo z omówieniem kroków opisanych w tym artykule:Watch the following video for an overview of the steps described in this article:

PrzeglądOverview

Możesz użyć artefaktów wdrażanie i konfigurowanie aplikacji po zainicjowaniu obsługi administracyjnej maszyny Wirtualnej.You can use artifacts to deploy and set up your application after you provision a VM. Artefakt składa się z plikiem definicji artefaktów i inne pliki skryptów, które są przechowywane w folderze w repozytorium Git.An artifact consists of an artifact definition file and other script files that are stored in a folder in a Git repository. Pliki definicji artefaktu składają się z kodu JSON i wyrażeń, które służą do określania, co chcesz zainstalować na maszynie Wirtualnej.Artifact definition files consist of JSON and expressions that you can use to specify what you want to install on a VM. Na przykład można zdefiniować nazwę artefakt, polecenie do uruchomienia i parametry, które są dostępne, gdy polecenie jest wykonywane.For example, you can define the name of an artifact, a command to run, and parameters that are available when the command is run. Mogą odwoływać się do innych plików skryptu w pliku definicji artefaktu według nazwy.You can refer to other script files within the artifact definition file by name.

Format pliku definicji artefaktuArtifact definition file format

Poniższy przykład przedstawia sekcje, które tworzą podstawowa struktura pliku definicji:The following example shows the sections that make up the basic structure of a definition file:

{
  "$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": ""
  }
}
Nazwa elementuElement name Wymagana?Required? OpisDescription
$schema$schema NieNo Lokalizacja pliku schematu JSON.Location of the JSON schema file. Plik schematu JSON może pomóc można sprawdzić poprawność pliku definicji.The JSON schema file can help you test the validity of the definition file.
titletitle TakYes Nazwa artefaktu wyświetlane w środowisku laboratoryjnym.Name of the artifact displayed in the lab.
descriptiondescription TakYes Opis artefaktu wyświetlane w środowisku laboratoryjnym.Description of the artifact displayed in the lab.
iconUriiconUri NieNo Identyfikator URI ikona wyświetlana w środowisku laboratoryjnym.URI of the icon displayed in the lab.
targetOsTypetargetOsType TakYes System operacyjny maszyny wirtualnej, w którym zainstalowano artefaktu.Operating system of the VM where the artifact is installed. Obsługiwane opcje to Windows i Linux.Supported options are Windows and Linux.
parametersparameters NieNo Wartości, które znajdują się po uruchomieniu polecenia install artefaktów na maszynie.Values that are provided when the artifact install command is run on a machine. Dzięki temu można dostosować swoje artefaktu.This helps you customize your artifact.
runCommandrunCommand YesYes Artefakt zainstalować polecenia, który jest wykonywany na maszynie Wirtualnej.Artifact install command that is executed on a VM.

Parametry artefaktuArtifact parameters

W sekcji parametrów w pliku definicji należy określić wartości, które użytkownik może wprowadzić podczas instalacjo artefaktu.In the parameters section of the definition file, specify which values a user can input when they install an artifact. Mogą odwoływać się do tych wartości w poleceniu instalacji artefaktu.You can refer to these values in the artifact install command.

Aby zdefiniować parametry, należy użyć następującej strukturze:To define parameters, use the following structure:

"parameters": {
  "<parameterName>": {
    "type": "<type-of-parameter-value>",
    "displayName": "<display-name-of-parameter>",
    "description": "<description-of-parameter>"
  }
}
Nazwa elementuElement name Wymagana?Required? OpisDescription
typetype TakYes Typ wartości parametru.Type of parameter value. Przejrzyj następującą listę dozwolonych typów.See the following list for the allowed types.
displayNamedisplayName TakYes Nazwa parametru, który jest wyświetlany użytkownikowi w środowisku laboratoryjnym.Name of the parameter that is displayed to a user in the lab.
descriptiondescription TakYes Opis parametru, który jest wyświetlany w środowisku laboratoryjnym.Description of the parameter that is displayed in the lab.

Dozwolone typy to:Allowed types are:

  • string (dowolny prawidłowy ciąg JSON)string (any valid JSON string)
  • int (Dowolna prawidłowa JSON liczba całkowita)int (any valid JSON integer)
  • bool (wszystkie prawidłowe logiczna JSON)bool (any valid JSON Boolean)
  • array (wszystkie prawidłową tablicą JSON)array (any valid JSON array)

Wpisy tajne jako bezpieczny ciągSecrets as secure strings

Zadeklaruj wpisów tajnych jako bezpieczny ciąg.Declare secrets as secure strings. Oto Składnia deklaracji parametru bezpieczny ciąg, w ramach parameters części artifactfile.json pliku:Here is the syntax for declaring a secure string parameter within the parameters section of the artifactfile.json file:


    "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
    },

Polecenie instalacji artefaktu, uruchom skrypt programu PowerShell, który przyjmuje bezpieczny ciąg utworzony za pomocą polecenia ConvertTo-SecureString.For the artifact install command, run the PowerShell script that takes the secure string created by using the ConvertTo-SecureString command.

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

Artifactfile.json kompletny przykład i artifact.ps1 (skrypt programu PowerShell) można znaleźć tego przykładu w usłudze GitHub.For the complete example artifactfile.json and the artifact.ps1 (PowerShell script), see this sample on GitHub.

Jest innym ważnym punktem należy pamiętać, aby nie rejestrować wpisy tajne w konsoli jako dane wyjściowe są przechwytywane do debugowania użytkownika.Another important point to note is not to log secrets to the console as output is captured for user debugging.

Artefakt wyrażeń i funkcjiArtifact expressions and functions

Można używać wyrażeń i funkcji do konstruowania artefaktu zainstalować polecenia.You can use expressions and functions to construct the artifact install command. Wyrażenia są ujęte w nawiasach kwadratowych ([i]), które są oceniane, po zainstalowaniu artefaktu.Expressions are enclosed with brackets ([ and ]), and are evaluated when the artifact is installed. Wyrażenia może występować w dowolnym miejscu w wartości ciągu JSON.Expressions can appear anywhere in a JSON string value. Wyrażenia zawsze zwraca inną wartość JSON.Expressions always return another JSON value. Aby użyć literału ciągu, rozpoczynająca się od nawiasu ([), należy użyć dwóch nawiasy kwadratowe ([[).If you need to use a literal string that starts with a bracket ([), you must use two brackets ([[). Zazwyczaj należy użyć wyrażeń z usługą functions do utworzenia wartości.Typically, you use expressions with functions to construct a value. Tak samo, jak w języku JavaScript, wywołania funkcji są sformatowane jako functionName (arg1 arg2, arg3) .Just like in JavaScript, function calls are formatted as functionName(arg1, arg2, arg3).

Na poniższej liście przedstawiono typowe funkcje:The following list shows common functions:

  • parameters(parameterName) : Zwraca wartość parametru, który znajduje się po uruchomieniu polecenia artefaktu.parameters(parameterName): Returns a parameter value that is provided when the artifact command is run.
  • concat (arg1, arg2 arg3...) : To połączenie wielu wartości ciągów.concat(arg1, arg2, arg3,….. ): Combines multiple string values. Ta funkcja może przybierać różne argumentów.This function can take a variety of arguments.

Poniższy przykład pokazuje, jak używać wyrażeń i funkcji do tworzenia wartości:The following example shows how to use expressions and functions to construct a value:

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

Tworzenie niestandardowego artefaktuCreate a custom artifact

  1. Instalowanie edytora JSON.Install a JSON editor. Potrzebujesz edytora JSON do pracy z plikami definicji artefaktu.You need a JSON editor to work with artifact definition files. Firma Microsoft zaleca używanie programu Visual Studio Code, który jest dostępny dla Windows, Linux i OS X.We recommend using Visual Studio Code, which is available for Windows, Linux, and OS X.

  2. Pobierz przykładowy plik definicji artifactfile.json.Get a sample artifactfile.json definition file. Zapoznaj się z artefaktów utworzonych przez zespół usługi DevTest Labs w naszym repozytorium GitHub.Check out the artifacts created by the DevTest Labs team in our GitHub repository. Utworzyliśmy Bogata biblioteka artefaktów, które mogą pomóc Ci tworzenie własnych artefaktów.We have created a rich library of artifacts that can help you create your own artifacts. Pobierz plik definicji artefaktu i zmodyfikować go do tworzenia własnych artefaktów.Download an artifact definition file and make changes to it to create your own artifacts.

  3. Korzystaj z funkcji IntelliSense.Make use of IntelliSense. Użyj funkcji IntelliSense, aby wyświetlić prawidłowe elementy, które można używać do tworzenia pliku definicji artefaktu.Use IntelliSense to see valid elements that you can use to construct an artifact definition file. Widać też różne opcje dla wartości elementu.You also can see the different options for values of an element. Na przykład podczas edytowania targetOsType elementu, IntelliSense pokazuje dwie opcje dla Windows lub Linux.For example, when you edit the targetOsType element, IntelliSense shows you two choices, for Windows or Linux.

  4. Store artefaktu w publicznego repozytorium Git na potrzeby usługi DevTest Labs lub repozytorium Git.Store the artifact in the public Git repository for DevTest Labs or your own Git repository. W publicznym repozytorium można wyświetlić artefaktów udostępnione przez innych użytkowników można używać bezpośrednio lub dostosować je do swoich potrzeb.In the public repository, you can view artifacts shared by others that you can use directly or customize them to suit your needs.

    1. Należy utworzyć oddzielny katalog dla każdego artefaktu.Create a separate directory for each artifact. Nazwa katalogu powinna być taka sama jak nazwa artefaktu.The directory name should be the same as the artifact name.

    2. Store plik definicji artefaktu (artifactfile.json) w katalogu, który został utworzony.Store the artifact definition file (artifactfile.json) in the directory that you created.

    3. Store skrypty, które są wywoływane z polecenia install artefaktu.Store the scripts that are referenced from the artifact install command.

      Poniżej przedstawiono przykładowy wygląd folderu artefaktów:Here is an example of how an artifact folder might look:

      Przykładowy folder artefaktu

  5. Jeśli używasz własnego repozytorium do przechowywania artefaktów, Dodaj repozytorium do laboratorium, wykonując instrukcje przedstawione w artykule: Dodawanie repozytorium Git dla artefaktów i szablonów.If you are using your own repository to store artifacts, add the repository to the lab by following instructions in the article: Add a Git repository for artifacts and templates.

Kolejne krokiNext steps