ACR 任务参考:YAMLACR Tasks reference: YAML

ACR 任务中的多步骤任务定义提供注重于生成、测试和修补容器的,以容器为中心的计算基元。Multi-step task definition in ACR Tasks provides a container-centric compute primitive focused on building, testing, and patching containers. 本文介绍用于定义多步骤任务的 YAML 文件的命令、参数、属性和语法。This article covers the commands, parameters, properties, and syntax for the YAML files that define your multi-step tasks.

本文包含有关为 ACR 任务创建多步骤任务 YAML 文件的参考信息。This article contains reference for creating multi-step task YAML files for ACR Tasks. 如需 ACR 任务的简介,请参阅 ACR 任务概述If you'd like an introduction to ACR Tasks, see the ACR Tasks overview.

acr-task.yaml 文件格式acr-task.yaml file format

ACR 任务支持采用标准 YAML 语法的多步骤任务声明。ACR Tasks supports multi-step task declaration in standard YAML syntax. 在 YAML 文件中定义任务的步骤。You define a task's steps in a YAML file. 然后,可以通过将该文件传递到 az acr run 命令来手动运行该任务。You can then run the task manually by passing the file to the az acr run command. 或者,运行 az acr task create 命令并使用该文件创建一个任务,每次执行 Git 提交或基础映像更新时,会自动触发该任务。Or, use the file to create a task with az acr task create that's triggered automatically on a Git commit or base image update. 尽管本文将 acr-task.yaml 称作包含步骤的文件,但 ACR 任务支持带有受支持扩展名的任何有效文件名。Although this article refers to acr-task.yaml as the file containing the steps, ACR Tasks supports any valid filename with a supported extension.

顶级 acr-task.yaml 基元为任务属性步骤类型步骤属性The top-level acr-task.yaml primitives are task properties, step types, and step properties:

  • 任务属性应用到整个任务执行中的所有步骤。Task properties apply to all steps throughout task execution. 有几个全局任务属性,包括:There are several global task properties, including:
    • version
    • stepTimeout
    • workingDirectory
  • 任务步骤类型表示可在任务中执行的操作类型。Task step types represent the types of actions that can be performed in a task. 有三个步骤类型:There are three step types:
    • build
    • push
    • cmd
  • 任务步骤属性是应用到单个步骤的参数。Task step properties are parameters that apply to an individual step. 有多个步骤属性,其中包括:There are several step properties, including:
    • startDelay
    • timeout
    • when
    • ...等等。...and many more.

acr-task.yaml 文件的基本格式(包括一些通用步骤属性)如下。The base format of an acr-task.yaml file, including some common step properties, follows. 尽管本文并未提供所有可用步骤属性或步骤类型用法的详尽表述,但提供了基本文件格式的简要概述。While not an exhaustive representation of all available step properties or step type usage, it provides a quick overview of the basic file format.

version: # acr-task.yaml format version.
stepTimeout: # Seconds each step may take.
steps: # A collection of image or container actions.
  - build: # Equivalent to "docker build," but in a multi-tenant environment
  - push: # Push a newly built or retagged image to a registry.
    when: # Step property that defines either parallel or dependent step execution.
  - cmd: # Executes a container, supports specifying an [ENTRYPOINT] and parameters.
    startDelay: # Step property that specifies the number of seconds to wait before starting execution.

支持的任务文件扩展名Supported task filename extensions

ACR 任务具有多个保留的文件扩展名(包括 .yaml),它将这些文件作为任务文件进行处理。ACR Tasks has reserved several filename extensions, including .yaml, that it will process as a task file. ACR 任务将以下列表中未列出的任何扩展名视为 Dockerfile:.yaml、.yml、.toml、.json、.sh、.bash、.zsh、.ps1、.ps、.cmd、.bat、.ts、.js、.php、.py、.rb、.lua Any extension not in the following list is considered by ACR Tasks to be a Dockerfile: .yaml, .yml, .toml, .json, .sh, .bash, .zsh, .ps1, .ps, .cmd, .bat, .ts, .js, .php, .py, .rb, .lua

YAML 是 ACR 任务目前支持的唯一一种文件格式。YAML is the only file format currently supported by ACR Tasks. 其他文件扩展名是保留的,将来可能受到支持。The other filename extensions are reserved for possible future support.

运行示例任务Run the sample tasks

本文的后续部分参考了多个示例任务文件。There are several sample task files referenced in the following sections of this article. 这些示例任务在公共 GitHub 存储库 Azure-Samples/acr-tasks 中提供。The sample tasks are in a public GitHub repository, Azure-Samples/acr-tasks. 可以使用 Azure CLI 命令 az acr run 运行这些任务。You can run them with the Azure CLI command az acr run. 示例命令如下所示:The sample commands are similar to:

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

示例命令的格式假设已在 Azure CLI 中配置了默认注册表,因此省略了 --registry 参数。The formatting of the sample commands assumes you've configured a default registry in the Azure CLI, so they omit the --registry parameter. 若要配置默认注册表,请结合 --defaults 参数(接受 acr=REGISTRY_NAME 值)使用 az configure 命令。To configure a default registry, use the az configure command with the --defaults parameter, which accepts an acr=REGISTRY_NAME value.

例如,若要在 Azure CLI 中配置名为“myregistry”的默认注册表:For example, to configure the Azure CLI with a default registry named "myregistry":

az configure --defaults acr=myregistry

任务属性Task properties

任务属性通常显示在 acr-task.yaml 文件的顶部,是在整个任务步骤执行中应用的全局属性。Task properties typically appear at the top of an acr-task.yaml file, and are global properties that apply throughout the full execution of the task steps. 其中的某些全局属性可在单个步骤中重写。Some of these global properties can be overridden within an individual step.

属性Property 类型Type 可选Optional 说明Description 支持的重写Override supported 默认值Default value
version stringstring Yes ACR 任务服务分析的 acr-task.yaml 文件的版本。The version of the acr-task.yaml file as parsed by the ACR Tasks service. ACR 任务致力于保持向后兼容性,而此值能使 ACR 任务与某个定义的版本保持兼容。While ACR Tasks strives to maintain backward compatibility, this value allows ACR Tasks to maintain compatibility within a defined version. 如果未指定,则默认为最新版本。If unspecified, defaults to the latest version. No None
stepTimeout 整数(秒)int (seconds) Yes 步骤可以运行的最大秒数。The maximum number of seconds a step can run. 如果在任务中指定该属性,则会设置所有步骤的默认 timeout 属性。If the property is specified on a task, it sets the default timeout property of all the steps. 如果在步骤中指定 timeout 属性,则会替代任务提供的属性。If the timeout property is specified on a step, it overrides the property provided by the task. Yes 600(10 分钟)600 (10 minutes)
workingDirectory stringstring Yes 运行时期间容器的工作目录。The working directory of the container during runtime. 如果在任务中指定该属性,则会设置所有步骤的默认 workingDirectory 属性。If the property is specified on a task, it sets the default workingDirectory property of all the steps. 如果在步骤中指定,则会替代任务提供的属性。If specified on a step, it overrides the property provided by the task. Yes $HOME
env [字符串, 字符串, ...][string, string, ...] Yes 采用 key=value 格式的字符串数组,定义任务的环境变量。Array of strings in key=value format that define the environment variables for the task. 如果在任务中指定该属性,则会设置所有步骤的默认 env 属性。If the property is specified on a task, it sets the default env property of all the steps. 如果在步骤中指定,则会替代从任务继承的所有环境变量。If specified on a step, it overrides any environment variables inherited from the task. None
secrets [secret, secret, ...][secret, secret, ...] Yes secret 对象的数组。Array of secret objects. None
networks [network, network, ...][network, network, ...] Yes network 对象的数组。Array of network objects. None

secretsecret

secret 对象具有以下属性。The secret object has the following properties.

属性Property 类型Type 可选Optional 说明Description 默认值Default value
id stringstring No 机密的标识符。The identifier of the secret. None
keyvault stringstring Yes Azure Key Vault 机密 URL。The Azure Key Vault Secret URL. None
clientID stringstring Yes Azure 资源的用户分配的托管标识的客户端 ID。The client ID of the user-assigned managed identity for Azure resources. None

网络network

network 对象具有以下属性。The network object has the following properties.

属性Property 类型Type 可选Optional 说明Description 默认值Default value
name stringstring No 网络的名称。The name of the network. None
driver stringstring Yes 用于管理网络的驱动程序。The driver to manage the network. None
ipv6 boolbool Yes IPv6 网络是否已启用。Whether IPv6 networking is enabled. false
skipCreation boolbool Yes 是否跳过网络创建过程。Whether to skip network creation. false
isDefault boolbool Yes 该网络是否是随 Azure 容器注册表一起提供的默认网络Whether the network is a default network provided with Azure Container Registry false

步骤任务类型Task step types

ACR 任务支持三种步骤类型。ACR Tasks supports three step types. 每种步骤类型支持多个属性,每个步骤类型的相关部分中会予以详述。Each step type supports several properties, detailed in the section for each step type.

步骤类型Step type 说明Description
build 使用熟悉的 docker build 语法生成容器映像。Builds a container image using familiar docker build syntax.
push 执行 docker push,将新生成或重新标记的映像推送到容器注册表。Executes a docker push of newly built or retagged images to a container registry. 支持 Azure 容器注册表、其他专用注册表和公共 Docker 中心。Azure Container Registry, other private registries, and the public Docker Hub are supported.
cmd 结合传递给容器的 [ENTRYPOINT] 的参数,以命令形式运行容器。Runs a container as a command, with parameters passed to the container's [ENTRYPOINT]. cmd 步骤类型支持 envdetach 等参数和其他常见的 docker run 命令选项,可对并发容器执行启用单元测试和功能测试。The cmd step type supports parameters like env, detach, and other familiar docker run command options, enabling unit and functional testing with concurrent container execution.

buildbuild

生成容器映像。Build a container image. build 步骤类型表示在云中以多租户的安全方式将 docker build 作为第一类基元运行。The build step type represents a multi-tenant, secure means of running docker build in the cloud as a first-class primitive.

语法:buildSyntax: build

version: v1.0.0
steps:
  - [build]: -t [imageName]:[tag] -f [Dockerfile] [context]
    [property]: [value]

build 步骤类型支持下表中的参数。The build step type supports the parameters in the following table. build 步骤类型还支持 docker build 命令的所有生成选项,例如 --build-arg 以设置生成时变量。The build step type also supports all build options of the docker build command, such as --build-arg to set build-time variables.

参数Parameter 说明Description 可选Optional
-t | --image-t | --image 定义所生成的映像的完全限定 image:tagDefines the fully qualified image:tag of the built image.

由于映像可用于内部任务验证(例如功能测试),并非所有映像都需要通过 push 推送到注册表。As images may be used for inner task validations, such as functional tests, not all images require push to a registry. 但是,若要实例化任务执行中的某个映像,该映像确实需要引用某个名称。However, to instance an image within a Task execution, the image does need a name to reference.

az acr build 不同,正在运行的 ACR 任务不提供默认的推送行为。Unlike az acr build, running ACR Tasks doesn't provide default push behavior. 使用 ACR 任务时,默认方案假设能够生成、验证再推送映像。With ACR Tasks, the default scenario assumes the ability to build, validate, then push an image. 请参阅 push,了解如何选择性地推送所生成的映像。See push for how to optionally push built images.
Yes
-f | --file-f | --file 指定要传递给 docker build 的 Dockerfile。Specifies the Dockerfile passed to docker build. 如果未指定,则假设使用上下文根目录中的默认 Dockerfile。If not specified, the default Dockerfile in the root of the context is assumed. 若要指定 Dockerfile,请传递相对于上下文根目录的文件名。To specify a Dockerfile, pass the filename relative to the root of the context. Yes
context 传递给 docker build 的根目录。The root directory passed to docker build. 每个任务的根目录设置为某个共享的 workingDirectory,包括关联的 Git 克隆目录所在的根目录。The root directory of each task is set to a shared workingDirectory, and includes the root of the associated Git cloned directory. No

属性:buildProperties: build

build 步骤类型支持以下属性。The build step type supports the following properties. 可在本文的任务步骤属性部分找到这些属性的详细信息。Find details of these properties in the Task step properties section of this article.

detach boolbool 可选Optional
disableWorkingDirectoryOverride boolbool 可选Optional
entryPoint stringstring 可选Optional
env [字符串, 字符串, ...][string, string, ...] 可选Optional
expose [字符串, 字符串, ...][string, string, ...] 可选Optional
id stringstring 可选Optional
ignoreErrors boolbool 可选Optional
isolation stringstring 可选Optional
keep boolbool 可选Optional
network objectobject 可选Optional
ports [字符串, 字符串, ...][string, string, ...] 可选Optional
pull boolbool 可选Optional
repeat intint 可选Optional
retries intint 可选Optional
retryDelay 整数(秒)int (seconds) 可选Optional
secret objectobject 可选Optional
startDelay 整数(秒)int (seconds) 可选Optional
timeout 整数(秒)int (seconds) 可选Optional
when [字符串, 字符串, ...][string, string, ...] 可选Optional
workingDirectory stringstring 可选Optional

示例:buildExamples: build

生成映像 - 根目录中的上下文Build image - context in root

az acr run -f build-hello-world.yaml https://github.com/AzureCR/acr-tasks-sample.git
version: v1.0.0
steps:
  - build: -t {{.Run.Registry}}/hello-world -f hello-world.dockerfile .

生成映像 - 子目录中的上下文Build image - context in subdirectory

version: v1.0.0
steps:
  - build: -t {{.Run.Registry}}/hello-world -f hello-world.dockerfile ./subDirectory

pushpush

将生成或重新标记的一个或多个映像推送到容器注册表。Push one or more built or retagged images to a container registry. 支持推送到 Azure 容器注册表等专用注册表,或推送到公共 Docker 中心。Supports pushing to private registries like Azure Container Registry, or to the public Docker Hub.

语法:pushSyntax: push

push 步骤类型支持映像集合。The push step type supports a collection of images. YAML 集合语法支持内联和嵌套格式。YAML collection syntax supports inline and nested formats. 推送单个映像的操作通常使用内联语法来表示:Pushing a single image is typically represented using inline syntax:

version: v1.0.0
steps:
  # Inline YAML collection syntax
  - push: ["{{.Run.Registry}}/hello-world:{{.Run.ID}}"]

为方便阅读,请在推送多个映像时使用嵌套语法:For increased readability, use nested syntax when pushing multiple images:

version: v1.0.0
steps:
  # Nested YAML collection syntax
  - push:
    - {{.Run.Registry}}/hello-world:{{.Run.ID}}
    - {{.Run.Registry}}/hello-world:latest

属性:pushProperties: push

push 步骤类型支持以下属性。The push step type supports the following properties. 可在本文的任务步骤属性部分找到这些属性的详细信息。Find details of these properties in the Task step properties section of this article.

env [字符串, 字符串, ...][string, string, ...] 可选Optional
id stringstring 可选Optional
ignoreErrors boolbool 可选Optional
startDelay 整数(秒)int (seconds) 可选Optional
timeout 整数(秒)int (seconds) 可选Optional
when [字符串, 字符串, ...][string, string, ...] 可选Optional

示例:pushExamples: push

推送多个映像Push multiple images

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  - build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f hello-world.dockerfile .
  - push: ["{{.Run.Registry}}/hello-world:{{.Run.ID}}"]

生成、推送和运行Build, push, and run

az acr run -f build-run-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  - build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f hello-world.dockerfile .
  - push:
    - {{.Run.Registry}}/hello-world:{{.Run.ID}}
  - cmd: {{.Run.Registry}}/hello-world:{{.Run.ID}}

cmdcmd

cmd 步骤类型运行容器。The cmd step type runs a container.

语法:cmdSyntax: cmd

version: v1.0.0
steps:
  - [cmd]: [containerImage]:[tag (optional)] [cmdParameters to the image]

属性:cmdProperties: cmd

cmd 步骤类型支持以下属性:The cmd step type supports the following properties:

detach boolbool 可选Optional
disableWorkingDirectoryOverride boolbool 可选Optional
entryPoint stringstring 可选Optional
env [字符串, 字符串, ...][string, string, ...] 可选Optional
expose [字符串, 字符串, ...][string, string, ...] 可选Optional
id stringstring 可选Optional
ignoreErrors boolbool 可选Optional
isolation stringstring 可选Optional
keep boolbool 可选Optional
network objectobject 可选Optional
ports [字符串, 字符串, ...][string, string, ...] 可选Optional
pull boolbool 可选Optional
repeat intint 可选Optional
retries intint 可选Optional
retryDelay 整数(秒)int (seconds) 可选Optional
secret objectobject 可选Optional
startDelay 整数(秒)int (seconds) 可选Optional
timeout 整数(秒)int (seconds) 可选Optional
when [字符串, 字符串, ...][string, string, ...] 可选Optional
workingDirectory stringstring 可选Optional

可在本文的任务步骤属性部分找到这些属性的详细信息。You can find details of these properties in the Task step properties section of this article.

示例:cmdExamples: cmd

运行 hello-world 映像Run hello-world image

此命令执行 hello-world.yaml 任务文件,此文件引用 Docker 中心内的 hello-world 映像。This command executes the hello-world.yaml task file, which references the hello-world image on Docker Hub.

az acr run -f hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  - cmd: hello-world

运行 bash 映像并回显“hello world”Run bash image and echo "hello world"

此命令执行 bash-echo.yaml 任务文件,此文件引用 Docker 中心内的 bash 映像。This command executes the bash-echo.yaml task file, which references the bash image on Docker Hub.

az acr run -f bash-echo.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  - cmd: bash echo hello world

运行特定的 bash 映像标记Run specific bash image tag

若要运行特定的映像版本,请在 cmd 中指定标记。To run a specific image version, specify the tag in the cmd.

此命令执行 bash-echo-3.yaml 任务文件,此文件引用 Docker 中心内的 bash:3.0 映像。This command executes the bash-echo-3.yaml task file, which references the bash:3.0 image on Docker Hub.

az acr run -f bash-echo-3.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  - cmd: bash:3.0 echo hello world

运行自定义映像Run custom images

cmd 步骤类型使用标准的 docker run 格式引用映像。The cmd step type references images using the standard docker run format. 不是以注册表名称开头的映像被认为源自 dockerhub.azk8s.cn。Images not prefaced with a registry are assumed to originate from dockerhub.azk8s.cn. 下面是前一示例的同等表示形式:The previous example could equally be represented as:

version: v1.0.0
steps:
  - cmd: dockerhub.azk8s.cn/bash:3.0 echo hello world

使用标准的 docker run 映像引用约定,cmd 可以运行任何专用注册表或公共 Docker Hub 中的映像。By using the standard docker run image reference convention, cmd can run images from any private registry or the public Docker Hub. 如果引用执行 ACR 任务的同一注册表中的映像,则无需指定任何注册表凭据。If you're referencing images in the same registry in which ACR Task is executing, you don't need to specify any registry credentials.

  • 运行 Azure 容器注册表中的映像Run an image that's from an Azure container registry

    [myregistry] 替换为注册表的名称:Replace [myregistry] with the name of your registry:

    version: v1.0.0
    steps:
        - cmd: [myregistry].azurecr.cn/bash:3.0 echo hello world
    
  • 使用 Run 变量通用化注册表引用Generalize the registry reference with a Run variable

    不要在 acr-task.yaml 文件中将注册表名称硬编码,可以使用 Run 变量来提高此名称的可移植性。Instead of hard-coding your registry name in an acr-task.yaml file, you can make it more portable by using a Run variable. 在运行时,Run.Registry 变量将扩展到执行任务的注册表的名称。The Run.Registry variable expands at runtime to the name of the registry in which the task is executing.

    若要通用化上述任务,使其可在任何 Azure 容器注册表中运行,请在映像名称中引用 Run.Registry 变量:To generalize the preceding task so that it works in any Azure container registry, reference the Run.Registry variable in the image name:

    version: v1.0.0
    steps:
      - cmd: {{.Run.Registry}}/bash:3.0 echo hello world
    

任务步骤属性Task step properties

每个步骤类型支持适用于其类型的多个属性。Each step type supports several properties appropriate for its type. 下表定义了所有可用的步骤属性。The following table defines all of the available step properties. 并非所有步骤类型都支持所有属性。Not all step types support all properties. 若要查看其中的哪些属性可用于每个步骤类型,请参阅 cmdbuildpush 步骤类型参考部分。To see which of these properties are available for each step type, see the cmd, build, and push step type reference sections.

属性Property 类型Type 可选Optional 说明Description 默认值Default value
detach boolbool Yes 在运行时是否应分离容器。Whether the container should be detached when running. false
disableWorkingDirectoryOverride boolbool Yes 是否禁用 workingDirectory 重写功能。Whether to disable workingDirectory override functionality. 将此属性与 workingDirectory 结合使用可以全面控制容器的工作目录。Use this in combination with workingDirectory to have complete control over the container's working directory. false
entryPoint stringstring Yes 重写步骤容器的 [ENTRYPOINT]Overrides the [ENTRYPOINT] of a step's container. None
env [字符串, 字符串, ...][string, string, ...] Yes 采用 key=value 格式的字符串数组,定义步骤的环境变量。Array of strings in key=value format that define the environment variables for the step. None
expose [字符串, 字符串, ...][string, string, ...] Yes 从容器公开的端口的数组。Array of ports that are exposed from the container. None
id stringstring Yes 唯一标识任务中的步骤。Uniquely identifies the step within the task. 任务中的其他步骤可以引用步骤的 id,例如,使用 when 执行依赖项检查。Other steps in the task can reference a step's id, such as for dependency checking with when.

id 也是正在运行的容器的名称。The id is also the running container's name. 例如,在任务的其他容器中运行的进程可以引用 id 作为其 DNS 主机名,或者通过 Docker 日志 [id] 来访问该步骤。Processes running in other containers in the task can refer to the id as its DNS host name, or for accessing it with docker logs [id], for example.
acb_step_%d,其中,%d 是 YAML 文件中的步骤的从 0 开始的索引(按从上到下的顺序排列)。acb_step_%d, where %d is the 0-based index of the step top-down in the YAML file
ignoreErrors boolbool Yes 是否将步骤标记为成功(无论容器执行过程中是否发生了错误)。Whether to mark the step as successful regardless of whether an error occurred during container execution. false
isolation stringstring Yes 容器的隔离级别。The isolation level of the container. default
keep boolbool Yes 执行后是否应保留该步骤的容器。Whether the step's container should be kept after execution. false
network objectobject Yes 标识运行容器的网络。Identifies a network in which the container runs. None
ports [字符串, 字符串, ...][string, string, ...] Yes 从容器发布到主机的端口的数组。Array of ports that are published from the container to the host. None
pull boolbool Yes 在执行容器之前是否强制提取容器以防止任何缓存行为。Whether to force a pull of the container before executing it to prevent any caching behavior. false
privileged boolbool Yes 是否在特权模式下运行容器。Whether to run the container in privileged mode. false
repeat intint Yes 尝试重复执行容器的次数。The number of retries to repeat the execution of a container. 00
retries intint Yes 容器执行失败时的重试次数。The number of retries to attempt if a container fails its execution. 仅当容器的退出代码非零时才重试。A retry is only attempted if a container's exit code is non-zero. 00
retryDelay 整数(秒)int (seconds) Yes 重试容器执行的间隔延迟(以秒为单位)。The delay in seconds between retries of a container's execution. 00
secret objectobject Yes 标识 Azure Key Vault 机密或 Azure 资源的托管标识Identifies an Azure Key Vault secret or managed identity for Azure resources. None
startDelay 整数(秒)int (seconds) Yes 将容器执行延迟的秒数。Number of seconds to delay a container's execution. 00
timeout 整数(秒)int (seconds) Yes 步骤在终止之前可以执行的最大秒数。Maximum number of seconds a step may execute before being terminated. 600600
when [字符串, 字符串, ...][string, string, ...] Yes 配置某个步骤对任务中其他一个或多个步骤的依赖。Configures a step's dependency on one or more other steps within the task. None
user stringstring Yes 容器的用户名或 UIDThe user name or UID of a container None
workingDirectory stringstring Yes 设置步骤的工作目录。Sets the working directory for a step. 默认情况下,ACR 任务会创建一个根目录作为工作目录。By default, ACR Tasks creates a root directory as the working directory. 但是,如果生成包含多个步骤,则前面的步骤可以通过指定相同的工作目录,来与后面的步骤共享项目。However, if your build has several steps, earlier steps can share artifacts with later steps by specifying the same working directory. $HOME

示例:任务步骤属性Examples: Task step properties

示例:idExample: id

生成两个映像,并实例化功能测试映像。Build two images, instancing a functional test image. 每个步骤由任务中的其他步骤在其 when 属性中引用的唯一 id 进行标识。Each step is identified by a unique id which other steps in the task reference in their when property.

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: {{.Run.Registry}}/hello-world:{{.Run.ID}}
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["{{.Run.Registry}}/hello-world:{{.Run.ID}}"]
    when: ["func-tests"]

示例:whenExample: when

when 属性指定某个步骤对任务中其他一个或多个步骤的依赖。The when property specifies a step's dependency on other steps within the task. 它支持两个参数值:It supports two parameter values:

  • when: ["-"] - 指示不依赖于其他步骤。when: ["-"] - Indicates no dependency on other steps. 指定 when: ["-"] 的步骤将立即执行,并启用并发步骤执行。A step specifying when: ["-"] will begin execution immediately, and enables concurrent step execution.
  • when: ["id1", "id2"] - 指示该步骤依赖于使用 id“id1”和 id“id2”的步骤。when: ["id1", "id2"] - Indicates the step is dependent upon steps with id "id1" and id "id2". 在“id1”和“id2”步骤完成之前,此步骤不会执行。This step won't be executed until both "id1" and "id2" steps complete.

如果未在某个步骤中指定 when,则该步骤依赖于 acr-task.yaml 文件中上一个步骤的完成。If when isn't specified in a step, that step is dependent on completion of the previous step in the acr-task.yaml file.

在不指定 when 的情况下按顺序执行步骤:Sequential step execution without when:

az acr run -f when-sequential-default.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
    - cmd: bash echo one
    - cmd: bash echo two
    - cmd: bash echo three

在指定 when 的情况下按顺序执行步骤:Sequential step execution with when:

az acr run -f when-sequential-id.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
    - id: step1
      cmd: bash echo one
    - id: step2
      cmd: bash echo two
      when: ["step1"]
    - id: step3
      cmd: bash echo three
      when: ["step2"]

并行映像生成:Parallel images build:

az acr run -f when-parallel.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]

并行映像生成和依赖测试:Parallel image build and dependent testing:

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.0.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: {{.Run.Registry}}/hello-world:{{.Run.ID}}
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["{{.Run.Registry}}/hello-world:{{.Run.ID}}"]
    when: ["func-tests"]

Run 变量Run variables

ACR 任务包含一组在执行时可供任务步骤使用的默认变量。ACR Tasks includes a default set of variables that are available to task steps when they execute. 可以使用 {{.Run.VariableName}} 格式访问这些变量,其中,VariableName 是以下值之一:These variables can be accessed by using the format {{.Run.VariableName}}, where VariableName is one of the following:

  • Run.ID
  • Run.Registry
  • Run.Date
  • Run.Commit
  • Run.Branch

Run.IDRun.ID

通过 az acr run 执行的,或者使用基于触发器的执行任务通过 az acr task create 创建的每个运行都有唯一的 ID。Each Run, through az acr run, or trigger based execution of tasks created through az acr task create have a unique ID. 此 ID 表示当前正在执行的运行。The ID represents the Run currently being executed.

通常用于唯一标记某个映像:Typically used for a uniquely tagging an image:

version: v1.0.0
steps:
    - build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} .

Run.RegistryRun.Registry

注册表的完全限定服务器名称。The fully qualified server name of the registry. 通常用于泛式引用正在运行任务的注册表。Typically used to generically reference the registry where the task is being run.

version: v1.0.0
steps:
  - build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} .

Run.DateRun.Date

运行开始时的当前 UTC 时间。The current UTC time the run began.

Run.CommitRun.Commit

对于提交到 GitHub 存储库后触发的任务,值为提交标识符。For a task triggered by a commit to a GitHub repository, the commit identifier.

Run.BranchRun.Branch

对于提交到 GitHub 存储库后触发的任务,值为分支名称。For a task triggered by a commit to a GitHub repository, the branch name.

后续步骤Next steps

有关多步骤任务的概述,请参阅在 ACR 任务中运行多步骤生成、测试和修补任务For an overview of multi-step tasks, see the Run multi-step build, test, and patch tasks in ACR Tasks.

有关单步骤生成,请参阅 ACR 任务概述For single-step builds, see the ACR Tasks overview.