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

# Nextflow 工作流程定義詳細資訊
<a name="workflow-definition-nextflow"></a>

HealthOmics 支援 Nextflow DSL1 和 DSL2。如需詳細資訊，請參閱[Nextflow 版本支援](workflows-lang-versions.md#workflows-lang-versions-nextflow)。

Nextflow DSL2 是以 Groovy 程式設計語言為基礎，因此參數是動態的，並且可以使用與 Groovy 相同的規則來強制類型。輸入 JSON 提供的參數和值可在工作流程的參數 (`params`) 映射中使用。

**Topics**
+ [使用 nf-schema 和 nf-validation 外掛程式](#schema-and-validation-plugins-nextflow)
+ [指定儲存 URIs](#storage-uris-nextflow)
+ [Nextflow 指令](#workflow-nexflow-directives)
+ [使用 Nextflow 設定檔](#nextflow-profiles)
+ [匯出工作流程層級內容](#exporting-workflow-content-nextflow)
+ [匯出任務內容](#exporting-task-content-nextflow)
+ [產生 Nextflow 執行報告](#nextflow-execution-reports)
+ [指定 Nextflow 語法版本](#nextflow-syntax-version)
+ [工作流程建立期間的自動語法驗證](#nextflow-automatic-validation)
+ [在 Nextflow 中有效率地使用暫存儲存](#nextflow-scratch-storage)

## 使用 nf-schema 和 nf-validation 外掛程式
<a name="schema-and-validation-plugins-nextflow"></a>

**注意**  
外掛程式的 HealthOmics 支援摘要：  
v22.04 – 不支援外掛程式
v23.10 – 支援 `nf-schema` 和 `nf-validation`
v24.10 – 支援 `nf-schema`
v25.10、v26.04 – 支援 `nf-schema`、`nf-core-utils`、 `nf-fgbio`和 `nf-prov`

HealthOmics 提供下列對 Nextflow 外掛程式的支援：
+ 對於 Nextflow v23.10，HealthOmics 會預先安裝 nf-validation@1.1.1 外掛程式。
+ 對於 Nextflow v23.10 和 v24.10，HealthOmics 會預先安裝 nf-schema@2.3.0 外掛程式。
+ 對於 Nextflow v25.10，HealthOmics 會預先安裝 nf-schema@2.6.1、nf-core-utils@0.4.0、nf-prov@1.7.0 和 nf-fgbio@1.0.1 外掛程式。
+ 對於 Nextflow v26.04，HealthOmics 會預先安裝 nf-schema@2.7.2、nf-core-utils@0.4.0、nf-prov@1.7.0 和 nf-fgbio@1.0.1 外掛程式。
+ 您無法在工作流程執行期間擷取其他外掛程式。HealthOmics 會忽略您在 `nextflow.config` 檔案中指定的任何其他外掛程式版本。
+ 對於 Nextflow v24 和更高版本， `nf-schema`是已棄用`nf-validation`外掛程式的新版本。如需詳細資訊，請參閱 Nextflow GitHub 儲存庫中的 [ nf-schema](https://github.com/nextflow-io/nf-schema)。

## 指定儲存 URIs
<a name="storage-uris-nextflow"></a>

使用 Amazon S3 或 HealthOmics URI 建構 Nextflow 檔案或路徑物件時，只要授予讀取存取權，就會將相符的物件提供給工作流程。Amazon S3 URIs 允許使用字首或目錄。如需範例，請參閱 [Amazon S3 輸入參數格式](workflows-run-inputs.md#s3-run-input-formats)。

HealthOmics 部分支援在 Amazon S3 URIs 或 HealthOmics 儲存 URIs 中使用 glob 模式。在工作流程定義中使用 Glob 模式來建立 `path`或 `file`頻道。如需預期的行為和確切案例，請參閱 [Amazon S3 輸入中 Glob 模式的下一個流程處理](workflows-run-inputs.md#wd-nextflow-s3-formats)。

## Nextflow 指令
<a name="workflow-nexflow-directives"></a>

您可以在 Nextflow 組態檔案或工作流程定義中設定 Nextflow 指令。下列清單顯示 HealthOmics 用來套用組態設定的優先順序，從最低到最高優先順序：

1. 組態檔案中的全域組態。

1. 工作流程定義的任務區段。

1. 組態檔案中的任務特定選擇器。

**Topics**
+ [使用 的任務重試策略 `errorStrategy`](#workflow-nextflow-errorStrategy)
+ [使用 的任務重試嘗試 `maxRetries`](#workflow-nexflow-task-retry)
+ [使用 選擇退出任務重試 `omicsRetryOn5xx`](#workflow-nextflow-retry-5xx)
+ [使用 `time`指令的任務持續時間](#time-directive-nextflow)

### 使用 的任務重試策略 `errorStrategy`
<a name="workflow-nextflow-errorStrategy"></a>

使用 `errorStrategy`指令來定義任務錯誤的策略。根據預設，當任務傳回錯誤指示 （非零結束狀態） 時，任務會停止，且 HealthOmics 會終止整個執行。如果您將 `errorStrategy`設定為 `retry`，HealthOmics 會嘗試重試失敗的任務一次。若要增加重試次數，請參閱 [使用 的任務重試嘗試 `maxRetries`](#workflow-nexflow-task-retry)。

```
process {
    label 'my_label'
    errorStrategy 'retry'

    script:
    """
    your-command-here
    """
}
```

如需有關 HealthOmics 在執行期間如何處理任務重試的資訊，請參閱 [任務重試](monitoring-runs.md#run-status-task-retries)。

### 使用 的任務重試嘗試 `maxRetries`
<a name="workflow-nexflow-task-retry"></a>

根據預設，HealthOmics 不會嘗試任何重試失敗的任務，或者如果您設定 ，則嘗試重試一次`errorStrategy`。若要增加重試次數上限，請將 `errorStrategy`設定為 `retry`，並使用 `maxRetries`指令設定重試次數上限。

下列範例會將全域組態中的重試次數上限設定為 3。

```
process {
    errorStrategy = 'retry'
    maxRetries = 3
}
```

下列範例示範如何在工作流程定義的任務區段`maxRetries`中設定 。

```
process myTask {
    label 'my_label'
    errorStrategy 'retry'
    maxRetries 3
    
    script:
    """
    your-command-here
    """
}
```

下列範例顯示如何根據名稱或標籤選擇器，在 Nextflow 組態檔案中指定任務特定的組態。

```
process {
    withLabel: 'my_label' {
        errorStrategy = 'retry'
        maxRetries = 3
    }

    withName: 'myTask' {
        errorStrategy = 'retry'
        maxRetries = 3
    }
}
```

### 使用 選擇退出任務重試 `omicsRetryOn5xx`
<a name="workflow-nextflow-retry-5xx"></a>

對於 Nextflow v23 和更新版本，如果任務因服務錯誤 (5XX HTTP 狀態碼） 失敗，HealthOmics 支援任務重試。根據預設，HealthOmics 最多會嘗試兩次失敗任務的重試。

您可以設定 `omicsRetryOn5xx`以選擇退出服務錯誤的任務重試。如需 HealthOmics 中任務重試的詳細資訊，請參閱 [任務重試](monitoring-runs.md#run-status-task-retries)。

下列範例會在全域組態`omicsRetryOn5xx`中設定 ，以選擇退出任務重試。

```
process {
    omicsRetryOn5xx = false
}
```

下列範例示範如何在工作流程定義的任務區段`omicsRetryOn5xx`中設定 。

```
process myTask {
    label 'my_label'
    omicsRetryOn5xx = false
    
    script:
    """
    your-command-here
    """
}
```

下列範例顯示如何根據名稱或標籤選擇器，在 Nextflow 組態檔案中`omicsRetryOn5xx`將 設定為任務特定組態。

```
process {
    withLabel: 'my_label' {
        omicsRetryOn5xx = false
    }

    withName: 'myTask' {
        omicsRetryOn5xx = false
    }
}
```

### 使用 `time`指令的任務持續時間
<a name="time-directive-nextflow"></a>

HealthOmics 提供可調整的配額 （請參閱 [HealthOmics 服務配額](service-quotas.md))，以指定執行的最長持續時間。對於 Nextflow v23 和更新版本的工作流程，您也可以使用 Nextflow `time`指令指定任務持續時間上限。

在新的工作流程開發期間，設定任務持續時間上限可協助您擷取失控任務和長時間執行的任務。

如需 Nextflow 時間指令的詳細資訊，請參閱 Nextflow 參考中的[時間指令](https://www.nextflow.io/docs/latest/reference/process.html#process-time)。

HealthOmics 為 Nextflow 時間指令提供下列支援：

1. HealthOmics 支援時間指令的 1 分鐘精細程度。您可以指定介於 60 秒和最大執行持續時間值之間的值。

1. 如果您輸入的值小於 60，HealthOmics 會四捨五入至 60 秒。對於 60 以上的值，HealthOmics 會四捨五入到最接近的分鐘。

1. 如果工作流程支援重試任務，HealthOmics 會在任務逾時時重試任務。

1. 如果任務逾時 （或上次重試逾時），HealthOmics 會取消任務。此操作的持續時間可以是 1 到 2 分鐘。

1. 在任務逾時時，HealthOmics 會將執行和任務狀態設定為失敗，並取消執行中的其他任務 （適用於處於啟動、待定或執行狀態的任務）。HealthOmics 會將輸出從逾時之前完成的任務匯出到您指定的 S3 輸出位置。

1. 任務花費在待定狀態的時間不會計入任務持續時間。

1. 如果執行是執行群組的一部分，且執行群組比任務計時器快逾時，則執行和任務會轉換為失敗狀態。

使用下列一或多個單位指定逾時持續時間：`ms`、`m``h`、 `s`或 `d`。

下列範例顯示如何在 Nextflow 組態檔案中指定全域組態。它將全域逾時設定為 1 小時 30 分鐘。

```
process {
    time = '1h30m'
}
```

下列範例顯示如何在工作流程定義的任務區段中指定時間指令。此範例會設定 3 天、5 小時和 4 分鐘的逾時。此值優先於組態檔案中的全域值，但不優先於`my_label`組態檔案中 的任務特定時間指令。

```
process myTask {
    label 'my_label'
    time '3d5h4m'
        
    script:
    """
    your-command-here
    """
}
```

下列範例顯示如何根據名稱或標籤選擇器，在 Nextflow 組態檔案中指定任務特定的時間指令。此範例會設定 30 分鐘的全域任務逾時值。它會為任務設定 2 小時的值，`myTask`並為具有標籤 的任務設定 3 小時的值`my_label`。對於符合選取器的任務，這些值優先於工作流程定義中的全域值和值。

```
process {
    time = '30m'
    
    withLabel: 'my_label' {
        time = '3h'  
    }

    withName: 'myTask' {
        time = '2h'  
    }
}
```

## 使用 Nextflow 設定檔
<a name="nextflow-profiles"></a>

Nextflow 設定檔是一組命名的組態設定，您可以在執行時間選取。在 `nextflow.config` 檔案的 `profiles`區塊中定義設定檔：

```
profiles {
    standard {
        process.cpus = 2
        process.memory = '4 GB'
    }

    production {
        process.cpus = 16
        process.memory = '64 GB'
        params.input = 's3://bucket/production-data.bam'
    }
}
```

當您開始執行時，請使用 `engineSettings` 參數指定一或多個設定檔。HealthOmics 會將 `-profile`旗標傳遞至 Nextflow 引擎。如需詳細資訊，請參閱[指定 Nextflow 引擎設定](starting-a-run.md#start-run-api-engine-settings)。

```
aws omics start-run \
  --workflow-id {{workflow-id}} \
  --role-arn {{role-arn}} \
  --output-uri s3://{{bucket}}/{{prefix}}/ \
  --engine-settings '{"profile": "production"}'
```

指定多個設定檔時 （例如，`"test,docker"`)，Nextflow 會按照命令列中指定的順序套用它們。稍後的設定檔會針對衝突的設定覆寫先前的設定檔。對於低於 26 的 Nextflow 版本，設定檔會按照組態檔案中定義的順序套用，而非命令列順序。

注意下列事項：
+ 設定檔支援適用於所有 HealthOmics 支援的 Nextflow 版本。
+ 設定檔可以包含參數、程序指令、`includeConfig`陳述式和資訊清單覆寫 （包括 `manifest.nextflowVersion`)。
+ 明確執行參數優先於設定檔定義的參數值。
+ 如果您指定不存在的設定檔，HealthOmics 會傳回驗證錯誤。
+ 設定檔必須在工作流程定義 zip 檔案中定義。HealthOmics 不支援從外部來源擷取設定檔定義。
+ 如果您未指定設定檔，執行會在工作流程定義中的`standard`設定檔下定義設定檔時使用該設定檔。否則，執行會使用預設 （頂層） 組態。
+ 使用設定檔時，建議您使用 在工作流程定義中釘選 Nextflow 版本`manifest.nextflowVersion`，以確保跨執行的設定檔應用程式行為一致。

## 匯出工作流程層級內容
<a name="exporting-workflow-content-nextflow"></a>

對於 Nextflow v25.10 和更新版本，您可以匯出在個別任務之外產生的檔案，例如來源報告或管道 DAGs。若要匯出這些檔案，請將它們寫入 `/mnt/workflow/output/`。HealthOmics 會將置於此目錄中的檔案匯出至執行 Amazon S3 輸出位置的`output/`字首。

下列範例示範如何設定`nf-prov`外掛程式，將來源報告寫入 `/mnt/workflow/output/`。

```
prov {
    formats {
        bco {
            file = "/mnt/workflow/output/pipeline_info/manifest.bco.json"
        }
    }
}
```

您也可以在執行的輸入 JSON 中將此路徑做為參數傳遞。此方法常見於使用 的 nf 核心工作流程`params.outdir`。

```
{
    "outdir": "/mnt/workflow/output/"
}
```

## 匯出任務內容
<a name="exporting-task-content-nextflow"></a>

對於以 Nextflow 編寫的工作流程，請定義 **publishDir** 指令，將任務內容匯出到您的輸出 Amazon S3 儲存貯體。如下列範例所示，將 **publishDir** 值設定為 `/mnt/workflow/pubdir`。若要將檔案匯出至 Amazon S3，檔案必須位於此目錄中。

```
 nextflow.enable.dsl=2
              
  workflow {
    CramToBamTask(params.ref_fasta, params.ref_fasta_index, params.ref_dict, params.input_cram, params.sample_name)
    ValidateSamFile(CramToBamTask.out.outputBam)
  }
  
  process CramToBamTask {
    container "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-cloud"
  
    publishDir "/mnt/workflow/pubdir"
  
    input:
        path ref_fasta
        path ref_fasta_index
        path ref_dict
        path input_cram
        val sample_name
  
    output:
        path "${sample_name}.bam", emit: outputBam
        path "${sample_name}.bai", emit: outputBai
  
    script:
    """
        set -eo pipefail
  
        samtools view -h -T $ref_fasta $input_cram |
        samtools view -b -o ${sample_name}.bam -
        samtools index -b ${sample_name}.bam
        mv ${sample_name}.bam.bai ${sample_name}.bai
    """
  }
  
  process ValidateSamFile {
    container "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-cloud"
  
    publishDir "/mnt/workflow/pubdir"
  
    input:
        file input_bam
  
    output:
        path "validation_report"
  
    script:
    """
        java -Xmx3G -jar /usr/gitc/picard.jar \
        ValidateSamFile \
        INPUT=${input_bam} \
        OUTPUT=validation_report \
        MODE=SUMMARY \
        IS_BISULFITE_SEQUENCED=false
    """
  }
```

對於 Nextflow v25.10 和更新版本，作為 的替代方案`publishDir`，您可以使用工作流程輸出來匯出任務內容。下列範例示範如何定義將任務結果匯出至 Amazon S3 的工作流程`output`區塊。

```
process myTask {
    input:
    val data

    output:
    path 'result.txt'

    script:
    """
    echo ${data} > result.txt
    """
}

workflow {
    main:
    output_file = myTask('hello')

    publish:
    results = output_file
}

output {
    results {
        path '.'
    }
}
```

如需工作流程輸出的詳細資訊，請參閱 Nextflow 文件中的[工作流程輸出](https://www.nextflow.io/docs/latest/workflow.html#workflow-output-def)。

## 產生 Nextflow 執行報告
<a name="nextflow-execution-reports"></a>

Nextflow 可以為每個執行產生四個內建報告：執行報告 (`report`)、時間軸 (`timeline`)、追蹤檔案 (`trace`) 和工作流程圖表 ()`dag`。若要讓 HealthOmics 將這些檔案匯出到執行的 Amazon S3 輸出位置，請將每個檔案設定為將其輸出寫入 `/mnt/workflow/output/` `nextflow.config`檔案中：

```
report {
    enabled = true
    file = '/mnt/workflow/output/report.html'
    overwrite = true
}

timeline {
    enabled = true
    file = '/mnt/workflow/output/timeline.html'
    overwrite = true
}

trace {
    enabled = true
    file = '/mnt/workflow/output/trace.txt'
    overwrite = true
}

dag {
    enabled = true
    file = '/mnt/workflow/output/dag.html'
    overwrite = true
}
```

HealthOmics 會將在 下寫入`/mnt/workflow/output/`執行 Amazon S3 輸出位置字`output/`首的檔案匯出。如需此匯出路徑的詳細資訊，請參閱 [匯出工作流程層級內容](#exporting-workflow-content-nextflow)。寫入外部的報告`/mnt/workflow/output/`不會匯出到執行的 Amazon S3 輸出位置。

**任務容器必須包含 `ps`**  
啟用 `report`、 `timeline`或 `trace`報告時，Nextflow 會在每個任務容器`ps`內叫用 ，以收集每個任務的指標。您使用 `container`指令指定的容器映像必須包含 `ps`命令。在大多數 Linux 發行版本上，使用 `procps`(Debian/Ubuntu) 或 `procps-ng`(Amazon Linux、Red Hat、Fedora) 套件進行安裝。如果程序未宣告`container`指令，HealthOmics 會在已包含 的預設容器中執行任務`ps`。

**工作流程圖表格式**  
`dag` 報告支援多種輸出格式，由 的延伸選取`dag.file`。HTML、Mermaid 和 DOT 格式由 Nextflow 直接轉譯，不需要額外的工具。PDF、PNG 和 SVG 格式需要 Graphviz，不包含在 HealthOmics 的 Nextflow 引擎中。如果 `dag.file` 設定為 PDF、PNG 或 SVG 路徑，Nextflow 會記錄警告，並將工作流程圖表寫入來源`.dot`檔案；執行仍然成功完成。我們建議`dag.file`將 設定為 `.html`、 `.mmd`或 `.dot` 路徑，以避免警告並產生請求的格式。

## 指定 Nextflow 語法版本
<a name="nextflow-syntax-version"></a>

Nextflow v26.04.0 預設使用嚴格 (v2) 語法剖析器。這是使用舊版 (v1) 語法寫入的工作流程的重大變更，這是 Nextflow v25.10.0 和更早版本中的預設值。如需 v2 語法的相關資訊，請參閱 [Seqera Nextflow 文件中的嚴格語法](https://docs.seqera.io/nextflow/strict-syntax)。

若要執行針對舊版 (v1) 剖析器撰寫的工作流程，請在**StartRun**請求`v1`中將 `engineSettings.syntaxVersion`設定為 ：

```
{
  "engineSettings": {
    "syntaxVersion": "v1"
  }
}
```

對於 Nextflow v25.10.0 和更早版本，HealthOmics 不支援 v2 剖析器。

## 工作流程建立期間的自動語法驗證
<a name="nextflow-automatic-validation"></a>

當您建立或更新 Nextflow DSL2 工作流程時，HealthOmics 會自動執行 Nextflow 內建的嚴格 DSL2 linter (nf-lang/v2)。此 linter 會在 `CreateWorkflow`和 期間執行`CreateWorkflowVersion`。它適用於所有支援的 DSL2 版本 (v22.04、v23.10、v24.10、v25.10 和 v26.04)。DSL1 工作流程不會鋪設。

linter 以非封鎖模式運作。Lint 調查結果不會阻止工作流程變為 ACTIVE。調查結果會在`GetWorkflow`回應的 `statusMessage` 欄位中顯示為結構化 JSON。

**注意**  
內建 linter 會在建立時驗證您的工作流程定義語法。它不同於 Nextflow v26.04 可用的嚴格語法*剖析器*，其由 控制`engineSettings.syntaxVersion`並影響執行時間行為。無論工作流程在執行時間使用哪個剖析器，linter 都會檢查建立時所有 DSL2 版本的語法。在 Nextflow v22.04、v23.10 和 v24.10 （舊版文法） 上，調查結果為諮詢。在 Nextflow v25.10 和 v26.04 上，調查結果反映嚴格的模式語法要求。

如需 lint 輸出格式以及如何解決問題清單的詳細資訊，請參閱 [HealthOmics 中的工作流程文字](workflows-linter.md)。

## 在 Nextflow 中有效率地使用暫存儲存
<a name="nextflow-scratch-storage"></a>

Nextflow 的`scratch`指令控制程序寫入其暫時工作檔案的位置。啟用暫時性儲存 (`scratchStorageMode: LOCAL`) 時，請使用 `scratch`指令將暫存 I/O 導向 的快速本機磁碟區`/tmp`。

下表說明 HealthOmics 中支援的`scratch`指令值及其行為：


| Value | HealthOmics 中的行為 | 建議 | 
| --- | --- | --- | 
| scratch true | 使用 $TMPDIR。當 scratchStorageMode為 時，抓取 I/O 會導向本機暫時性磁碟區LOCAL。 | 建議 | 
| scratch '/some/path' | 使用指定的常值路徑做為暫存目錄。若要使用暫時性儲存，請將路徑設定為 /tmp或 的子目錄/tmp。路徑必須存在於容器中且可寫入。 | 當路徑低於 時可運作 /tmp | 
| scratch 'ram-disk' | 嘗試使用 /dev/shm(RAM 中的 tmpfs)。這不建議用於 HealthOmics 中的本機暫存儲存。 | 不建議項目 | 

建議的方法是在程序定義`scratch true`中設定 ，其會自動使用 `$TMPDIR` 且不需要路徑組態：

```
process my_process {
    scratch true
    disk '200 GB'
    script:
    """
    my-tool --input ${input} --output ${output}
    """
}
```

如需暫時性儲存和 `disk` 指令的詳細資訊，請參閱 [HealthOmics 工作流程任務的暫時性儲存](workflows-ephemeral-storage.md)。