Criar artefactos personalizados para o DevTest Labs

Artigo
09/30/2023

Este artigo descreve como criar ficheiros de artefactos personalizados para Azure DevTest Labs máquinas virtuais (VMs). Os artefactos do DevTest Labs especificam ações a tomar para aprovisionar uma VM. Um artefacto consiste num ficheiro de definição de artefacto e noutros ficheiros de script que armazena numa pasta num repositório Git.

Para obter informações sobre como adicionar os repositórios de artefactos a laboratórios, consulte Adicionar um repositório de artefactos ao laboratório.
Para obter informações sobre como adicionar os artefactos que cria às VMs, veja Add artifacts to DevTest Labs VMs (Adicionar artefactos a VMs do DevTest Labs).
Para obter informações sobre como especificar artefactos obrigatórios a serem adicionados a todas as VMs de laboratório, veja Especificar artefactos obrigatórios para VMs do DevTest Labs.

Ficheiros de definição de artefactos

Os ficheiros de definição de artefactos são expressões JSON que especificam o que pretende instalar numa VM. Os ficheiros definem o nome de um artefacto, um comando a executar e os parâmetros disponíveis para o comando. Pode consultar outros ficheiros de script por nome no ficheiro de definição do artefacto.

O exemplo seguinte mostra as secções que compõem a estrutura básica de um ficheiro de definição de artefacto 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": ""
    }
  }

Nome do elemento	Descrição
`$schema`	Localização do ficheiro de esquema JSON. O ficheiro de esquema JSON pode ajudá-lo a testar a validade do ficheiro de definição.
`title`	Nome do artefacto a apresentar no laboratório. Obrigatório.
`description`	Descrição do artefacto a apresentar no laboratório. Obrigatório.
`iconUri`	URI do ícone do artefacto a apresentar no laboratório.
`targetOsType`	Sistema operativo da VM no qual instalar o artefacto. Valores suportados: `Windows`, `Linux`. Obrigatório.
`parameters`	Valores para personalizar o artefacto ao instalar na VM.
`runCommand`	O comando de instalação do artefacto a executar na VM. Obrigatório.

Parâmetros dos artefactos

Na secção parâmetros do ficheiro de definição, especifique os valores que um utilizador pode introduzir ao instalar um artefacto. Pode ver estes valores no comando de instalação do artefacto.

Para definir parâmetros, utilize a seguinte estrutura:

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

Nome do elemento	Descrição
`type`	Tipo de valor de parâmetro. Obrigatório.
`displayName`	Nome do parâmetro a apresentar ao utilizador do laboratório. Obrigatório.
`description`	Descrição do parâmetro a apresentar ao utilizador do laboratório. Obrigatório.

Os tipos de valores de parâmetro permitidos são:

Tipo	Descrição
`string`	Qualquer cadeia JSON válida
`int`	Qualquer número inteiro JSON válido
`bool`	Qualquer booleano JSON válido
`array`	Qualquer matriz JSON válida

Segredos como cadeias seguras

Para declarar segredos como parâmetros de cadeia de carateres seguros com carateres mascarados na IU, utilize a seguinte sintaxe na parameters secção do ficheiro 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
    },

O comando de instalação do artefacto para executar o script do PowerShell utiliza a cadeia segura criada com o ConvertTo-SecureString comando .

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

Não registe segredos na consola, porque o script captura a saída para a depuração do utilizador.

Expressões e funções de artefactos

Pode utilizar expressões e funções para construir o comando de instalação do artefacto. As expressões avaliam quando o artefacto é instalado. As expressões podem aparecer em qualquer lugar num valor de cadeia JSON e devolver sempre outro valor JSON. Coloque expressões entre parênteses retos, [ ]. Se precisar de utilizar uma cadeia literal que comece com um parêntese reto, utilize dois parênteses retos [[.

Normalmente, utiliza expressões com funções para construir um valor. As chamadas de função são formatadas como functionName(arg1, arg2, arg3).

As funções comuns incluem:

Função	Descrição
`parameters(parameterName)`	Devolve um valor de parâmetro a indicar quando o comando do artefacto é executado.
`concat(arg1, arg2, arg3, ...)`	Combina vários valores de cadeia. Esta função pode utilizar vários argumentos.

O exemplo seguinte utiliza expressões e funções para construir um valor:

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

Criar um artefacto personalizado

Para criar um artefacto personalizado:

Instale um editor JSON para trabalhar com ficheiros de definição de artefactos. O Visual Studio Code está disponível para Windows, Linux e macOS.
Comece com um ficheiro de definição artifactfile.json de exemplo.

O repositório de artefactos do DevTest Labs público tem uma biblioteca avançada de artefactos que pode utilizar. Pode transferir um ficheiro de definição de artefacto e personalizá-lo para criar os seus próprios artefactos.

Este artigo utiliza o ficheiro de definição artifactfile.json e artifact.ps1 script do PowerShell em https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Utilize o IntelliSense para ver opções de elementos e valores válidas que pode utilizar para construir um ficheiro de definição de artefacto. Por exemplo, quando edita o elemento, o targetOsType IntelliSense mostra-lhe Windows ou Linux opções.
Armazene os artefactos em repositórios de artefactos git públicos ou privados.
- Armazene cada ficheiro de definição de artefacto artifactfile.json num diretório separado com o mesmo nome que o nome do artefacto.
- Armazene os scripts que o comando de instalação referencia no mesmo diretório que o ficheiro de definição do artefacto.
A seguinte captura de ecrã mostra uma pasta de artefactos de exemplo:
Para armazenar os artefactos personalizados no repositório de artefactos público do DevTest Labs, abra um pedido Pull no repositório.
Para adicionar o repositório de artefactos privados a um laboratório, veja Adicionar um repositório de artefactos ao laboratório no DevTest Labs.

Share via