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í kanálu dostat klíčová data. Proměnné se nejčastěji používají k definování hodnot, které pak můžete použít v kanálu. 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 kanálech YAML můžete nastavit proměnné na úrovni kořenového adresáře, 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í.

Podřízené komponenty, jako jsou úlohy kanálu, 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 dá se použít k identifikaci různých spuštění kanálu. 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é kanály verze, přečtěte si informace o proměnných verze.

Systémové proměnné se při spuštění kanálu 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. Vloží se do kanálu různými způsoby. 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 %NAME% formát pro dávku a $env:NAME v PowerShellu.

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

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í pojmenování proměnných

Uživatelem definované proměnné prostředí a proměnné prostředí se můžou skládat z písmen, .číslic a _ znaků. Nepoužívejte předpony proměnných rezervované systémem. Toto jsou: endpoint, , secretinput, 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 kanálu se proměnné výrazů šablony (${{ variables.var }}) zpracovávají v době kompilace před spuštěním modulu runtime. Proměnné syntaxe maker ($(var)) se zpracovávají během běhu před spuštěním úlohy. Výrazy modulu runtime ($[variables.var]) se také zpracovávají během běhu, ale mají být použity s podmínkami a výrazy. Pokud používáte běhový výraz, musí zabrat celou pravou stranu definice.

V tomto příkladu vidíte, že výraz šablony má po aktualizaci proměnné počáteční hodnotu proměnné. 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é syntaxe maker se naproti tomu vyhodnocují před spuštěním jednotlivých úloh.

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

Většina příkladů dokumentace používá 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é se syntaxí maker se zpracovávají před spuštěním úlohy 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 se například $(var) nedá nahradit, $(var) nic se nenahradí.

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

Proměnné maker se rozbalí jenom v případě, že se použijí 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, jobsa steps. Například nelze použít syntaxi makra uvnitř nebo resource trigger.

V tomto příkladu se používá syntaxe maker s Bashem, PowerShellem a úlohou skriptu. 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 }}). Proces proměnných šablon v době kompilace a nahrazení před spuštěním modulu runtime. Výrazy šablon jsou navržené pro opakované použití částí YAML jako šablon.

Proměnné šablony se bezobslužně spojí s prázdnými řetězci, 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

Syntaxi výrazu runtime můžete použít pro proměnné, které jsou rozbalené za běhu ($[variables.var]). Proměnné výrazů modulu runtime se bezobslužně spojí s prázdnými řetězci, pokud se nenajde 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 se rozbalí jenom v případě, že se používají pro hodnotu, 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 modulu runtime musí převzít celou pravou stranu páru klíč-hodnota. Je například platný, key: $[variables.value] ale key: $[variables.value] foo není.

Syntaxe Příklad Kdy se zpracovává? Kde se rozbalí v definici kanálu? Jak se vykresluje, když se nenajde?
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] modul runtime 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 runtime. 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 váš kanál plně vloží hodnotu proměnné do kanálu při kompilaci kanálu. To je užitečné při pokusu o ladění kanálů. Můžete stáhnout soubory protokolu a vyhodnotit plně rozbalenou hodnotu, která se nahrazuje. Vzhledem k tomu, že je proměnná nahrazena, neměli byste pro citlivé hodnoty využívat syntaxi šablony.

Nastavení proměnných v kanálu

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 kořenové úrovni ho zpřístupníte pro všechny úlohy v kanálu.
  • Na úrovni fáze ji zpřístupníte pouze pro určitou fázi.
  • Na úrovni úlohy ji zpřístupníte 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řenové a dílčí fáze. Proměnné na úrovni fáze přepíší 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íchpříkladch variables 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 kanálu.

V této alternativní syntaxi variables přebírá klíčové slovo 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é skripty: %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 použít metodu proměnné prostředí pro přístup k těmto proměnným místo metody proměnné kanálu, abyste měli jistotu, že máte správný styl cesty k souboru.

Nastavení tajných proměnných

Tip

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 namapujte proměnnou v variables rámci bloku k předání tajných kódů do kanálu.

Poznámka:

Azure Pipelines se snaží maskovat tajné kódy při generová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 nastavené jako tajné kódy.

V uživatelském rozhraní nastavení kanálu musíte nastavit tajné proměnné. Tyto proměnné jsou vymezeny na kanál, ve kterém jsou nastavené. 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 Zachovat tento tajný kód hodnoty, aby se proměnná ukládal šifrovaným způsobem.
  5. Uložte kanál.

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ě kanálu.

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 neodhalujte tajné kódy jako výstup. Některé argumenty příkazového řádku protokolu operačních systémů. Nikdy nepředávejte tajné kódy na příkazovém řádku. Místo toho doporučujeme namapovat tajné kódy 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é mySecreta GLOBAL_MY_MAPPED_ENV_VAR je přiřazena hodnota proměnné bez tajného nonSecretVariablekódu . Na rozdíl od normální proměnné kanálu neexistuje žádná proměnná prostředí.MYSECRET

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

  • $(mySecret): Toto je přímý odkaz na proměnnou tajného kódu a funguje.
  • $env:MYSECRET: Tento pokus o přístup k tajné proměnné jako proměnné prostředí, která 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: Tato funkce přistupuje k proměnné bez tajného kódu prostřednictvím globální proměnné, která 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. Pomocí definice můžete například mapovat proměnné tajných kódů na úkoly variables . 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)

Referenční proměnné tajných kódů 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 kanálu zpřístupněny pro sestavení forků žádostí o přijetí změn. Další informace naleznete v tématu Příspěvky z forků.

Sdílení proměnných mezi kanály

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í.

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

  • 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 kanálu závisí na jedné fázi těsně před ní 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 kanálu. Pokud používáte kanály nasazení, bude se lišit syntaxe proměnných 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é můžete předat také mezi fázemi se vstupem souboru. 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 kanálu 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 vyzvednuto 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 kanálu.
  • 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 vyzvednuto 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 spotřebovávají v následných krocích v kanálu. 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.

Nastavení proměnné s oborem úlohy ze skriptu

Pokud chcete nastavit proměnnou ze skriptu, použijte task.setvariable pří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é se syntaxí maker a v úkolech jako proměnných 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)

Další kroky budou mít také přidanou proměnnou kanálu do svého 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 kanálu.

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

Nastavení výstupní proměnné s více úlohami

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 kanálu závisí na jedné fázi těsně před ní v souboru YAML. Každá fáze proto může používat výstupní proměnné z předchozí fáze. Pokud například fáze 3 vyžaduje proměnnou z fáze 1, budete muset upravit graf závislostí.

Při vytváření výstupní proměnné s více úlohami byste měli přiřadit výraz 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 kanálu.

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.
  • 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 název úlohy předponovat 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 výstup jiné z předchozí ú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í kanálu 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

Povolení nastavení 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 dává smysl. Můžete například chtít definovat tajnou proměnnou, která nemá v YAML vystavenou proměnnou. Nebo může být potřeba ručně nastavit hodnotu proměnné během spuštění kanálu.

Pro definování hodnot fronty a času 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 kanálu nebo místo toho můžete použít parametry modulu runtime. Pokud proměnná není tajným kódem, osvědčeným postupem je použít parametry modulu runtime.

Pokud chcete nastavit proměnnou v době fronty, přidejte do kanálu novou proměnnou a vyberte možnost přepsání.

Nastavte proměnnou v době 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.

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ě Gproměnných a jako proměnná v uživatelském rozhraní nastavení kanálu.

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 nastavenou v době fronty. V současné době nemůžete měnit proměnné, které jsou nastavené v souboru YAML v době fronty. Pokud potřebujete nastavit proměnnou v době fronty, nenastavujte ji v souboru YAML.

Proměnné se po spuštění rozbalí jednou 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 agentu se proměnné odkazované pomocí $( ) syntaxe rekurzivně rozbalí. Příklad:

variables:
  myInner: someValue
  myOuter: $(myInner)

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