Sdílet prostřednictvím

Definování proměnných

  • Článek

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Proměnné poskytují pohodlný způsob, jak do různých částí datového toku dostat klíčová data. Proměnné se nejčastěji používají k definování hodnoty, kterou pak můžete použít ve svém datovém toku. Všechny proměnné jsou měnitelné řetězce. Hodnota proměnné se může v jednotlivých spuštěních nebo úlohách kanálu měnit.

Když definujete stejnou proměnnou na více místech se stejným názvem, má přednost nejvíce místně vymezená proměnná. Proměnná definovaná na úrovni úlohy tedy může přepsat proměnnou nastavenou na úrovni fáze. Proměnná definovaná na úrovni fáze přepíše proměnnou nastavenou na úrovni kořenového kanálu. Proměnná nastavená v kořenové úrovni kanálu přepíše proměnnou nastavenou v uživatelském rozhraní nastavení kanálu. Další informace o práci s proměnnými definovanými na úrovni úlohy, fáze a kořenové úrovně najdete v tématu Rozsah proměnných.

Proměnné s výrazy můžete použít k podmíněnému přiřazování hodnot a dalším přizpůsobení kanálů.

Proměnné se liší od parametrů modulu runtime. Parametry modulu runtime jsou typované a dostupné během parsování šablony.

Uživatelem definované proměnné

Při definování proměnné můžete použít různé syntaxe (makro, výraz šablony nebo modul runtime) a jakou syntaxi použijete, určuje, kde se proměnná v kanálu vykresluje.

V potrubích YAML můžete nastavit proměnné na úrovni rootu, fáze a úlohy. V uživatelském rozhraní můžete také zadat proměnné mimo kanál YAML. Když nastavíte proměnnou v uživatelském rozhraní, může být tato proměnná zašifrována a nastavena jako tajný klíč.

Uživatelem definované proměnné lze nastavit jen pro čtení. Pro proměnné existují omezení pojmenování (příklad: Nemůžete použít secret na začátku názvu proměnné).

Skupinu proměnných můžete použít k zpřístupnění proměnných napříč několika kanály.

Pomocí šablon můžete definovat proměnné v jednom souboru, který se používá v několika kanálech.

Uživatelem definované víceřádkové proměnné

Azure DevOps podporuje víceřádkové proměnné, ale existuje několik omezení.

Dílčí komponenty, jako jsou úlohy v potrubí, nemusí správně zpracovávat hodnoty proměnných.

Azure DevOps nezmění hodnoty proměnných definovaných uživatelem. Hodnoty proměnných musí být před předáním víceřádkových proměnných správně naformátované. Při formátování proměnné nepoužívejte speciální znaky, nepoužívejte omezené názvy a ujistěte se, že používáte formát konce řádku, který funguje pro operační systém vašeho agenta.

Víceřádkové proměnné se chovají odlišně v závislosti na operačním systému. Abyste tomu předešli, ujistěte se, že pro cílový operační systém správně naformátujete víceřádkové proměnné.

Azure DevOps nikdy nemění hodnoty proměnných, i když poskytujete nepodporované formátování.

Systémové proměnné

Kromě uživatelem definovaných proměnných má Azure Pipelines systémové proměnné s předdefinovanými hodnotami. Například předdefinovaná proměnná Build.BuildId poskytuje ID každého sestavení a můžete použít k identifikaci různých spuštění pipelinu. Proměnnou Build.BuildId můžete použít ve skriptech nebo úkolech, když potřebujete jedinečnou hodnotu.

Pokud používáte YAML nebo klasické kanály sestavení, podívejte se na předdefinované proměnné , kde najdete komplexní seznam systémových proměnných.

Pokud používáte klasické publikační kanály, podívejte se na proměnné pro vydání.

Systémové proměnné se při spuštění potrubí automaticky nastaví s jejich aktuální hodnotou. Některé proměnné se nastaví automaticky. Jako autor kanálu nebo koncový uživatel změníte hodnotu systémové proměnné před spuštěním kanálu.

Systémové proměnné jsou jen pro čtení.

Proměnné prostředí

Proměnné prostředí jsou specifické pro operační systém, který používáte. Jsou vloženy do datového toku specifickými způsoby pro platformu. Formát odpovídá způsobu formátování proměnných prostředí pro vaši konkrétní skriptovací platformu.

V systémech UNIX (macOS a Linux) mají proměnné prostředí formát $NAME. Ve Windows je formát %NAME% pro dávkový soubor a $env:NAME v PowerShellu.

Systémové a uživatelem definované proměnné (kromě tajných proměnných) se také vloží jako proměnné prostředí pro vaši platformu. Když se proměnné změní na proměnné prostředí, názvy proměnných se převedou na velká písmena a tečky se nahradí podtržítky. Například se název proměnné any.variable změní na název proměnné $ANY_VARIABLE.

Existují omezení pojmenovávání proměnných pro proměnné prostředí (příklad: Nemůžete použít secret na začátku názvu proměnné).

Omezení názvů proměnných

Uživatelsky definované proměnné a proměnné prostředí mohou obsahovat písmena, číslice . a znaky _. Nepoužívejte předpony proměnných rezervované systémem. Toto jsou: endpoint, , inputsecret, patha securefile. Každá proměnná, která začíná jedním z těchto řetězců (bez ohledu na velká písmena), nebude k dispozici pro vaše úkoly a skripty.

Principy syntaxe proměnných

Azure Pipelines podporuje tři různé způsoby odkazování na proměnné: makro, výraz šablony a běhový výraz. Každou syntaxi můžete použít pro jiný účel a každá má určitá omezení.

V rámci kanálu se proměnné výrazů šablony (${{ variables.var }}) zpracovávají v době kompilace, ještě před zahájením běhu programu. Proměnné syntaxe maker ($(var)) se zpracovávají během běhu před spuštěním úlohy. Výrazy runtime ($[variables.var]) se zpracovávají při běhu a jsou určeny k použití s podmínkami a výrazy. Pokud používáte běhový výraz, musí zabírat celou pravou stranu definice.

V tomto příkladu můžete vidět, že výraz šablony má stále počáteční hodnotu proměnné i po její aktualizaci. Hodnota proměnné syntaxe makra se aktualizuje. Hodnota výrazu šablony se nemění, protože všechny proměnné výrazů šablony se zpracovávají v době kompilace před spuštěním úloh. Proměnné makrosyntaxe se naproti tomu vyhodnocují před spuštěním každé úlohy.

variables:
- name: one
  value: initialValue 

steps:
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one)
    displayName: First variable pass
  - bash: echo "##vso[task.setvariable variable=one]secondValue"
    displayName: Set new variable value
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one) # outputs secondValue
    displayName: Second variable pass

Proměnné syntaxe maker

Příklady v dokumentaci většinou používají syntaxi maker ($(var)). Syntaxe makra je určená k interpolaci hodnot proměnných do vstupů úkolů a do jiných proměnných.

Proměnné s makro syntaxí se zpracovávají před tím, než se úloha spustí za běhu. K běhu dochází po rozšíření šablony. Když systém narazí na výraz makra, nahradí výraz obsahem proměnné. Pokud tento název neobsahuje žádnou proměnnou, výraz makra se nezmění. Pokud například $(var) nelze nahradit, pak se $(var) ničím nenahradí.

Proměnné syntaxe maker zůstávají beze změny a bez nastavené hodnoty, protože prázdná hodnota jako $() může znamenat něco pro úlohu, kterou právě provádíte, a agent by neměl automaticky předpokládat, že chcete tuto hodnotu nahradit. Pokud například použijete $(foo) k odkazu na proměnnou foo v úloze Bash, může nahrazení všech $() výrazů ve vstupu do úlohy narušit vaše skripty Bash.

Proměnné maker se expandují pouze v případě, že jsou použity pro hodnotu, ne jako klíčové slovo. Hodnoty se zobrazí na pravé straně definice kanálu. Toto je platné: key: $(value). Toto není platné: $(key): value. Proměnné maker nejsou rozbalené, pokud se používají k zobrazení názvu úlohy v textu. Místo toho musíte použít displayName vlastnost.

Poznámka:

Proměnné syntaxe maker jsou rozbalené pouze pro stages, jobs a steps. Například nemůžete použít syntaxi makra uvnitř resource nebo trigger.

V tomto příkladu se používá syntaxe maker s Bashem, PowerShellem a skriptovou úlohou. Syntaxe pro volání proměnné se syntaxí makra je stejná pro všechny tři.

variables:
 - name: projectName
   value: contoso

steps: 
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)

Syntaxe výrazu šablony

Pomocí syntaxe výrazu šablony můžete rozšířit parametry šablony i proměnné (${{ variables.var }}). Proměnné šablony jsou zpracovány v době kompilace a nahrazeny ještě před spuštěním programu. Výrazy šablon jsou navržené pro opakované použití částí YAML jako šablon.

Proměnné šablony se neslyšně slijí do prázdných řetězců, pokud se nenajde náhradní hodnota. Výrazy šablony, na rozdíl od výrazů makra a modulu runtime, se můžou zobrazit jako klíče (levá strana) nebo hodnoty (pravá strana). Toto je platné: ${{ variables.key }} : ${{ variables.value }}.

Syntaxe výrazů modulu runtime

Syntaxe výrazů runtime můžete použít pro proměnné, které jsou rozšířené za běhu ($[variables.var]). Proměnné výrazů modulu runtime se tiše spojí s prázdnými řetězci, pokud není nalezena žádná náhradní hodnota. Použití výrazů modulu runtime v podmínkách úlohy k podpoře podmíněného spouštění úloh nebo celých fází.

Proměnné výrazů modulu runtime jsou rozšířeny jen tehdy, když jsou použity jako hodnota, ne jako klíčové slovo. Hodnoty se zobrazí na pravé straně definice kanálu. Toto je platné: key: $[variables.value]. Toto není platné: $[variables.key]: value. Výraz runtime musí obsáhnout celou pravou stranu páru klíč-hodnota. Například key: $[variables.value] je platný, ale key: $[variables.value] foo není.

Syntaxe Příklad Kdy se zpracovává? Kde se rozšiřuje v definici pipeline? Jak se vykresluje, když není nalezeno?
makro $(var) runtime před spuštěním úlohy hodnota (pravá strana) tiskne $(var)
výraz šablony ${{ variables.var }} čas kompilace klíč nebo hodnota (vlevo nebo vpravo) prázdný řetězec
výraz runtime $[variables.var] běhové prostředí hodnota (pravá strana) prázdný řetězec

Jakou syntaxi mám použít?

Syntaxi makra použijte, pokud pro úlohu poskytujete zabezpečený řetězec nebo předdefinovaný vstup proměnné .

Pokud pracujete s podmínkami a výrazy, zvolte výraz pro dobu běhu. Výraz runtime však nepoužívejte, pokud nechcete, aby se prázdná proměnná vytiskla (příklad: $[variables.var]). Pokud máte například podmíněnou logiku, která spoléhá na proměnnou, která má konkrétní hodnotu nebo žádnou hodnotu. V takovém případě byste měli použít výraz makra.

Obvykle je proměnná šablony standardem, který se má použít. Díky využití proměnných šablon vaše pipelina zcela vloží hodnotu proměnné do vašeho systému během kompilace. To je užitečné při ladění datových toků. Můžete stáhnout soubory protokolu a vyhodnotit plně rozšířenou hodnotu, která je nahrazována. Vzhledem k tomu, že je proměnná nahrazena, neměli byste pro citlivé hodnoty využívat syntaxi šablony.

Nastavení proměnných v potrubí

V nejběžnějším případě nastavíte proměnné a použijete je v souboru YAML. Díky tomu můžete sledovat změny proměnné v systému správy verzí. Můžete také definovat proměnné v uživatelském rozhraní nastavení kanálu (viz karta Classic) a odkazovat na ně v YAML.

Tady je příklad, který ukazuje, jak nastavit dvě proměnné configuration a platformjak je použít později v krocích. Chcete-li použít proměnnou v příkazu YAML, zabalte ji do $(). Proměnné nelze použít k definování repository v příkazu YAML.

# Set variables once
variables:
  configuration: debug
  platform: x64

steps:

# Use them once
- task: MSBuild@1
  inputs:
    solution: solution1.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

# Use them again
- task: MSBuild@1
  inputs:
    solution: solution2.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

Proměnné rozsahu

V souboru YAML můžete nastavit proměnnou v různých oborech:

  • Na úrovni kořene ho zpřístupníte pro všechny úlohy v pipeline.
  • Na úrovni fáze ji zpřístupníte pouze pro určitou fázi.
  • Na úrovni úlohy ji zpřístupníte tak, aby byla dostupná pouze pro konkrétní úlohu.

Když definujete proměnnou v horní části YAML, je tato proměnná dostupná pro všechny úlohy a fáze v kanálu a je globální proměnnou. Globální proměnné definované v YAML nejsou viditelné v uživatelském rozhraní nastavení kanálu.

Proměnné na úrovni úlohy přepisují proměnné na úrovni kořene a fáze. Proměnné na úrovni fáze přepisují proměnné na kořenové úrovni.

variables:
  global_variable: value    # this is available to all jobs

jobs:
- job: job1
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable1: value1    # this is only available in job1
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable1)
  - bash: echo $JOB_VARIABLE1 # variables are available in the script environment too

- job: job2
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable2: value2    # this is only available in job2
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable2)
  - bash: echo $GLOBAL_VARIABLE

Výstup obou úloh vypadá takto:

# job1
value 
value1
value1

# job2
value
value2
value

Zadání proměnných

V předchozích příkladech následuje za klíčovým slovem variables seznam dvojic klíč-hodnota. Klíče jsou názvy proměnných a hodnoty jsou hodnoty proměnných.

Existuje další syntaxe, která je užitečná, když chcete použít šablony pro proměnné nebo skupiny proměnných.

Pomocí šablon lze proměnné definovat v jednom YAML a zahrnout do jiného souboru YAML.

Skupiny proměnných jsou sada proměnných, které můžete použít napříč několika kanály. Umožňují spravovat a organizovat proměnné, které jsou společné pro různé fáze na jednom místě.

Tuto syntaxi použijte pro šablony proměnných a skupiny proměnných na kořenové úrovni pipeliny.

V této alternativní syntaxi klíčové slovo variables přebírá seznam specifikátorů proměnných. Specifikátory proměnných jsou name určené pro běžnou proměnnou, group pro skupinu proměnných a template pro zahrnutí šablony proměnné. Následující příklad ukazuje všechny tři.

variables:
# a regular variable
- name: myvariable
  value: myvalue
# a variable group
- group: myvariablegroup
# a reference to a variable template
- template: myvariabletemplate.yml

Přečtěte si další informace o opakovaném použití proměnných pomocí šablon.

Přístup k proměnným prostřednictvím prostředí

Všimněte si, že proměnné jsou také zpřístupněny skriptům prostřednictvím proměnných prostředí. Syntaxe pro použití těchto proměnných prostředí závisí na skriptovacím jazyce.

Název je velkými písmeny a . je nahrazen znakem _. Ten se automaticky vloží do procesního prostředí. Několik příkladů:

  • Dávkový skript: %VARIABLE_NAME%
  • Skript PowerShellu: $env:VARIABLE_NAME
  • Skript Bash: $VARIABLE_NAME

Důležité

Předdefinované proměnné, které obsahují cesty k souborům, se překládají na odpovídající styl (styl Windows C:\foo\ versus Unix style /foo/) na základě typu hostitele agenta a typu prostředí. Pokud spouštíte úlohy skriptu Bash ve Windows, měli byste pro přístup k těmto proměnným použít metodu proměnných prostředí namísto metody potrubních proměnných, abyste zajistili správný formát cesty k souboru.

Nastavení tajných proměnných

Doporučení

Tajné proměnné se automaticky neexportují jako proměnné prostředí. Pokud chcete ve skriptech použít tajné proměnné, explicitně je namapujte na proměnné prostředí. Další informace naleznete v tématu Nastavení tajných proměnných.

Nenastavujte v souboru YAML tajné proměnné. Operační systémy často protokolují příkazy pro procesy, které spouští, a nechcete, aby protokol obsahoval tajný kód, který jste předali jako vstup. Pomocí prostředí skriptu nebo mapujte proměnnou v rámci bloku variables k předání citlivých údajů do vaší pipeliny.

Poznámka:

Azure Pipelines se snaží maskovat citlivé údaje při zásílání dat do protokolů kanálu, takže můžete vidět další proměnné a data maskovaná ve výstupu a protokolech, které nejsou označené jako tajnosti.

V uživatelském rozhraní nastavení potrubí musíte nastavit tajné proměnné. Tyto proměnné jsou omezeny na potrubí, ve kterém jsou nastaveny. Tajné proměnné můžete také nastavit ve skupinách proměnných.

Pokud chcete nastavit tajné kódy ve webovém rozhraní, postupujte takto:

  1. Přejděte na stránku Kanály , vyberte příslušný kanál a pak vyberte Upravit.
  2. Vyhledejte proměnné pro tento kanál.
  3. Přidejte nebo aktualizujte proměnnou.
  4. Vyberte možnost Uchovat tuto hodnotu v tajnosti, aby se proměnná ukládala šifrovaným způsobem.
  5. Uložte potrubí.

Tajné proměnné se šifrují v klidovém stavu pomocí 2048bitového klíče RSA. Tajné kódy jsou k dispozici v agentu pro úlohy a skripty, které se mají použít. Dávejte pozor na to, kdo má přístup ke změně vaší pipeline.

Důležité

Snažíme se maskovat tajné kódy, které se zobrazují ve výstupu Služby Azure Pipelines, ale přesto je potřeba provést preventivní opatření. Nikdy nevypisujte tajnosti jako výstup. Některé operační systémy zaznamenávají argumenty příkazového řádku. Nikdy nepředávejte tajné kódy na příkazovém řádku. Místo toho doporučujeme namapovat vaše tajemství na proměnné prostředí.

Nikdy nezamaskujeme podřetěžky tajných kódů. Pokud je například "abc123" nastaven jako tajný kód, "abc" není maskován z protokolů. Tím se vyhnete maskování tajných kódů na příliš podrobné úrovni, aby protokoly byly nečitelné. Z tohoto důvodu by tajné kódy neměly obsahovat strukturovaná data. Pokud je například "{ "foo": "bar" }" nastaven jako tajný kód, "bar" není maskován z protokolů.

Na rozdíl od normální proměnné nejsou automaticky dešifrovány do proměnných prostředí pro skripty. Musíte explicitně mapovat tajné proměnné.

Následující příklad ukazuje, jak mapovat a používat tajnou proměnnou volanou mySecret ve skriptech PowerShellu a Bash. Jsou definovány dvě globální proměnné. GLOBAL_MYSECRET je přiřazena hodnota tajné proměnné mySecret, a GLOBAL_MY_MAPPED_ENV_VAR je přiřazena hodnota netajné proměnné nonSecretVariable. Na rozdíl od běžné proměnné kanálu neexistuje žádná proměnná prostředí nazývaná MYSECRET.

Úloha PowerShellu spustí skript pro tisk proměnných.

  • $(mySecret): Toto je přímý odkaz na tajnou proměnnou a funguje.
  • $env:MYSECRET: Tento pokus o přístup k tajné proměnné jako k proměnné prostředí nefunguje, protože tajné proměnné nejsou automaticky mapovány na proměnné prostředí.
  • $env:GLOBAL_MYSECRET: Tento pokus o přístup k tajné proměnné prostřednictvím globální proměnné, která také nefunguje, protože tajné proměnné nelze tímto způsobem mapovat.
  • $env:GLOBAL_MY_MAPPED_ENV_VAR: Tímto se přistupuje k neveřejné proměnné prostřednictvím globální proměnné, což funguje.
  • $env:MY_MAPPED_ENV_VAR: Tato metoda přistupuje k tajné proměnné prostřednictvím proměnné prostředí specifické pro úlohu, což je doporučený způsob mapování tajných proměnných na proměnné prostředí.
variables:
 GLOBAL_MYSECRET: $(mySecret) # this will not work because the secret variable needs to be mapped as env
 GLOBAL_MY_MAPPED_ENV_VAR: $(nonSecretVariable) # this works because it's not a secret.

steps:

- powershell: |
    Write-Host "Using an input-macro works: $(mySecret)"
    Write-Host "Using the env var directly does not work: $env:MYSECRET"
    Write-Host "Using a global secret var mapped in the pipeline does not work either: $env:GLOBAL_MYSECRET"
    Write-Host "Using a global non-secret var mapped in the pipeline works: $env:GLOBAL_MY_MAPPED_ENV_VAR" 
    Write-Host "Using the mapped env var for this task works and is recommended: $env:MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

- bash: |
    echo "Using an input-macro works: $(mySecret)"
    echo "Using the env var directly does not work: $MYSECRET"
    echo "Using a global secret var mapped in the pipeline does not work either: $GLOBAL_MYSECRET"
    echo "Using a global non-secret var mapped in the pipeline works: $GLOBAL_MY_MAPPED_ENV_VAR" 
    echo "Using the mapped env var for this task works and is recommended: $MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

Výstup z obou úloh v předchozím skriptu by vypadal takto:

Using an input-macro works: ***
Using the env var directly does not work:
Using a global secret var mapped in the pipeline does not work either:
Using a global non-secret var mapped in the pipeline works: foo
Using the mapped env var for this task works and is recommended: ***

Můžete také použít tajné proměnné mimo skripty. Například můžete pomocí definice variables mapovat tajné proměnné na úkoly. Tento příklad ukazuje, jak používat tajné proměnné $(vmsUser) a $(vmsAdminPass) v úloze kopírování souboru Azure.

variables:
  VMS_USER: $(vmsUser)
  VMS_PASS: $(vmsAdminPass)

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureFileCopy@4
  inputs:
    SourcePath: 'my/path'
    azureSubscription: 'my-subscription'
    Destination: 'AzureVMs'
    storage: 'my-storage'
    resourceGroup: 'my-rg'
    vmsAdminUserName: $(VMS_USER)
    vmsAdminPassword: $(VMS_PASS)

Odkazy na tajné proměnné ve skupinách proměnných

Tento příklad ukazuje, jak odkazovat na skupinu proměnných v souboru YAML a také jak přidat proměnné v rámci YAML. Ze skupiny proměnných se používají dvě proměnné: user a token. Proměnná token je tajná a mapuje se na proměnnou $env:MY_MAPPED_TOKEN prostředí, aby na ni bylo možné odkazovat v YAML.

Tento YAML provede volání REST k načtení seznamu vydaných verzí a výstupu výsledku.

variables: 
- group: 'my-var-group' # variable group
- name: 'devopsAccount' # new variable defined in YAML
  value: 'contoso'
- name: 'projectName' # new variable defined in YAML
  value: 'contosoads'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
        # Encode the Personal Access Token (PAT)
        # $env:USER is a normal variable in the variable group
        # $env:MY_MAPPED_TOKEN is a mapped secret variable
        $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $env:USER,$env:MY_MAPPED_TOKEN)))

        # Get a list of releases
        $uri = "https://vsrm.dev.azure.com/$(devopsAccount)/$(projectName)/_apis/release/releases?api-version=5.1"

        # Invoke the REST call
        $result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

        # Output releases in JSON
        Write-Host $result.value
  env:
    MY_MAPPED_TOKEN: $(token) # Maps the secret variable $(token) from my-var-group

Důležité

Ve výchozím nastavení s úložišti GitHub nejsou tajné proměnné přidružené k vašemu CI/CD pipeline zpřístupněny pro sestavení pull requestů z forků. Další informace naleznete v tématu Příspěvky z forků.

Sdílení proměnných mezi pipelineami

Pokud chcete sdílet proměnné mezi několika kanály v projektu, použijte webové rozhraní. V části Knihovna použijte skupiny proměnných.

Použití výstupních proměnných z úkolů

Některé úlohy definují výstupní proměnné, které můžete využívat v podřízených krocích, úlohách a fázích. V YAML můžete přistupovat k proměnným napříč úlohami a fázemi pomocí závislostí.

Při odkazování na maticové úlohy v podřízených úkolech budete muset použít jinou syntaxi. Viz Nastavení výstupní proměnné s více úlohami. Musíte také použít jinou syntaxi pro proměnné v úlohách nasazení. Viz Podpora výstupních proměnných v úlohách nasazení.

  • Pokud chcete odkazovat na proměnnou z jiného úkolu ve stejné úloze, použijte TASK.VARIABLE.
  • Pokud chcete odkazovat na proměnnou z úkolu z jiné úlohy, použijte dependencies.JOB.outputs['TASK.VARIABLE'].

Poznámka:

Ve výchozím nastavení každá fáze v potrubí závisí na fázi bezprostředně předcházející v souboru YAML. Pokud potřebujete odkazovat na fázi, která není bezprostředně před aktuální fází, můžete tuto automatickou výchozí hodnotu přepsat přidáním dependsOn oddílu do fáze.

Poznámka:

Následující příklady používají standardní syntaxi pipeline. Pokud používáte kanály nasazení, bude se lišit syntaxe jak běžných proměnných, tak i podmíněných proměnných. Informace o konkrétní syntaxi, která se má použít, najdete v tématu Úlohy nasazení.

V těchto příkladech předpokládejme, že máme úlohu nazvanou MyTask, která nastaví výstupní proměnnou s názvem MyVar. Přečtěte si další informace o syntaxi výrazů – závislosti.

Použití výstupů ve stejné úloze

steps:
- task: MyTask@1  # this step generates the output variable
  name: ProduceVar  # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable

Použití výstupů v jiné úloze

jobs:
- job: A
  steps:
  # assume that MyTask generates an output variable called "MyVar"
  # (you would learn that from the task's documentation)
  - task: MyTask@1
    name: ProduceVar  # because we're going to depend on it, we need to name the step
- job: B
  dependsOn: A
  variables:
    # map the output variable from A into this job
    varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
  steps:
  - script: echo $(varFromA) # this step uses the mapped-in variable

Použití výstupů v jiné fázi

Pokud chcete použít výstup z jiné fáze, formát pro odkazování na proměnné je stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE']. Na úrovni fáze, ale ne na úrovni úlohy, můžete tyto proměnné použít v podmínkách.

Výstupní proměnné jsou k dispozici pouze v další podřízené fázi. Pokud více fází spotřebovává stejnou výstupní proměnnou, použijte podmínku dependsOn .

stages:
- stage: One
  jobs:
  - job: A
    steps:
    - task: MyTask@1  # this step generates the output variable
      name: ProduceVar  # because we're going to depend on it, we need to name the step

- stage: Two
  dependsOn:
  - One
  jobs:
  - job: B
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

- stage: Three
  dependsOn:
  - One
  - Two
  jobs:
  - job: C
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

Proměnné mezi fázemi můžete předat také pomocí souborového vstupu. K tomu budete muset definovat proměnné ve druhé fázi na úrovni úlohy a pak proměnné předat jako env: vstupy.

## script-a.sh
echo "##vso[task.setvariable variable=sauce;isOutput=true]crushed tomatoes"

## script-b.sh
echo 'Hello file version'
echo $skipMe
echo $StageSauce

## azure-pipelines.yml
stages:

- stage: one
  jobs:
  - job: A
    steps:
    - task: Bash@3
      inputs:
          filePath: 'script-a.sh'
      name: setvar
    - bash: |
       echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]true"
      name: skipstep

- stage: two
  jobs:
  - job: B
    variables:
      - name: StageSauce
        value: $[ stageDependencies.one.A.outputs['setvar.sauce'] ]
      - name: skipMe
        value: $[ stageDependencies.one.A.outputs['skipstep.skipsubsequent'] ]
    steps:
    - task: Bash@3
      inputs:
        filePath: 'script-b.sh'
      name: fileversion
      env:
        StageSauce: $(StageSauce) # predefined in variables section
        skipMe: $(skipMe) # predefined in variables section
    - task: Bash@3
      inputs:
        targetType: 'inline'
        script: |
          echo 'Hello inline version'
          echo $(skipMe) 
          echo $(StageSauce)

Výstup z fází v předchozím zpracování vypadá takto:

Hello inline version
true
crushed tomatoes

Výpis proměnných

Pomocí příkazu az pipelines variable list můžete zobrazit seznam všech proměnných v kanálu. Pokud chcete začít, přečtěte si téma Začínáme s Azure DevOps CLI.

az pipelines variable list [--org]
                           [--pipeline-id]
                           [--pipeline-name]
                           [--project]

Parametry

  • org: Adresa URL organizace Azure DevOps Výchozí organizaci můžete nakonfigurovat pomocí .az devops configure -d organization=ORG_URL Požadováno, pokud není nakonfigurováno jako výchozí nebo pokud není zpracováno pomocí git config. Příklad: --org https://dev.azure.com/MyOrganizationName/.
  • ID kanálu: Vyžaduje se, pokud není zadaný název kanálu. ID potrubí.
  • název kanálu: Vyžaduje se, pokud není zadáno ID kanálu, ale ignoruje se, pokud je zadáno ID kanálu. Název kanálu.
  • projekt: Název nebo ID projektu. Výchozí projekt můžete nakonfigurovat pomocí az devops configure -d project=NAME_OR_ID. Vyžaduje se, pokud není nakonfigurováno jako výchozí nebo získáno pomocí git config.

Příklad

Následující příkaz zobrazí seznam všech proměnných v kanálu s ID 12 a zobrazí výsledek ve formátu tabulky.

az pipelines variable list --pipeline-id 12 --output table

Name           Allow Override    Is Secret    Value
-------------  ----------------  -----------  ------------
MyVariable     False             False        platform
NextVariable   False             True         platform
Configuration  False             False        config.debug

Nastavení proměnných ve skriptech

Skripty mohou definovat proměnné, které se později využívají v následujících krocích potrubí. Všechny proměnné nastavené touto metodou jsou považovány za řetězce. Pokud chcete nastavit proměnnou ze skriptu, použijte syntaxi příkazu a vytiskněte ji na stdout.

Nastavit proměnnou v rámci úlohy ze skriptu

Pokud chcete nastavit proměnnou ze skriptu, použijte task.setvariablepříkaz protokolování. Tím se aktualizují proměnné prostředí pro následné úlohy. Následné úlohy mají přístup k nové proměnné pomocí syntaxí maker a v úkolech jsou jako proměnné prostředí.

Pokud issecret je hodnota true, bude hodnota proměnné uložena jako tajný kód a maskována z protokolu. Další informace o tajných proměnných najdete v tématu příkazy protokolování.

steps:
# Create a variable
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes" # remember to use double quotes

# Use the variable
# "$(sauce)" is replaced by the contents of the `sauce` variable by Azure Pipelines
# before handing the body of the script to the shell.
- bash: |
    echo my pipeline variable is $(sauce)

Následující kroky budou mít také přidanou proměnnou potrubí do jejich prostředí. Proměnnou v kroku, který je definovaný, nemůžete použít.

steps:
# Create a variable
# Note that this does not update the environment of the current script.
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes"

# An environment variable called `SAUCE` has been added to all downstream steps
- bash: |
    echo "my environment variable is $SAUCE"
- pwsh: |
    Write-Host "my environment variable is $env:SAUCE"

Výstup z předchozího potrubí.

my environment variable is crushed tomatoes
my environment variable is crushed tomatoes

Nastavit výstupní proměnnou pro více úloh

Pokud chcete zpřístupnit proměnnou pro budoucí úlohy, musíte ji označit jako výstupní proměnnou pomocí isOutput=true. Pak ho můžete namapovat do budoucích úloh pomocí $[] syntaxe a zahrnutím názvu kroku, který proměnnou nastavil. Výstupní proměnné s více úlohami fungují jenom pro úlohy ve stejné fázi.

Pokud chcete předat proměnné úlohám v různých fázích, použijte syntaxi závislostí fází.

Poznámka:

Ve výchozím nastavení každá fáze v pipeline závisí na předchozí fázi v souboru YAML. Každá fáze proto může používat výstupní proměnné z předchozí fáze. Abyste měli přístup k dalším fázím, budete muset upravit graf závislostí. Například pokud fáze 3 vyžaduje proměnnou z fáze 1, budete muset deklarovat explicitní závislost na fázi 1.

Při vytváření výstupní proměnné pro více úloh byste měli přiřadit výraz k proměnné. V tomto YAML $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] je přiřazen k proměnné $(myVarFromJobA).

jobs:
# Set an output variable from job A
- job: A
  pool:
    vmImage: 'windows-latest'
  steps:
  - powershell: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable into job B
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobA: $[ dependencies.A.outputs['setvarStep.myOutputVar'] ]  # map in the variable
                                                                          # remember, expressions require single quotes
  steps:
  - script: echo $(myVarFromJobA)
    name: echovar

Výstup z předchozího potrubí.

this is the value
this is the value

Pokud nastavujete proměnnou z jedné fáze na jinou, použijte stageDependencies.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=myStageOutputVar;isOutput=true]this is a stage output var"
       name: printvar

- stage: B
  dependsOn: A
  variables:
    myVarfromStageA: $[ stageDependencies.A.A1.outputs['printvar.myStageOutputVar'] ]
  jobs:
  - job: B1
    steps:
    - script: echo $(myVarfromStageA)

Pokud nastavujete proměnnou z matice nebo řezu, pak chcete odkazovat na proměnnou při přístupu z podřízené úlohy, musíte zahrnout:

  • Název úlohy.
  • Ten krok.
jobs:

# Set an output variable from a job with a matrix
- job: A
  pool:
    vmImage: 'ubuntu-latest'
  strategy:
    maxParallel: 2
    matrix:
      debugJob:
        configuration: debug
        platform: x64
      releaseJob:
        configuration: release
        platform: x64
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the $(configuration) value"
    name: setvarStep
  - bash: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the debug job
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobADebug: $[ dependencies.A.outputs['debugJob.setvarStep.myOutputVar'] ]
  steps:
  - script: echo $(myVarFromJobADebug)
    name: echovar

jobs:

# Set an output variable from a job with slicing
- job: A
  pool:
    vmImage: 'ubuntu-latest'
    parallel: 2 # Two slices
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the slice $(system.jobPositionInPhase) value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ]
  steps:
  - script: "echo $(myVarFromJobsA1)"
    name: echovar

Nezapomeňte přidat název úlohy jako předponu k výstupním proměnným úlohy nasazení. V tomto případě je Anázev úlohy:

jobs:

# Set an output variable from a deployment
- deployment: A
  pool:
    vmImage: 'ubuntu-latest'
  environment: staging
  strategy:
    runOnce:
      deploy:
        steps:
        - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the deployment variable value"
          name: setvarStep
        - bash: echo $(setvarStep.myOutputVar)
          name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromDeploymentJob: $[ dependencies.A.outputs['A.setvarStep.myOutputVar'] ]
  steps:
  - bash: "echo $(myVarFromDeploymentJob)"
    name: echovar

Nastavení proměnných pomocí výrazů

Proměnnou můžete nastavit pomocí výrazu. Už jsme narazili na jeden případ, kdy jsme nastavili proměnnou na základě výstupu jiné z dřívější úlohy.

- job: B
  dependsOn: A
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ] # remember to use single quotes

Pro nastavení proměnné můžete použít libovolný z podporovaných výrazů. Tady je příklad nastavení proměnné tak, aby fungovala jako čítač, který začíná na 100, se pro každé spuštění zvýší o 1 a každý den se resetuje na 100.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Další informace o čítačích, závislostech a dalších výrazech najdete v tématu výrazy.

Konfigurace nastavených proměnných pro kroky

Můžete definovat settableVariables v rámci kroku nebo určit, že nelze nastavit žádné proměnné.

V tomto příkladu nemůže skript nastavit proměnnou.

steps:
- script: echo This is a step
  target:
    settableVariables: none

V tomto příkladu skript umožňuje proměnnou sauce , ale ne proměnnou secretSauce. Na stránce spuštění potrubí se zobrazí upozornění.

Upozornění, že nemůžete nastavit secretSauce 

steps:
  - bash: |
      echo "##vso[task.setvariable variable=Sauce;]crushed tomatoes"
      echo "##vso[task.setvariable variable=secretSauce;]crushed tomatoes with garlic"
    target:
     settableVariables:
      - sauce
    name: SetVars
  - bash: 
      echo "Sauce is $(sauce)"
      echo "secretSauce is $(secretSauce)"
    name: OutputVars

Povolit při čekání ve frontě

Pokud se proměnná zobrazí v variables bloku souboru YAML, její hodnota je pevná a nelze ji přepsat v době fronty. Osvědčeným postupem je definovat proměnné v souboru YAML, ale někdy to nedává smysl. Můžete například chtít definovat tajnou proměnnou, která nebude vystavena ve vašem YAML. Nebo může být potřeba ručně nastavit hodnotu proměnné během spuštění kanálu.

Pro definování hodnoty doby fronty máte dvě možnosti. Můžete definovat proměnnou v uživatelském rozhraní a vybrat možnost Umožnit uživatelům přepsat tuto hodnotu při spuštění tohoto pipeline nebo místo toho můžete použít parametry za běhu. Pokud vaše proměnná není tajemstvím, osvědčeným postupem je použít parametry za běhu.

Pokud chcete nastavit proměnnou v době fronty, přidejte do kanálu novou proměnnou a vyberte možnost přepsání. Hodnotu proměnné mohou změnit pouze uživatelé, kteří mají oprávnění ke konfiguraci sestavení fronty úprav .

Nastavte proměnnou při zpracování fronty.

Pokud chcete povolit nastavení proměnné v době fronty, ujistěte se, že se proměnná také nezobrazuje v variables bloku kanálu nebo úlohy. Pokud definujete proměnnou v bloku proměnných YAML i v uživatelském rozhraní, má hodnota v YAML prioritu.

Pro zvýšení zabezpečení použijte předem definovanou sadu hodnot pro proměnné nastavitelné při zpracování fronty a bezpečné typy, jako jsou logické (boolean) hodnoty a celá čísla. Pro řetězce použijte předdefinovanou sadu hodnot.

Rozšíření proměnných

Když proměnnou se stejným názvem nastavíte v několika oborech, použije se následující priorita (nejvyšší priorita je uvedena jako první).

  1. Proměnná na úrovni úlohy nastavená v souboru YAML
  2. Proměnná na úrovni fáze nastavená v souboru YAML
  3. Proměnná na úrovni kanálu nastavená v souboru YAML
  4. Proměnná nastavená při čekání ve frontě
  5. Proměnná kanálu nastavená v uživatelském rozhraní nastavení kanálu

V následujícím příkladu je stejná proměnná a nastavená na úrovni kanálu a na úrovni úlohy v souboru YAML. Je také nastavena ve skupině proměnných G a jako proměnná v nastavení kanálu v uživatelském rozhraní.

variables:
  a: 'pipeline yaml'

stages:
- stage: one
  displayName: one
  variables:
  - name: a
    value: 'stage yaml'

  jobs:
  - job: A
    variables:
    - name: a
      value: 'job yaml'
    steps:
    - bash: echo $(a)        # This will be 'job yaml'

Když nastavíte proměnnou se stejným názvem ve stejném oboru, bude mít přednost hodnota poslední sady.

stages:
- stage: one
  displayName: Stage One
  variables: 
    - name: a
      value: alpha
    - name: a
      value: beta
  jobs: 
  - job: I
    displayName: Job I
    variables:
      - name: b
        value: uno
      - name: b
        value: dos
    steps: 
    - script: echo $(a) #outputs beta
    - script: echo $(b) #outputs dos

Poznámka:

Když nastavíte proměnnou v souboru YAML, nedefinujte ji ve webovém editoru jako nastavitelnou během času ve frontě. V současné době nemůžete měnit proměnné, které jsou nastavené v souboru YAML při zařazení do fronty. Pokud potřebujete nastavit proměnnou v době fronty, nenastavujte ji v souboru YAML.

Proměnné jsou rozšířeny jednou po spuštění a znovu na začátku každého kroku. Příklad:

jobs:
- job: A
  variables:
    a: 10
  steps:
  - bash: |
      echo $(a)            # This will be 10
      echo '##vso[task.setvariable variable=a]20'
      echo $(a)            # This will also be 10, since the expansion of $(a) happens before the step
  - bash: echo $(a)        # This will be 20, since the variables are expanded just before the step

V předchozím příkladu jsou dva kroky. Rozšíření $(a) se provede jednou na začátku úlohy a jednou na začátku každého ze dvou kroků.

Vzhledem k tomu, že se proměnné rozšiřují na začátku úlohy, nemůžete je použít ve strategii. V následujícím příkladu nemůžete proměnnou a použít k rozbalení matice úlohy, protože proměnná je k dispozici pouze na začátku každé rozšířené úlohy.

jobs:
- job: A
  variables:
    a: 10
  strategy:
    matrix:
      x:
        some_variable: $(a)    # This does not work

Pokud je proměnná a výstupní proměnnou z předchozí úlohy, můžete ji použít v budoucí úloze.

- job: A
  steps:
  - powershell: echo "##vso[task.setvariable variable=a;isOutput=true]10"
    name: a_step

# Map the variable into job B
- job: B
  dependsOn: A
  variables:
    some_variable: $[ dependencies.A.outputs['a_step.a'] ]

Rekurzivní rozšíření

V rámci agenta se proměnné odkazované syntaxí $( ) rekurzivně expandují. Příklad:

variables:
  myInner: someValue
  myOuter: $(myInner)

steps:
- script: echo $(myOuter)  # prints "someValue"
  displayName: Variable is $(myOuter)  # display name is "Variable is someValue"