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 工作」保留了數個將視為工作檔案來處理的副檔名,包括 .yamlACR 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、.luaAny 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 範例/acr 作業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. 若要設定預設登錄,請使用az configure命令搭配 --defaults 參數,它會接受 acr=REGISTRY_NAME 值。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 字串string yesYes 「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) yesYes 步驟的可執行秒數上限。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. yesYes 600 (10 分鐘)600 (10 minutes)
workingDirectory 字串string yesYes 容器在執行時間期間的工作目錄。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. yesYes $HOME
env [字串, 字串, ...][string, string, ...] yesYes 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, ...] yesYes 秘密物件的陣列。Array of secret objects. None
networks [network,network,...][network, network, ...] yesYes 網路物件的陣列。Array of network objects. None

secretsecret

Secret 物件具有下列屬性。The secret object has the following properties.

屬性Property 在系統提示您進行確認時,輸入Type 選用Optional 描述Description 預設值Default value
id 字串string No 密碼的識別碼。The identifier of the secret. None
keyvault 字串string yesYes Azure Key Vault 秘密 URL。The Azure Key Vault Secret URL. None
clientID 字串string yesYes 適用于 Azure 資源之使用者指派受控識別的用戶端識別碼。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 字串string No 網路的名稱。The name of the network. None
driver 字串string yesYes 用來管理網路的驅動程式。The driver to manage the network. None
ipv6 布林bool yesYes 是否啟用 IPv6 網路功能。Whether IPv6 networking is enabled. false
skipCreation 布林bool yesYes 是否略過網路建立。Whether to skip network creation. false
isDefault 布林bool yesYes 網路是否為 Azure Container Registry 所提供的預設網路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 Container Registry、其他私人登錄,以及公用 Docker Hub。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.1.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. 如需了解如何視需要推送所建置的映像,請參閱 pushSee push for how to optionally push built images.
yesYes
-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. yesYes
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 布林bool 選用Optional
disableWorkingDirectoryOverride 布林bool 選用Optional
entryPoint 字串string 選用Optional
env [字串, 字串, ...][string, string, ...] 選用Optional
expose [字串, 字串, ...][string, string, ...] 選用Optional
id 字串string 選用Optional
ignoreErrors 布林bool 選用Optional
isolation 字串string 選用Optional
keep 布林bool 選用Optional
network 物件object 選用Optional
ports [字串, 字串, ...][string, string, ...] 選用Optional
pull 布林bool 選用Optional
repeat intint 選用Optional
retries intint 選用Optional
retryDelay 整數 (秒)int (seconds) 選用Optional
secret 物件object 選用Optional
startDelay 整數 (秒)int (seconds) 選用Optional
timeout 整數 (秒)int (seconds) 選用Optional
when [字串, 字串, ...][string, string, ...] 選用Optional
workingDirectory 字串string 選用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.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile .

建置映像 - 子目錄中的內容Build image - context in subdirectory

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile ./subDirectory

pushpush

將一或多個已建置或重新標記的映像推送至登錄。Push one or more built or retagged images to a container registry. 支援推送至私人登錄 (例如 Azure Container Registry) 或公用 Docker Hub。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.1.0
steps:
  # Inline YAML collection syntax
  - push: ["$Registry/hello-world:$ID"]

為了提升可讀性,推送多個映像時,請使用巢狀語法:For increased readability, use nested syntax when pushing multiple images:

version: v1.1.0
steps:
  # Nested YAML collection syntax
  - push:
    - $Registry/hello-world:$ID
    - $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 字串string 選用Optional
ignoreErrors 布林bool 選用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.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push: 
    - $Registry/hello-world:$ID

建置、推送及執行Build, push, and run

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

cmdcmd

cmd 步驟類型會執行容器。The cmd step type runs a container.

語法:cmdSyntax: cmd

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

屬性:cmdProperties: cmd

cmd 步驟類型支援下列屬性:The cmd step type supports the following properties:

detach 布林bool 選用Optional
disableWorkingDirectoryOverride 布林bool 選用Optional
entryPoint 字串string 選用Optional
env [字串, 字串, ...][string, string, ...] 選用Optional
expose [字串, 字串, ...][string, string, ...] 選用Optional
id 字串string 選用Optional
ignoreErrors 布林bool 選用Optional
isolation 字串string 選用Optional
keep 布林bool 選用Optional
network 物件object 選用Optional
ports [字串, 字串, ...][string, string, ...] 選用Optional
pull 布林bool 選用Optional
repeat intint 選用Optional
retries intint 選用Optional
retryDelay 整數 (秒)int (seconds) 選用Optional
secret 物件object 選用Optional
startDelay 整數 (秒)int (seconds) 選用Optional
timeout 整數 (秒)int (seconds) 選用Optional
when [字串, 字串, ...][string, string, ...] 選用Optional
workingDirectory 字串string 選用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 Hub 上的 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.1.0
steps:
  - cmd: hello-world

執行 bash 映像並回應 "hello world"Run bash image and echo "hello world"

此命令會執行 bash-echo.yaml 工作檔案以參考 Docker Hub 上的 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.1.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 Hub 上的 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.1.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. 映像的開頭如果不是登錄,系統會假設其產生自 docker.io。Images not prefaced with a registry are assumed to originate from docker.io. 上述範例可同樣表示為:The previous example could equally be represented as:

version: v1.1.0
steps:
  - cmd: docker.io/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 container registry 的映射。Run an image that's from an Azure container registry. 下列範例假設您具有名為 myregistry的登錄,以及自訂映射 myimage:mytagThe following example assumes you have a registry named myregistry, and a custom image myimage:mytag.

    version: v1.1.0
    steps:
        - cmd: myregistry.azurecr.io/myimage:mytag
    
  • 使用執行變數或別名將登錄參考一般化Generalize the registry reference with a Run variable or alias

    您不需要在 acr-task.yaml 檔案中硬式編碼您的登錄名稱,而可以使用執行變數別名讓它更具可攜性。Instead of hard-coding your registry name in an acr-task.yaml file, you can make it more portable by using a Run variable or alias. Run.Registry 變數或 $Registry 別名會在執行時間展開為工作執行所在的登錄名稱。The Run.Registry variable or $Registry alias expands at runtime to the name of the registry in which the task is executing.

    例如,若要將上述工作一般化,使其可在任何 Azure container registry 中運作,請參考映射名稱中的 $Registry 變數:For example, to generalize the preceding task so that it works in any Azure container registry, reference the $Registry variable in the image name:

    version: v1.1.0
    steps:
      - cmd: $Registry/myimage:mytag
    

工作步驟屬性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 布林bool yesYes 執行時是否應將容器中斷連結。Whether the container should be detached when running. false
disableWorkingDirectoryOverride 布林bool yesYes 是否要停用 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 字串string yesYes 覆寫步驟容器的 [ENTRYPOINT]Overrides the [ENTRYPOINT] of a step's container. None
env [字串, 字串, ...][string, string, ...] yesYes key=value 格式的字串陣列,用來定義步驟的環境變數。Array of strings in key=value format that define the environment variables for the step. None
expose [字串, 字串, ...][string, string, ...] yesYes 從容器公開的埠陣列。Array of ports that are exposed from the container. None
id 字串string yesYes 可唯一識別工作內的步驟。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 logs [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 檔案中步驟上階的以零為基的索引acb_step_%d, where %d is the 0-based index of the step top-down in the YAML file
ignoreErrors 布林bool yesYes 不論容器執行期間是否發生錯誤,是否將步驟標記為成功。Whether to mark the step as successful regardless of whether an error occurred during container execution. false
isolation 字串string yesYes 容器的隔離等級。The isolation level of the container. default
keep 布林bool yesYes 在執行後是否應保留步驟的容器。Whether the step's container should be kept after execution. false
network 物件object yesYes 識別執行容器的網路。Identifies a network in which the container runs. None
ports [字串, 字串, ...][string, string, ...] yesYes 從容器發佈到主機的埠陣列。Array of ports that are published from the container to the host. None
pull 布林bool yesYes 是否要先強制提取容器,再執行它以防止任何快取行為。Whether to force a pull of the container before executing it to prevent any caching behavior. false
privileged 布林bool yesYes 是否要以特殊許可權模式執行容器。Whether to run the container in privileged mode. false
repeat intint yesYes 重複執行容器的重試次數。The number of retries to repeat the execution of a container. 00
retries intint yesYes 容器失敗執行時嘗試的重試次數。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) yesYes 容器執行重試之間的延遲(以秒為單位)。The delay in seconds between retries of a container's execution. 00
secret 物件object yesYes 識別 Azure 資源的 Azure Key Vault 秘密或受控識別Identifies an Azure Key Vault secret or managed identity for Azure resources. None
startDelay 整數 (秒)int (seconds) yesYes 延遲容器執行的秒數。Number of seconds to delay a container's execution. 00
timeout 整數 (秒)int (seconds) yesYes 終止步驟前可允許步驟執行的秒數上限。Maximum number of seconds a step may execute before being terminated. 600600
when [字串, 字串, ...][string, string, ...] yesYes 設定步驟與工作內一或多個其他步驟的相依性。Configures a step's dependency on one or more other steps within the task. None
user 字串string yesYes 容器的使用者名稱或 UIDThe user name or UID of a container None
workingDirectory 字串string yesYes 設定步驟的工作目錄。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. 每個步驟都會由唯一 id 識別,工作中的其他步驟會在其 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.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$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: $Registry/hello-world:$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: ["$Registry/hello-world:$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.1.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.1.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.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$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.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$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: $Registry/hello-world:$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: ["$Registry/hello-world:$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.SharedVolume
  • Run.Registry
  • Run.RegistryName
  • Run.Date
  • Run.OS
  • Run.Architecture
  • Run.Commit
  • Run.Branch
  • Run.TaskName

變數名稱一般一目了然。The variable names are generally self-explanatory. 常用變數的詳細資料如下所示。Details follows for commonly used variables. 從 YAML 版本 v1.1.0開始,您可以使用縮寫的預先定義工作別名來取代大部分的執行變數。As of YAML version v1.1.0, you can use an abbreviated, predefined task alias in place of most run variables. 例如,若要取代 {{.Run.Registry}},請使用 $Registry 別名。For example, in place of {{.Run.Registry}}, use the $Registry alias.

Run.IDRun.ID

每次執行時,都會透過 az acr run,或透過 az acr task create建立的觸發程式執行,都有唯一的識別碼。Each Run, through az acr run, or trigger based execution of tasks created through az acr task create, has a unique ID. 此識別碼代表目前正在執行的「執行」。The ID represents the Run currently being executed.

通常用來唯一標記某個映像:Typically used for a uniquely tagging an image:

version: v1.1.0
steps:
    - build: -t $Registry/hello-world:$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.1.0
steps:
  - build: -t $Registry/hello-world:$ID .

執行. 于: registrynameRun.RegistryName

容器登錄的名稱。The name of the container registry. 通常用於不需要完整伺服器名稱的工作步驟中,例如,cmd 在登錄上執行 Azure CLI 命令的步驟。Typically used in task steps that don't require a fully qualified server name, for example, cmd steps that run Azure CLI commands on registries.

version 1.1.0
steps:
# List repositories in registry
- cmd: az login --identity
- cmd: az acr repository list --name $RegistryName

Run.DateRun.Date

執行開始的目前 UTC 時間。The current UTC time the run began.

執行. CommitRun.Commit

對於由 GitHub 存放庫認可所觸發的工作,認可識別碼。For a task triggered by a commit to a GitHub repository, the commit identifier.

執行分支Run.Branch

對於由 GitHub 存放庫認可所觸發的工作,則為分支名稱。For a task triggered by a commit to a GitHub repository, the branch name.

別名Aliases

v1.1.0,ACR 工作支援執行時可供工作步驟使用的別名。As of v1.1.0, ACR Tasks supports aliases that are available to task steps when they execute. 別名類似于 bash 中支援的別名(命令快捷方式)和一些其他命令 shell。Aliases are similar in concept to aliases (command shortcuts) supported in bash and some other command shells.

使用別名時,您可以藉由輸入單一單字,啟動任何命令或命令群組(包括選項和檔案名)。With an alias, you can launch any command or group of commands (including options and filenames) by entering a single word.

ACR 工作支援數個預先定義的別名,以及您所建立的自訂別名。ACR Tasks supports several predefined aliases and also custom aliases you create.

預先定義的別名Predefined aliases

下列工作別名可用於取代執行變數The following task aliases are available to use in place of run variables:

AliasAlias 執行變數Run variable
ID Run.ID
SharedVolume Run.SharedVolume
Registry Run.Registry
RegistryName Run.RegistryName
Date Run.Date
OS Run.OS
Architecture Run.Architecture
Commit Run.Commit
Branch Run.Branch

在 [工作步驟] 中,在別名前面加上 $ 指示詞,如下列範例所示:In task steps, precede an alias with the $ directive, as in this example:

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .

影像別名Image aliases

下列每個別名都會指向 Microsoft Container Registry (MCR)中的穩定映射。Each of the following aliases points to a stable image in Microsoft Container Registry (MCR). 您可以在工作檔案的 [cmd] 區段中參考每個專案,而不使用指示詞。You can refer to each of them in the cmd section of a Task file without using a directive.

AliasAlias 映像Image
acr mcr.microsoft.com/acr/acr-cli:0.1
az mcr.microsoft.com/acr/azure-cli:d0725bc
bash mcr.microsoft.com/acr/bash:d0725bc
curl mcr.microsoft.com/acr/curl:d0725bc

下列範例工作會使用數個別名,在執行登錄中的存放庫 samples/hello-world清除7 天之前的映射標記:The following example task uses several aliases to purge image tags older than 7 days in the repo samples/hello-world in the run registry:

version: v1.1.0
steps:
  - cmd: acr tag list --registry $RegistryName --repository samples/hello-world
  - cmd: acr purge --registry $RegistryName --filter samples/hello-world:.* --ago 7d

自訂別名Custom alias

在 YAML 檔案中定義自訂別名並加以使用,如下列範例所示。Define a custom alias in your YAML file and use it as shown in the following example. 別名只能包含英數位元。An alias can contain only alphanumeric characters. 展開別名的預設指示詞是 $ 字元。The default directive to expand an alias is the $ character.

version: v1.1.0
alias:
  values:
    repo: myrepo
steps:
  - build: -t $Registry/$repo/hello-world:$ID -f Dockerfile .

您可以連結至遠端或本機 YAML 檔案,以取得自訂別名定義。You can link to a remote or local YAML file for custom alias definitions. 下列範例會連結至 Azure blob 儲存體中的 YAML 檔案:The following example links to a YAML file in Azure blob storage:

version: v1.1.0
alias:
  src:  # link to local or remote custom alias files
    - 'https://link/to/blob/remoteAliases.yml?readSasToken'
[...]

後續步驟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.