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

Nextflow 工作流程定義詳細資訊

HealthOmics 支援 Nextflow DSL1 和 DSL2。如需詳細資訊，請參閱Nextflow 版本支援。

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

使用 nf-schema 和 nf-validation 外掛程式

HealthOmics 為 Nextflow 外掛程式提供下列支援：

指定儲存 URIs

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

HealthOmics 部分支援在 Amazon S3 URIs 或 HealthOmics 儲存 URIs 中使用 glob 模式。在工作流程定義中使用 Glob 模式來建立 path或 file頻道。如需預期的行為和確切案例，請參閱 Amazon S3 輸入中 Glob 模式的下一個流程處理。

Nextflow 指令

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

使用 的任務重試策略 errorStrategy

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

process {
    label 'my_label'
    errorStrategy 'retry'

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

如需有關 HealthOmics 在執行期間如何處理任務重試的資訊，請參閱 任務重試。

使用 的任務重試嘗試 maxRetries

根據預設，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

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

您可以設定 omicsRetryOn5xx以選擇退出任務重試服務錯誤。如需 HealthOmics 中任務重試的詳細資訊，請參閱 任務重試。

下列範例會在全域組態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指令的任務持續時間

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

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

如需 Nextflow 時間指令的詳細資訊，請參閱 Nextflow 參考中的時間指令。

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

使用下列一或多個單位指定逾時持續時間：ms、mh、 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 設定檔

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 引擎設定。

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 版本，設定檔會按照組態檔案中定義的順序套用，而不是命令列順序。

注意下列事項：

匯出工作流程層級內容

對於 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/"
}

匯出任務內容

對於以 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，您可以使用工作流程輸出來匯出任務內容。下列範例示範如何定義工作流程output區塊，將任務結果匯出至 Amazon S3。

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 文件中的工作流程輸出。

產生 Nextflow 執行報告

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

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 會將在 下寫入執行 Amazon S3 輸出位置/mnt/workflow/output/字output/首的檔案匯出。如需此匯出路徑的詳細資訊，請參閱 匯出工作流程層級內容。寫入外部的報告/mnt/workflow/output/不會匯出至執行的 Amazon S3 輸出位置。

指定 Nextflow 語法版本

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

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

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

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

工作流程建立期間的自動語法驗證

當您建立或更新 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。

如需 lint 輸出格式以及如何解決問題清單的詳細資訊，請參閱 HealthOmics 中的工作流程文字。

在 Nextflow 中有效率地使用暫存儲存

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

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

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

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

如需暫時性儲存和 disk指令的詳細資訊，請參閱 HealthOmics 工作流程任務的暫時性儲存。

Nextflow v26.04 版本備註

下表摘要說明 HealthOmics 對 Nextflow 26.04 版中發行的新功能、增強功能和取代的支援。

新功能和增強功能

棄用