Tworzenie niestandardowych artefaktów dla maszyn wirtualnych usługi DevTest Labs

Artefakty to narzędzia, akcje lub oprogramowanie, które można dodać do maszyn wirtualnych usługi Azure DevTest Labs. Na przykład artefakty mogą uruchamiać skrypty, instalować narzędzia lub podejmować akcje, takie jak dołączanie do domeny. Użytkownicy usługi DevTest Labs mogą dodawać artefakty do swoich maszyn wirtualnych, a administratorzy laboratorium mogą określić obowiązkowe artefakty, które mają zostać dodane do wszystkich maszyn wirtualnych laboratorium.

W tym artykule opisano sposób tworzenia artefaktów do aprowizacji maszyn wirtualnych w laboratorium. Artefakt składa się z pliku JSON definicji artefaktu i innych plików skryptów przechowywanych w folderze repozytorium Git. Artefakty można przechowywać w prywatnym lub publicznym repozytorium Git. Administratorzy laboratoriów mogą dodawać repozytoria artefaktów do laboratoriów , aby wszyscy użytkownicy laboratorium mogli uzyskiwać do nich dostęp.

Wymagania wstępne

Aby utworzyć pliki definicji artefaktu i pracować z plikami definicji artefaktu, potrzebny jest edytor JSON. Program Visual Studio Code jest dostępny dla systemów Windows, Linux i macOS.
Do przechowywania definicji artefaktu i plików skryptów potrzebne jest konto usługi GitHub.

Omówienie plików definicji artefaktu

Plik definicji artefaktu składa się z wyrażenia JSON, które określa akcję do wykonania na maszynie wirtualnej. Plik definiuje nazwę artefaktu, polecenie do uruchomienia i parametry dostępne dla polecenia. Jeśli artefakt zawiera inne pliki skryptu, możesz odwołać się do plików według nazwy w pliku definicji artefaktu.

W poniższym przykładzie przedstawiono podstawową strukturę pliku definicji artefaktu 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>"
    }
  }

Definicja zawiera następujące wymagane i opcjonalne elementy:

Nazwa elementu	Description
`$schema`	Lokalizacja pliku schematu JSON, który może pomóc w przetestowaniu poprawności pliku definicji.
`title`	Wymagana nazwa artefaktu do wyświetlenia.
`description`	Wymagany opis artefaktu.
`iconUri`	URI ikony artefaktu do wyświetlenia.
`targetOsType`	Wymagany system operacyjny do zainstalowania. Obsługiwane wartości to `Windows` lub `Linux`.
`parameters`	Dostępne dostosowania artefaktów podczas instalacji.
`runCommand`	Wymagane polecenie w celu zainstalowania artefaktu na maszynie wirtualnej.

Parametry artefaktu

Sekcja parameters pliku definicji definiuje opcje i wartości, które użytkownicy mogą określić podczas instalowania artefaktu. Możesz odwołać się do tych parametrów w pliku runCommand.

Następująca struktura definiuje parametr:

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

Każdy parametr wymaga nazwy, a definicja parametru wymaga następujących elementów:

Nazwa elementu	Description
`type`	Wymagany typ wartości parametru. Typ może być dowolnym prawidłowym kodem JSON `string`, liczbą całkowitą `int`, wartością logiczną `bool`lub `array`.
`displayName`	Wymagana nazwa parametru do wyświetlenia użytkownikowi.
`description`	Opis parametru wymaganego .

Parametry bezpiecznego ciągu znaków

Aby uwzględnić tajne dane w definicji artefaktu, zadeklaruj je jako bezpieczne ciągi znaków, używając składni secureStringParam w sekcji parameters pliku definicji. Element description zezwala na dowolny ciąg tekstowy, w tym spacje i przedstawia ciąg w interfejsie użytkownika jako znaki maskowane.


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

runCommand Poniższy skrypt używa skryptu programu PowerShell, który pobiera bezpieczny ciąg utworzony przy użyciu ConvertTo-SecureString polecenia . Skrypt przechwytuje dane wyjściowe na potrzeby debugowania, więc dla bezpieczeństwa nie rejestruj danych wyjściowych w konsoli.

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

Wyrażenia i funkcje artefaktu

Za pomocą wyrażeń i funkcji można skonstruować polecenie instalacji artefaktu. Wyrażenia obliczane są podczas instalacji artefaktu.

Wyrażenia mogą występować w dowolnym miejscu w wartości ciągu JSON i zawsze zwracają inną wartość JSON. Ujmij wyrażenia w nawiasy, [ ]. Jeśli musisz użyć ciągu znaków literałowych rozpoczynającego się nawiasem, użyj dwóch nawiasów [[.

Zwykle używasz wyrażeń z funkcjami do konstruowania wartości. Wywołania funkcji są formatowane jako functionName(arg1, arg2, arg3).

Typowe funkcje obejmują:

Funkcja	Description
`parameters(parameterName)`	Zwraca wartość parametru, która ma być używana podczas uruchamiania polecenia artefaktu.
`concat(arg1, arg2, arg3, ...)`	Łączy wiele wartości ciągów i może przyjmować różne argumenty.

W poniższym przykładzie użyto wyrażeń z funkcją concat do skonstruowania wartości.

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

Tworzenie artefaktu niestandardowego

Możesz utworzyć artefakt niestandardowy, zaczynając od przykładowego pliku definicji artifactfile.json . Publiczne repozytorium artefaktów usługi DevTest Labs zawiera bibliotekę artefaktów. Możesz pobrać plik definicji artefaktu i dostosować go, aby utworzyć własne artefakty.

Pobierz plik definicji artifactfile.json i skrypt programu PowerShell artifact.ps1 z witryny https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Edytuj plik definicji artefaktu, aby wprowadzić prawidłowe zmiany w elementach i wartościach. W programie Visual Studio Code możesz użyć funkcji IntelliSense, aby wyświetlić prawidłowe elementy i opcje wartości. Na przykład podczas edytowania targetOsType elementu funkcja IntelliSense wyświetla opcje Windows lub Linux .
Zapisz artefakt w publicznym lub prywatnym repozytorium artefaktów Git.
- Zapisz każdy plik definicji artefaktu artifactfile.json w osobnym katalogu o nazwie takiej samej jak nazwa artefaktu.
- Zapisz skrypty, do których odwołuje się polecenie instalacji w tym samym katalogu co plik definicji artefaktu.
Poniższy zrzut ekranu przedstawia przykładowy folder artefaktu:

Uwaga / Notatka

Aby dodać artefakty niestandardowe do publicznego repozytorium artefaktów usługi DevTest Labs, otwórz pull request dla repozytorium.

Dalsze kroki

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-12-16