Contexto de expressão do decorador de pipeline

Artigo
11/09/2024

Serviços de DevOps do Azure

Os decoradores de pipeline têm acesso ao contexto sobre o pipeline em que são executados. Como autor de um decorador de pipeline, você pode usar esse contexto para tomar decisões sobre o comportamento do decorador. As informações disponíveis no contexto são diferentes para pipelines e para liberação. Além disso, os decoradores são executados depois que os nomes das tarefas são resolvidos para identificar identificadores globais exclusivos (GUIDs). Quando o decorador quiser fazer referência a uma tarefa, ele deve usar o GUID em vez do nome ou palavra-chave.

Gorjeta

Confira nossa documentação mais recente sobre desenvolvimento de extensões usando o SDK de Extensão do Azure DevOps.

Nota

Os decoradores de pipeline são usados ao construir extensões da web. Esses exemplos não foram projetados para funcionar em pipelines YAML.

Recursos

Os recursos de pipeline estão disponíveis no resources objeto.

Repositórios

Atualmente, há apenas uma chave: repositories. repositories é um mapa do ID do repositório para informações sobre o repositório.

Em uma compilação de designer, o alias de repositório principal é __designer_repo. Em um pipeline YAML, o repositório primário é chamado selfde . Em um pipeline de versão, os repositórios não estão disponíveis. Variáveis de artefato de liberação estão disponíveis.

Por exemplo, para imprimir o self nome do repositório em um pipeline YAML:

steps:
- script: echo ${{ resources.repositories['self'].name }}

Os repositórios contêm estas propriedades:

resources['repositories']['self'] =
{
	"alias": "self",
	"id": "<repo guid>",
	"type": "Git",
	"version": "<commit hash>",
	"name": "<repo name>",
	"project": "<project guid>",
	"defaultBranch": "<default ref of repo, like 'refs/heads/main'>",
	"ref": "<current pipeline ref, like 'refs/heads/topic'>",
	"versionInfo": {
		"author": "<author of tip commit>",
		"message": "<commit message of tip commit>"
	},
	"checkoutOptions": {}
}

Tarefa

Os detalhes do job trabalho estão disponíveis no objeto.

Os dados são semelhantes a:

job = 
{
	"steps": [
		{
			"environment": null,
			"inputs": {
				"script": "echo hi"
			},
			"type": "Task",
			"task": {
				"id": "d9bafed4-0b18-4f58-968d-86655b4d2ce9",
				"name": "CmdLine",
				"version": "2.146.1"
			},
			"condition": null,
			"continueOnError": false,
			"timeoutInMinutes": 0,
			"id": "5c09f0b5-9bc3-401f-8cfb-09c716403f48",
			"name": "CmdLine",
			"displayName": "CmdLine",
			"enabled": true
		}
	]
}

Por exemplo, para adicionar condicionalmente uma tarefa somente se ela ainda não existir:

- ${{ if not(containsValue(job.steps.*.task.id, 'f3ab91e7-bed6-436a-b651-399a66fe6c2a')) }}:
  - script: echo conditionally inserted

Variáveis

Variáveis de pipeline também estão disponíveis.

Por exemplo, se o pipeline tivesse uma variável chamada myVar, seu valor estaria disponível para o decorador como variables['myVar'].

Por exemplo, para dar a um decorador um opt-out, podemos procurar uma variável. Os autores de pipeline que desejam optar por sair do decorador podem definir essa variável, e o decorador não é injetado. Se a variável não estiver presente, o decorador é injetado como de costume.

my-decorator.yml

- ${{ if ne(variables['skipInjecting'], 'true') }}:
  - script: echo Injected the decorator

Então, em um pipeline na organização, o autor pode solicitar ao decorador para não se injetar.

pipeline-with-opt-out.yml

variables:
  skipInjecting: true
steps:
- script: echo This is the only step. No decorator is added.

Nomes de tarefas e GUIDs

Os decoradores correm atrás de tarefas já transformadas em GUIDs. Considere o seguinte YAML:

steps:
- checkout: self
- bash: echo This is the Bash task
- task: PowerShell@2
  inputs:
    targetType: inline
    script: Write-Host This is the PowerShell task

Cada uma dessas etapas é mapeada para uma tarefa. Cada tarefa tem um GUID exclusivo. Nomes de tarefas e palavras-chave são mapeados para GUIDs de tarefas antes que os decoradores sejam executados. Se um decorador quiser verificar a existência de outra tarefa, ele deve pesquisar por GUID da tarefa em vez de por nome ou palavra-chave.

Para tarefas normais (que você especifica com a palavra-chave task ), você pode examinar o GUID da task.json tarefa para determinar seu GUID. Para palavras-chave especiais como checkout e bash no exemplo anterior, você pode usar os seguintes GUIDs:

Palavra-chave	GUID	Nome da Tarefa
`checkout`	`6D15AF64-176C-496D-B583-FD2AE21D4DF4`	n/d, ver nota
`bash`	`6C731C3C-3C68-459A-A5C9-BDE6E6595B5B`	Bash
`script`	`D9BAFED4-0B18-4F58-968D-86655B4D2CE9`	CmdLine
`powershell`	`E213FF0F-5D5C-4791-802D-52EA3E7BE1F1`	PowerShell
`pwsh`	`E213FF0F-5D5C-4791-802D-52EA3E7BE1F1`	PowerShell
`publish`	`ECDC45F6-832D-4AD9-B52B-EE49E94659BE`	PublishPipelineArtifact
`download`	`30f35852-3f7e-4c0c-9a88-e127b4f97211`	BaixarPipelineArtifact

Após a resolução de nomes de tarefas e palavras-chave, o YAML anterior torna-se:

steps:
- task: 6D15AF64-176C-496D-B583-FD2AE21D4DF4@1
  inputs:
    repository: self
- task: 6C731C3C-3C68-459A-A5C9-BDE6E6595B5B@3
  inputs:
    targetType: inline
    script: echo This is the Bash task
- task: E213FF0F-5D5C-4791-802D-52EA3E7BE1F1@2
  inputs:
    targetType: inline
    script: Write-Host This is the PowerShell task

Gorjeta

Você pode encontrar cada um task.json desses GUIDs na tarefa da caixa de entrada correspondente. A única exceção é checkout, que é uma capacidade nativa do agente. Seu GUID é incorporado ao serviço e agente do Azure Pipelines.

Partilhar via