DevTest Labs sanal makineniz için özel yapılar oluşturmaCreate custom artifacts for your DevTest Labs virtual machine

Bu makalede açıklanan adımlara genel bir bakış için aşağıdaki videoyu izleyin:Watch the following video for an overview of the steps described in this article:

Genel BakışOverview

Bir VM sağlamadıktan sonra, uygulamanızı dağıtmak ve ayarlamak için yapıtları kullanabilirsiniz.You can use artifacts to deploy and set up your application after you provision a VM. Yapıt bir yapıt tanım dosyasından ve git deposundaki bir klasörde depolanan diğer betik dosyalarından oluşur.An artifact consists of an artifact definition file and other script files that are stored in a folder in a Git repository. Yapıt tanımı dosyaları, bir VM 'ye ne yüklemek istediğinizi belirtmek için kullanabileceğiniz JSON ve ifadelerden oluşur.Artifact definition files consist of JSON and expressions that you can use to specify what you want to install on a VM. Örneğin, bir yapıt adı, çalıştırılacak bir komut ve komut çalıştırıldığında kullanılabilir parametreler tanımlayabilirsiniz.For example, you can define the name of an artifact, a command to run, and parameters that are available when the command is run. Yapıt tanım dosyası içindeki diğer betik dosyalarına adı ile başvurabilirsiniz.You can refer to other script files within the artifact definition file by name.

Yapıt tanım dosyası biçimiArtifact definition file format

Aşağıdaki örnek, bir tanım dosyasının temel yapısını oluşturan bölümleri gösterir: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": ""
  }
}
Öğe adıElement name Gerekli mi?Required? AçıklamaDescription
$schema$schema NoNo JSON Şema dosyasının konumu.Location of the JSON schema file. JSON şema dosyası, tanım dosyasının geçerliliğini test etmenize yardımcı olabilir.The JSON schema file can help you test the validity of the definition file.
başlıktitle YesYes Laboratuvarda görünen yapıt adı.Name of the artifact displayed in the lab.
açıklamadescription YesYes Laboratuvarda görünen yapının açıklaması.Description of the artifact displayed in the lab.
ıconuriiconUri NoNo Laboratuvarda görünen simgenin URI 'SI.URI of the icon displayed in the lab.
targetOsTypetargetOsType YesYes Yapıtın yüklendiği VM 'nin işletim sistemi.Operating system of the VM where the artifact is installed. Desteklenen seçenekler Windows ve Linux.Supported options are Windows and Linux.
parametrelerparameters NoNo Bir makinede yapıt install komutu çalıştırıldığında belirtilen değerler.Values that are provided when the artifact install command is run on a machine. Bu, yapıtı özelleştirmenize yardımcı olur.This helps you customize your artifact.
EyleminerunCommand YesYes Bir VM üzerinde yürütülen yapıt install komutu.Artifact install command that is executed on a VM.

Yapıt parametreleriArtifact parameters

Tanım dosyasının parametreler bölümünde, bir kullanıcının bir yapıtı yüklediklerinde hangi değerlere giriş yapabilir olduğunu belirtin.In the parameters section of the definition file, specify which values a user can input when they install an artifact. Yapıt install komutunda bu değerlere başvurabilirsiniz.You can refer to these values in the artifact install command.

Parametreleri tanımlamak için aşağıdaki yapıyı kullanın:To define parameters, use the following structure:

"parameters": {
  "<parameterName>": {
    "type": "<type-of-parameter-value>",
    "displayName": "<display-name-of-parameter>",
    "description": "<description-of-parameter>"
  }
}
Öğe adıElement name Gerekli mi?Required? AçıklamaDescription
türtype YesYes Parametre değerinin türü.Type of parameter value. İzin verilen türler için aşağıdaki listeye bakın.See the following list for the allowed types.
displayNamedisplayName YesYes Laboratuvardaki bir kullanıcıya görüntülenen parametrenin adı.Name of the parameter that is displayed to a user in the lab.
açıklamadescription YesYes Laboratuvarda görüntülenen parametrenin açıklaması.Description of the parameter that is displayed in the lab.

İzin verilen türler şunlardır:Allowed types are:

  • dize (geçerli JSON dizesi)string (any valid JSON string)
  • int (herhangi bir geçerli JSON tamsayı)int (any valid JSON integer)
  • bool (herhangi bir geçerli JSON Boole değeri)bool (any valid JSON Boolean)
  • dizi (geçerli JSON dizisi)array (any valid JSON array)

Güvenli dizeler olarak gizli dizilerSecrets as secure strings

Gizli dizeleri güvenli dizeler olarak bildirin.Declare secrets as secure strings. parametersDosyadaki artifactfile.js bölümünde güvenli bir dize parametresi bildirmek için sözdizimi aşağıda verilmiştir: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
    },

Yapıt install komutu için, ConvertTo-SecureString komutu kullanılarak oluşturulan güvenli dizeyi alan PowerShell betiğini çalıştırın.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'), '\"')]"
  }

Tüm örnek artifactfile.jsve artifact.ps1 (PowerShell betiği) için GitHub 'da bu örneğebakın.For the complete example artifactfile.json and the artifact.ps1 (PowerShell script), see this sample on GitHub.

Bir diğer önemli nokta, Kullanıcı hata ayıklaması için çıktı yakalandığından gizli dizileri konsola günlüğe kaydetmek değildir.Another important point to note is not to log secrets to the console as output is captured for user debugging.

Yapıt ifadeleri ve işlevleriArtifact expressions and functions

Yapıt install komutunu oluşturmak için ifadeleri ve işlevleri kullanabilirsiniz.You can use expressions and functions to construct the artifact install command. İfadeler köşeli ayraçlar ([ve]) ile çevrelenmiş ve yapıt yüklendiği zaman değerlendirilir.Expressions are enclosed with brackets ([ and ]), and are evaluated when the artifact is installed. İfadeler, JSON dize değerinde herhangi bir yerde görünebilir.Expressions can appear anywhere in a JSON string value. İfadeler her zaman başka bir JSON değeri döndürür.Expressions always return another JSON value. Köşeli ayraç ([) ile başlayan bir sabit dize kullanmanız gerekiyorsa, iki köşeli ayraç ([[) kullanmanız gerekir.If you need to use a literal string that starts with a bracket ([), you must use two brackets ([[). Genellikle, bir değer oluşturmak için işlevleri işlevlerle birlikte kullanırsınız.Typically, you use expressions with functions to construct a value. JavaScript içinde olduğu gibi, işlev çağrıları fonksiyonadı (arg1, arg2, arg3) olarak biçimlendirilir.Just like in JavaScript, function calls are formatted as functionName(arg1, arg2, arg3).

Aşağıdaki listede yaygın işlevler gösterilmektedir:The following list shows common functions:

  • Parametreler (ParameterName): yapıt komutu çalıştırıldığında belirtilen bir parametre değeri döndürür.parameters(parameterName): Returns a parameter value that is provided when the artifact command is run.
  • Concat (arg1, arg2, arg3,.....): birden çok dize değerini birleştirir.concat(arg1, arg2, arg3,….. ): Combines multiple string values. Bu işlev, çeşitli bağımsız değişkenler alabilir.This function can take a variety of arguments.

Aşağıdaki örnek, bir değer oluşturmak için ifadelerin ve işlevlerin nasıl kullanılacağını gösterir: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'))]"
}

Özel yapıt oluşturmaCreate a custom artifact

  1. JSON Düzenleyicisi yükler.Install a JSON editor. Yapıt tanım dosyalarıyla çalışmak için bir JSON düzenleyicisine ihtiyacınız vardır.You need a JSON editor to work with artifact definition files. Windows, Linux ve OS X için kullanılabilen Visual Studio Codekullanmanızı öneririz.We recommend using Visual Studio Code, which is available for Windows, Linux, and OS X.

  2. Tanım dosyasında bir örnek artifactfile.jsalın.Get a sample artifactfile.json definition file. GitHub deponuzdaDevTest Labs ekibi tarafından oluşturulan yapıtları inceleyin.Check out the artifacts created by the DevTest Labs team in our GitHub repository. Kendi yapılarınızı oluşturmanıza yardımcı olabilecek zengin bir yapıt kitaplığı oluşturduk.We have created a rich library of artifacts that can help you create your own artifacts. Kendi yapıtlarınızı oluşturmak için bir yapıt tanım dosyası indirin ve üzerinde değişiklikler yapın.Download an artifact definition file and make changes to it to create your own artifacts.

  3. IntelliSense 'in kullanımını yapın.Make use of IntelliSense. Bir yapıt tanım dosyası oluşturmak için kullanabileceğiniz geçerli öğeleri görmek için IntelliSense kullanın.Use IntelliSense to see valid elements that you can use to construct an artifact definition file. Ayrıca, bir öğenin değerleri için farklı seçenekleri görebilirsiniz.You also can see the different options for values of an element. Örneğin, Targetostype öğesini düzenlediğinizde, IntelliSense Windows veya Linux için size iki seçenek gösterir.For example, when you edit the targetOsType element, IntelliSense shows you two choices, for Windows or Linux.

  4. Yapıtı DevTest Labs veya kendi git deponuzdaki genel git deposunda depolayın.Store the artifact in the public Git repository for DevTest Labs or your own Git repository. Ortak depoda, başkaları tarafından paylaşılan yapıtları, doğrudan kullanabileceğiniz veya gereksinimlerinize uyacak şekilde özelleştirebilmeniz için görüntüleyebilirsiniz.In the public repository, you can view artifacts shared by others that you can use directly or customize them to suit your needs.

    1. Her yapıt için ayrı bir dizin oluşturun.Create a separate directory for each artifact. Dizin adı yapıt adı ile aynı olmalıdır.The directory name should be the same as the artifact name.

    2. Yapıt tanım dosyasını (artifactfile.jsüzerinde) oluşturduğunuz dizinde depolayın.Store the artifact definition file (artifactfile.json) in the directory that you created.

    3. Yapıt install komutuyla başvurulan betikleri depolayın.Store the scripts that are referenced from the artifact install command.

      Yapıt klasörünün nasıl görünebileceğini gösteren bir örnek aşağıda verilmiştir:Here is an example of how an artifact folder might look:

      Yapıt klasörü örneği

  5. Yapıtları depolamak için kendi deponuzu kullanıyorsanız, Şu makaledeki yönergeleri izleyerek depoyu laboratuvara ekleyin: yapılar ve şablonlar Için Git deposu ekleme.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.

Sonraki adımlarNext steps