本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在佇列環境中設定環境變數
<a name="set-environment-variables"></a>

許多應用程式和架構使用環境變數來控制功能設定、記錄層級和顯示組態。您可以使用[開放任務描述 (OpenJD) 環境](https://github.com/OpenJobDescription/openjd-specifications/wiki/2023-09-Template-Schemas#4-environment)來設定其範圍內每個任務命令繼承的環境變數。

## 環境變數範圍
<a name="set-env-vars-scope"></a>

AWS 截止日期 Cloud 會從您連接至佇列的佇列環境套用環境變數。在任務範本中，您也可以使用 [OpenJD 環境在任務和步驟層級定義環境](https://github.com/OpenJobDescription/openjd-specifications/wiki/2023-09-Template-Schemas#4-environment)變數。在較窄範圍定義的變數，會覆寫具有較廣泛範圍相同名稱的變數。
+ **佇列環境** – 您附加至截止日期雲端中佇列的範本。變數會套用至提交至佇列的所有任務。您可以使用固定值的`variables`映射來設定變數，或使用動態值的指令碼。
+ **任務環境** – 在任務範本`jobEnvironments`的 下定義。變數適用於任務中的所有步驟和任務。任務層級變數會以相同名稱覆寫佇列層級變數。
+ **步驟環境** – 在任務範本`stepEnvironments`的 下定義。變數僅適用於該步驟中的任務。步驟層級變數會以相同名稱覆寫任務層級或佇列層級變數。

## 在佇列環境中設定變數
<a name="set-env-vars-queue-env"></a>

您可以使用固定值的`variables`映射，或在動態值`script`的 `onEnter` 動作中使用 ，在佇列環境中設定環境變數。

下列佇列環境範本使用`variables`映射將`QT_QPA_PLATFORM`變數設定為 `offscreen`，這可讓使用 [Qt 架構](https://www.qt.io/product/framework)的應用程式在沒有互動式顯示的工作者主機上執行。

```
specificationVersion: 'environment-2023-09'
environment:
  name: QtOffscreen
  variables:
    QT_QPA_PLATFORM: offscreen
```

對於動態值，例如修改`PATH`或啟用虛擬環境，請使用以 `openjd_env: {{VAR}}={{value}}`stdout 格式列印行的指令碼。字`openjd_env:`首為必要。使用 `echo`、 `export`或其他沒有字首的 Shell 機制，不會將變數傳播至任務。

下列佇列環境範本會使用指令碼設定`QT_QPA_PLATFORM`變數。

```
specificationVersion: 'environment-2023-09'
environment:
  name: QtOffscreen
  script:
    actions:
      onEnter:
        command: bash
        args:
        - "{{Env.File.Enter}}"
    embeddedFiles:
    - name: Enter
      type: TEXT
      data: |
        #!/bin/env bash
        set -euo pipefail
        echo "openjd_env: QT_QPA_PLATFORM=offscreen"
```

若要將佇列環境連接至佇列，請使用截止日期雲端主控台或 AWS CLI。如需詳細資訊，請參閱《 AWS 截止日期雲端使用者指南》中的[建立佇列環境](https://docs.aws.amazon.com/deadline-cloud/latest/userguide/create-queue-environment.html)。下列 AWS CLI 命令會從範本檔案建立佇列環境。

```
aws deadline create-queue-environment \
    --farm-id {{FARM_ID}} \
    --queue-id {{QUEUE_ID}} \
    --priority 1 \
    --template-type YAML \
    --template file://{{my-queue-env.yaml}}
```

如需建立和啟用 conda 虛擬環境等更複雜的範例，請參閱 GitHub 上的[截止日期雲端佇列環境範例](https://github.com/aws-deadline/deadline-cloud-samples/tree/mainline/queue_environments)。

## 在任務範本中設定變數
<a name="set-env-vars-job-template"></a>

在任務範本中，將`variables`映射新增至 `jobEnvironments`或 `stepEnvironments`項目。每個項目都是索引鍵/值對，其中索引鍵是變數名稱，而值是變數值。

下列任務範本會將`QT_QPA_PLATFORM`環境變數設定為 `offscreen`，允許使用 [Qt 架構](https://www.qt.io/product/framework)的應用程式在沒有互動式顯示的工作者主機上執行。

```
specificationVersion: 'jobtemplate-2023-09'
name: MyJob
jobEnvironments:
- name: JobEnv
  variables:
    QT_QPA_PLATFORM: offscreen
```

您可以在單一環境定義中設定多個變數。

```
jobEnvironments:
- name: JobEnv
  variables:
    JOB_VERBOSITY: MEDIUM
    JOB_PROJECT_ID: {{my-project-id}}
    JOB_ENDPOINT_URL: {{https://my-host-name/my/path}}
    QT_QPA_PLATFORM: offscreen
```

您可以使用 `{{Param.{{ParameterName}}}}` 語法，在變數值中參考任務參數。

```
jobEnvironments:
- name: JobEnv
  variables:
    JOB_EXAMPLE_PARAM: "{{Param.ExampleParam}}"
```

若要覆寫特定步驟的任務層級變數，請使用相同的變數名稱定義`stepEnvironments`項目。下列範例`JOB_PROJECT_ID`會在任務層級以值 定義 `project-12`，然後使用 覆寫步驟層級的值`step-project-12`。步驟中的任務使用步驟層級值。

```
specificationVersion: 'jobtemplate-2023-09'
name: MyJob
jobEnvironments:
- name: JobEnv
  variables:
    JOB_PROJECT_ID: project-12
steps:
- name: MyStep
  stepEnvironments:
  - name: StepEnv
    variables:
      JOB_PROJECT_ID: step-project-12
```

## 試用：執行環境變數範例
<a name="set-env-vars-example"></a>

Deadline Cloud 範例儲存庫包含[任務套件，示範設定和檢視環境變數](https://github.com/aws-deadline/deadline-cloud-samples/tree/mainline/job_bundles/job_env_vars/template.yaml)。範例任務範本會在任務和步驟層級定義變數，然後執行列印合併結果的任務。使用下列程序執行範例並檢查結果。

### 先決條件
<a name="set-prerequisites"></a>

1. 如果您沒有具有佇列和相關聯 Linux 機群的截止日期雲端陣列，請遵循[截止日期雲端主控台](https://console.aws.amazon.com/deadlinecloud/home)中的引導式加入體驗，以使用預設設定建立。

1. 如果您的工作站上沒有截止日期雲端 CLI AWS 和截止日期雲端監視器，請遵循[設定截止日期雲端提交者](https://docs.aws.amazon.com/deadline-cloud/latest/userguide/submitter.html)中的步驟。

1. 使用 `git`複製[截止日期雲端範例 GitHub 儲存庫](https://github.com/aws-deadline/deadline-cloud-samples)。

   ```
   git clone https://github.com/aws-deadline/deadline-cloud-samples.git
   cd deadline-cloud-samples/job_bundles
   ```

### 執行範例
<a name="set-run-example"></a>

1. 使用截止日期雲端 CLI 提交`job_env_vars`範例。

   ```
   deadline bundle submit job_env_vars
   ```

1. 在截止日期雲端監視器中，選取新任務以監控其進度。與佇列相關聯的Linux機群有可用的工作者後，任務會在幾秒鐘內完成。選取任務，然後在任務面板的右上角選單中選擇**檢視日誌**。

### 比較工作階段動作及其定義
<a name="set-compare-actions"></a>

日誌檢視會顯示三個工作階段動作。在文字編輯器中開啟檔案 [job\_env\_vars/template.yaml](https://github.com/aws-deadline/deadline-cloud-samples/tree/mainline/job_bundles/job_env_vars/template.yaml)，將每個動作與其在任務範本中的定義進行比較。

1. 選取**啟動 JobEnv** 工作階段動作。日誌輸出會顯示正在設定的任務層級環境變數。

   ```
   Setting: JOB_VERBOSITY=MEDIUM
   Setting: JOB_EXAMPLE_PARAM=An example parameter value
   Setting: JOB_PROJECT_ID=project-12
   Setting: JOB_ENDPOINT_URL=https://internal-host-name/some/path
   Setting: QT_QPA_PLATFORM=offscreen
   ```

   來自任務範本的下列行定義了此環境。

   ```
   jobEnvironments:
   - name: JobEnv
     variables:
       JOB_VERBOSITY: MEDIUM
       JOB_EXAMPLE_PARAM: "{{Param.ExampleParam}}"
       JOB_PROJECT_ID: project-12
       JOB_ENDPOINT_URL: https://internal-host-name/some/path
       QT_QPA_PLATFORM: offscreen
   ```

1. 選取**啟動 StepEnv** 工作階段動作。日誌輸出會顯示步驟層級變數，包括覆寫的 `JOB_PROJECT_ID`。

   ```
   Setting: STEP_VERBOSITY=HIGH
   Setting: JOB_PROJECT_ID=step-project-12
   ```

   來自任務範本的下列行定義了此環境。

   ```
   stepEnvironments:
   - name: StepEnv
     variables:
       STEP_VERBOSITY: HIGH
       JOB_PROJECT_ID: step-project-12
   ```

1. 選取**任務執行**工作階段動作。日誌輸出會顯示任務可用的合併環境變數。請注意， `JOB_PROJECT_ID`使用步驟層級值 `step-project-12`。

   ```
   Environment variables starting with JOB_*:
   JOB_ENDPOINT_URL=https://internal-host-name/some/path
   JOB_EXAMPLE_PARAM='An example parameter value'
   JOB_PROJECT_ID=step-project-12
   JOB_VERBOSITY=MEDIUM
   
   Environment variables starting with STEP_*:
   STEP_VERBOSITY=HIGH
   ```