input:
path input_file
val name
val threshold
output:
path 'results.txt', emit: results
script:
"""
my_tool --name ${name} --threshold ${threshold} ${input_file}
"""
}
workflow MY_WORKFLOW {
my_task(
params.input_file,
params.name,
params.threshold
)
}
workflow {
MY_WORKFLOW()
}
```
------
#### [ CWL ]
```
cwlVersion: v1.2
class: Workflow
requirements:
InlineJavascriptRequirement: {}
inputs:
input_file: File
name: string
threshold: int
outputs:
result:
type: ...
outputSource: ...
steps:
my_task:
run:
class: CommandLineTool
baseCommand: my_tool
requirements:
...
inputs:
name:
type: string
inputBinding:
prefix: "--name"
threshold:
type: int
inputBinding:
prefix: "--threshold"
input_file:
type: File
inputBinding: {}
outputs:
results:
type: File
outputBinding:
glob: results.txt
```
------
# HealthOmics 工作流程的參數範本檔案
參數範本定義工作流程的輸入參數。您可以定義輸入參數，讓您的工作流程更具彈性和多樣化。例如，您可以為參考基因體檔案的 Amazon S3 位置定義參數。參數範本可以透過 Git 型儲存庫服務或本機磁碟機提供。然後，使用者可以使用各種資料集執行工作流程。
您可以為工作流程建立參數範本，或者 HealthOmics 可以為您產生參數範本。
參數範本是 JSON 檔案。在 檔案中，每個輸入參數都是具名物件，必須符合工作流程輸入的名稱。當您開始執行時，如果您未提供所有必要參數的值，則執行會失敗。
輸入參數物件包含下列屬性：
+ **description** – 此必要屬性是主控台顯示在**開始執行**頁面中的字串。此描述也會保留為執行中繼資料。
+ **optional** – 此選用屬性指出輸入參數是否為選用。如果您未指定 **optional** 欄位，則需要輸入參數。
下列參數範本範例示範如何指定輸入參數。
```
{
"myRequiredParameter1": {
"description": "this parameter is required",
},
"myRequiredParameter2": {
"description": "this parameter is also required",
"optional": false
},
"myOptionalParameter": {
"description": "this parameter is optional",
"optional": true
}
}
```
## 產生參數範本
HealthOmics 透過剖析工作流程定義來偵測輸入參數來產生參數範本。如果您提供工作流程的參數範本檔案，檔案中的參數會覆寫工作流程定義中偵測到的參數。
CWL、WDL 和 Nextflow 引擎的剖析邏輯之間有些微差異，如以下各節所述。
**Topics**
+ [CWL 的參數偵測](#parameter-parsing-cwl)
+ [WDL 的參數偵測](#parameter-parsing-wdl)
+ [Nextflow 的參數偵測](#parameter-parsing-nextflow)
### CWL 的參數偵測
在 CWL 工作流程引擎中，剖析邏輯會做出下列假設：
+ 任何 null 支援的類型都會標示為選用的輸入參數。
+ 任何非 Null 支援的類型都會標示為必要的輸入參數。
+ 任何具有預設值的參數都會標示為選用的輸入參數。
+ 描述會從`main`工作流程定義的 `label`區段擷取。如果`label`未指定 ，則描述將為空白 （空字串）。
下表顯示 CWL 插補範例。對於每個範例，參數名稱為 `x`。如果需要 參數，您必須提供 參數的值。如果 參數是選用的，則不需要提供值。
此資料表顯示基本類型的 CWL 插補範例。
| 輸入 | 輸入/輸出範例 | 必要 |
| --- | --- | --- |
| x:
type: int
| 1 或 2 或 ... | 是 |
| x:
type: int
default: 2
| 預設值為 2。有效輸入為 1 或 2 或 ... | 否 |
| x:
type: int?
| 有效輸入為無或 1 或 2 或 ... | 否 |
| x:
type: int?
default: 2
| 預設值為 2。有效輸入為無或 1 或 2 或 ... | 否 |
下表顯示複雜類型的 CWL 插補範例。複雜類型是基本類型的集合。
| 輸入 | 輸入/輸出範例 | 必要 |
| --- | --- | --- |
| x:
type: array
items: int
| 【】 或 【1，2，3】 | 是 |
| x:
type: array?
items: int
| 無 或 【】 或 【1，2，3】 | 否 |
| x:
type: array
items: int?
| 【】 或 【無、3、無】 | 是 |
| x:
type: array?
items: int?
| 【無】 或 無 或 【1，2，3】 或 【無，3】 但 【】 | 否 |
### WDL 的參數偵測
在 WDL 工作流程引擎中，剖析邏輯會做出下列假設：
+ 任何 null 支援的類型都會標示為選用的輸入參數。
+ 對於非 Null 支援的類型：
+ 任何指派常值或表達式的輸入變數都會標示為選用參數。例如：
```
Int x = 2
Float f0 = 1.0 + f1
```
+ 如果未將值或表達式指派給輸入參數，則會將其標記為必要參數。
+ 描述是從`main`工作流程定義`parameter_meta`中的 擷取。如果`parameter_meta`未指定 ，則描述將為空白 （空字串）。如需詳細資訊，請參閱[參數中繼資料](https://github.com/openwdl/wdl/blob/wdl-1.2/SPEC.md#metadata-sections)的 WDL 規格。
下表顯示 WDL 插補範例。對於每個範例，參數名稱為 `x`。如果需要 參數，您必須提供 參數的值。如果 參數是選用的，則不需要提供值。
此資料表顯示基本類型的 WDL 插補範例。
| 輸入 | 輸入/輸出範例 | 必要 |
| --- | --- | --- |
| Int x | 1 或 2 或 ... | 是 |
| Int x = 2 | 2 | 否 |
| Int x = 1\$12 | 3 | 否 |
| Int x = y\$1z | y\$1z | 否 |
| Int？ x | 無 或 1 或 2 或 ... | 是 |
| Int？ x = 2 | 無或 2 | 否 |
| Int？ x = 1\$12 | 無或 3 | 否 |
| Int？ x = y\$1z | 無或 y\$1z | 否 |
下表顯示複雜類型的 WDL 插補範例。複雜類型是基本類型的集合。
| 輸入 | 輸入/輸出範例 | 必要 |
| --- | --- | --- |
| Array【Int】 x | 【1，2，3】 或 【】 | 是 |
| Array【Int】\$1 x | 【1】，但不是 【】 | 是 |
| Array【Int】？ x | 無 或 【】 或 【1，2，3】 | 否 |
| Array【Int？】 x | 【】 或 【無、3、無】 | 是 |
| Array【Int？】=？ x | 【無】 或 無 或 【1，2，3】 或 【無，3】 但 【】 | 否 |
| 結構範例 \$1String a， Int y\$1 稍後在輸入中：mySample 範例 | String a = mySample.a
Int y = mySample.y
| 是 |
| 結構範例 \$1String a， Int y\$1 稍後在輸入中：Sample？ mySample | if (defined(mySample)) {
String a = mySample.a
Int y = mySample.y
} | 否 |
### Nextflow 的參數偵測
對於 Nextflow，HealthOmics 會剖析 `nextflow_schema.json` 檔案來產生參數範本。如果工作流程定義不包含結構描述檔案，HealthOmics 會剖析主要工作流程定義檔案。
**Topics**
+ [剖析結構描述檔案](#parameter-parsing-nextflow-schema)
+ [剖析主要檔案](#parameter-parsing-nextflow-main)
+ [巢狀參數](#parameter-parsing-nextflow-nested)
+ [Nextflow 插補的範例](#parameter-parsing-nextflow-examples)
#### 剖析結構描述檔案
若要讓剖析正常運作，請確定結構描述檔案符合下列要求：
+ 結構描述檔案名為 `nextflow_schema.json`，且位於與主要工作流程檔案相同的目錄中。
+ 結構描述檔案是有效的 JSON，如下列任一結構描述所定義：
+ https：//[json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)。
+ https：//[json-schema.org/draft-07/schema](https://json-schema.org/draft-07/schema)。
HealthOmics 會剖析`nextflow_schema.json`檔案以產生參數範本：
+ 擷取結構描述中**properties**定義的所有 。
+ **description** 如果 屬性可用，請包含 屬性。
+ 根據 屬性**required**的 欄位，識別每個參數是否為選用或必要。
下列範例顯示定義檔案和產生的參數檔案。
```
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"$defs": {
"input_options": {
"title": "Input options",
"type": "object",
"required": ["input_file"],
"properties": {
"input_file": {
"type": "string",
"format": "file-path",
"pattern": "^s3://[a-z0-9.-]{3,63}(?:/\\S*)?$",
"description": "description for input_file"
},
"input_num": {
"type": "integer",
"default": 42,
"description": "description for input_num"
}
}
},
"output_options": {
"title": "Output options",
"type": "object",
"required": ["output_dir"],
"properties": {
"output_dir": {
"type": "string",
"format": "file-path",
"description": "description for output_dir",
}
}
}
},
"properties": {
"ungrouped_input_bool": {
"type": "boolean",
"default": true
}
},
"required": ["ungrouped_input_bool"],
"allOf": [
{ "$ref": "#/$defs/input_options" },
{ "$ref": "#/$defs/output_options" }
]
}
```
產生的參數範本：
```
{
"input_file": {
"description": "description for input_file",
"optional": False
},
"input_num": {
"description": "description for input_num",
"optional": True
},
"output_dir": {
"description": "description for output_dir",
"optional": False
},
"ungrouped_input_bool": {
"description": None,
"optional": False
}
}
```
#### 剖析主要檔案
如果工作流程定義不包含`nextflow_schema.json`檔案，HealthOmics 會剖析主要工作流程定義檔案。
HealthOmics 會分析主要工作流程定義檔案和 `nextflow.config` 檔案中找到的`params`表達式。`params` 具有預設值的所有 都會標示為選用。
若要讓剖析正常運作，請注意下列需求：
+ HealthOmics 只會剖析主要工作流程定義檔案。為了確保擷取所有參數，建議您**params**將所有參數全部連接到任何子模組和匯入的工作流程。
+ 組態檔案是選用的。如果您定義一個，請命名它`nextflow.config`，並將其放在與主要工作流程定義檔案相同的目錄中。
下列範例顯示定義檔案和產生的參數範本。
```
params.input_file = "default.txt"
params.threads = 4
params.memory = "8GB"
workflow {
if (params.version) {
println "Using version: ${params.version}"
}
}
```
產生的參數範本：
```
{
"input_file": {
"description": None,
"optional": True
},
"threads": {
"description": None,
"optional": True
},
"memory": {
"description": None,
"optional": True
},
"version": {
"description": None,
"optional": False
}
}
```
對於 nextflow.config 中定義的預設值，HealthOmics 會收集在 中宣告的`params`指派和參數`params {}`，如下列範例所示。在指派陳述式中， `params` 必須出現在陳述式的左側。
```
params.alpha = "alpha"
params.beta = "beta"
params {
gamma = "gamma"
delta = "delta"
}
env {
// ignored, as this assignment isn't in the params block
VERSION = "TEST"
}
// ignored, as params is not on the left side
interpolated_image = "${params.cli_image}"
```
產生的參數範本：
```
{
// other params in your main workflow defintion
"alpha": {
"description": None,
"optional": True
},
"beta": {
"description": None,
"optional": True
},
"gamma": {
"description": None,
"optional": True
},
"delta": {
"description": None,
"optional": True
}
}
```
#### 巢狀參數
`nextflow_schema.json` 和 `nextflow.config` 允許巢狀參數。不過，HealthOmics 參數範本只需要最上層參數。如果您的工作流程使用巢狀參數，您必須提供 JSON 物件做為該參數的輸入。
##### 結構描述檔案中的巢狀參數
HealthOmics 會在剖析`nextflow_schema.json`檔案**params**時略過巢狀。例如，如果您定義下列`nextflow_schema.json`檔案：
```
{
"properties": {
"input": {
"properties": {
"input_file": { ... },
"input_num": { ... }
}
},
"input_bool": { ... }
}
}
```
HealthOmics 會在產生參數範本`input_num`時忽略 `input_file`和 ：
```
{
"input": {
"description": None,
"optional": True
},
"input_bool": {
"description": None,
"optional": True
}
}
```
當您執行此工作流程時，HealthOmics 預期會有類似下列`input.json`的檔案：
```
{
"input": {
"input_file": "s3://bucket/obj",
"input_num": 2
},
"input_bool": false
}
```
##### 組態檔案中的巢狀參數
HealthOmics 不會收集`nextflow.config`檔案中**params**的巢狀，並在剖析期間略過它們。例如，如果您定義下列`nextflow.config`檔案：
```
params.alpha = "alpha"
params.nested.beta = "beta"
params {
gamma = "gamma"
group {
delta = "delta"
}
}
```
HealthOmics 會在產生參數範本`params.group.delta`時忽略 `params.nested.beta`和 ：
```
{
"alpha": {
"description": None,
"optional": True
},
"gamma": {
"description": None,
"optional": True
}
}
```
#### Nextflow 插補的範例
下表顯示主檔案中參數的 Nextflow 插補範例。
| 參數 | 必要 |
| --- | --- |
| params.input\$1file | 是 |
| params.input\$1file = "s3：//bucket/data.json" | 否 |
| params.nested.input\$1file | N/A |
| params.nested.input\$1file = "s3：//bucket/data.json" | N/A |
下表顯示 `nextflow.config` 檔案中參數的 Nextflow 插補範例。
| 參數 | 必要 |
| --- | --- |
| params.input_file = "s3://bucket/data.json"
| 否 |
| params {
input_file = "s3://bucket/data.json"
} | 否 |
| params {
nested {
input_file = "s3://bucket/data.json"
}
} | N/A |
| input_file = params.input_file
| N/A |
# 私有工作流程的容器映像
HealthOmics 支援 Amazon ECR 私有儲存庫中託管的容器映像。您可以建立容器映像並將其上傳至私有儲存庫。您也可以使用 Amazon ECR 私有登錄檔做為提取快取，以同步上游登錄檔的內容。
您的 Amazon ECR 儲存庫必須與呼叫 服務的帳戶位於相同的 AWS 區域。只要來源映像儲存庫提供適當的許可，不同的 AWS 帳戶 就可以擁有容器映像。如需詳細資訊，請參閱[跨帳戶 Amazon ECR 存取的政策](permissions-ecr.md#permissions-cross-account)。
建議您將 Amazon ECR 容器映像 URIs定義為工作流程中的參數，以便在執行開始之前驗證存取權。變更區域參數也可讓您更輕鬆地在新區域中執行工作流程。
**注意**
HealthOmics 不支援 ARM 容器，也不支援存取公有儲存庫。
如需設定 HealthOmics 存取 Amazon ECR 的 IAM 許可的詳細資訊，請參閱 [HealthOmics 資源許可](permissions-resource.md)。
**Topics**
+ [與第三方容器登錄檔同步](#ecr-pull-through)
+ [Amazon ECR 容器映像的一般考量](#ecr-considerations)
+ [HealthOmics 工作流程的環境變數](#ecr-env-vars)
+ [在 Amazon ECR 容器映像中使用 Java](#ecr-java-considerations)
+ [將任務輸入新增至 Amazon ECR 容器映像](#ecr-tasks)
## 與第三方容器登錄檔同步
您可以使用 Amazon ECR 提取快取規則，將支援的上游登錄檔中的儲存庫與您的 Amazon ECR 私有儲存庫同步。如需詳細資訊，請參閱《*Amazon ECR 使用者指南*》中的[同步上游登錄](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html)檔。
當您建立快取時，提取快取會自動在私有登錄檔中建立映像儲存庫，並在上游映像發生變更時自動與快取映像同步。
HealthOmics 支援下列上游登錄檔的提取快取：
+ Amazon ECR Public
+ Kubernetes 容器映像登錄檔
+ Quay
+ Docker Hub
+ Microsoft Azure Container Registry
+ GitHub Container Registry
+ GitLab 容器登錄檔
HealthOmics 不支援為上游 Amazon ECR 私有儲存庫提取快取。
使用 Amazon ECR 提取快取的優勢包括：
1. 您不必手動將容器映像遷移至 Amazon ECR 或同步來自第三方儲存庫的更新。
1. 工作流程會存取私有儲存庫中的同步容器映像，這比在執行時間從公有登錄檔下載內容更為可靠。
1. 由於 Amazon ECR 提取快取使用可預測的 URI 結構，因此 HealthOmics 服務可以自動將 Amazon ECR 私有 URI 與上游登錄 URI 對應。您不需要在工作流程定義中更新和取代 URI 值。
**Topics**
+ [設定提取快取](#ecr-pull-through-configure)
+ [登錄檔映射](#ecr-pull-through-registry-mapping)
+ [影像映射](#ecr-pull-through-mapping-format)
### 設定提取快取
Amazon ECR AWS 帳戶 為每個區域中的 提供登錄檔。請務必在計劃執行工作流程的相同區域中建立 Amazon ECR 組態。
下列各節說明提取快取的組態任務。
**Topics**
+ [建立提取快取規則](#create-ecr-ptc)
+ [上游登錄檔的登錄檔許可](#reg-ecr-ptc)
+ [儲存庫建立範本](#repo-create-templates-ptc)
+ [建立工作流程](#reg-mapping-ecr-ptc)
#### 建立提取快取規則
針對具有您要快取之映像的每個上游登錄檔，建立 Amazon ECR 提取快取規則。規則指定上游登錄檔與 Amazon ECR 私有儲存庫之間的映射。
對於需要身分驗證的上游登錄檔，您可以使用 AWS Secrets Manager 提供您的登入資料。
**注意**
當作用中執行使用私有儲存庫時，請勿變更提取快取規則。執行可能會失敗，或者更關鍵地，可能會導致您的管道使用非預期的映像。
如需詳細資訊，請參閱《*Amazon Elastic Container Registry 使用者指南*》中的[建立提取快取規則](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html)。
##### 使用主控台建立提取快取規則
若要設定提取快取，請使用 Amazon ECR 主控台執行下列步驟：
1. 開啟 Amazon ECR 主控台：https：//https://console.aws.amazon.com/ecr
1. 在左側選單的**私有登錄**檔下，展開**功能和設定**。然後選擇**提取快取**。
1. 從**提取快取**頁面中，選擇**新增規則**。
1. 在**上游登錄**檔面板中，選擇要與您的私有登錄檔同步的上游登錄檔，然後選擇**下一步**。
1. 如果上游登錄檔需要身分驗證，主控台會開啟新頁面，您可以在其中指定包含登入資料的 SageMaker AI 秘密。選擇**下一步**。
1. 在**指定命名空間**下，在**快取命名空間**面板中，選擇使用特定儲存庫字首或沒有字首來建立私有儲存庫。如果您選擇使用字首，請在**快取儲存庫字首中指定字首**名稱。
1. 在**上游命名空間**面板中，選擇使用特定儲存庫字首或無字首從上游儲存庫提取。如果您選擇使用字首，請在**上游儲存庫字首中指定字首**名稱。
**命名空間範例**面板顯示提取請求、上游 URL 和所建立快取儲存庫的 URL 範例。
1. 選擇**下一步**。
1. 檢閱組態，然後選擇**建立**以建立規則。
如需詳細資訊，請參閱[建立提取快取規則 (AWS 管理主控台）](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html#pull-through-cache-creating-rule-console)。
##### 使用 CLI 建立提取快取規則
使用 Amazon ECR **create-pull-through-cache-rule**命令來建立提取快取規則。對於需要身分驗證的上游登錄檔，請將登入資料存放在 Secrets Manager 秘密中。
以下各節提供每個支援的上游登錄檔的範例。
##### 對於 Amazon ECR Public
下列範例會為 Amazon ECR Public 登錄檔建立提取快取規則。其會指定 `ecr-public` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `ecr-public/upstream-repository-name` 的命名規則。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix ecr-public \
--upstream-registry-url public.ecr.aws \
--region us-east-1
```
##### 對於 Kubernetes Container Registry
下列範例會為 Kubernetes 公有登錄檔建立提取快取規則。其會指定 `kubernetes` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `kubernetes/upstream-repository-name` 的命名規則。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix kubernetes \
--upstream-registry-url registry.k8s.io \
--region us-east-1
```
##### 對於 Quay
下列範例會為 Quay 公有登錄檔建立提取快取規則。其會指定 `quay` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `quay/upstream-repository-name` 的命名規則。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix quay \
--upstream-registry-url quay.io \
--region us-east-1
```
##### 對於 Docker Hub
下列範例會為 Docker Hub 登錄檔建立提取快取規則。其會指定 `docker-hub` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `docker-hub/upstream-repository-name` 的命名規則。您必須指定秘密包含 Docker Hub 憑證的完整 Amazon Resource Name (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix docker-hub \
--upstream-registry-url registry-1.docker.io \
--credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-1
```
##### 對於 GitHub Container Registry
下列範例會建立 GitHub Container Registry 的提取快取規則。其會指定 `github` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `github/upstream-repository-name` 的命名規則。您必須指定秘密包含 GitHub Container Registry 憑證的完整 Amazon Resource Name (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix github \
--upstream-registry-url ghcr.io \
--credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-1
```
##### 對於 Microsoft Azure Container Registry
下列範例會建立 Microsoft Azure Container Registry 的提取快取規則。其會指定 `azure` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `azure/upstream-repository-name` 的命名規則。您必須指定秘密包含 Microsoft Azure Container Registry 憑證的完整 Amazon Resource Name (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix azure \
--upstream-registry-url myregistry.azurecr.io \
--credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-1
```
##### 對於 GitLab 容器登錄檔
下列範例會建立 GitLab Container Registry 的提取快取規則。其會指定 `gitlab` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `gitlab/upstream-repository-name` 的命名規則。您必須指定包含 GitLab Container Registry 登入資料之秘密的完整 Amazon Resource Name (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix gitlab \
--upstream-registry-url registry.gitlab.com \
--credential-arn arn:aws:secretsmanager:us-east-1:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-1
```
如需詳細資訊，請參閱《*Amazon ECR 使用者指南*》中的[建立提取快取規則 (CLI)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html#pull-through-cache-creating-rule-cli)。
您可以使用 **get-run-task** CLI 命令來擷取用於特定任務之容器映像的相關資訊：
```
aws omics get-run-task --id 1234567 --task-id
```
輸出包含下列容器映像的相關資訊：
```
"imageDetails": {
"image": "string",
"imageDigest": "string",
"sourceImage": "string",
...
}
```
#### 上游登錄檔的登錄檔許可
使用登錄檔許可，以允許 HealthOmics 使用提取快取並將容器映像提取至 Amazon ECR 私有登錄檔。將 Amazon ECR 登錄檔政策新增至提供執行中所用容器的登錄檔。
下列政策會授予許可，讓 HealthOmics 服務建立具有指定提取快取字首的儲存庫 （以及啟動上游提取至這些儲存庫）。
1. 從 Amazon ECR 主控台開啟左側選單，在**私有登錄**檔下展開**登錄檔許可**，然後選擇**產生陳述式**。
1. 在右上角，選擇 JSON。輸入類似下列的政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowPTCinRegPermissions",
"Effect": "Allow",
"Principal": {
"Service": "omics.amazonaws.com"
},
"Action": [
"ecr:CreateRepository",
"ecr:BatchImportUpstreamImage"
],
"Resource": [
"arn:aws:ecr:us-east-1:123456789012:repository/ecr-public/*",
"arn:aws:ecr:us-east-1:123456789012:repository/docker-hub/*"
]
}
]
}
```
------
#### 儲存庫建立範本
若要在 HealthOmics 中使用提取快取，Amazon ECR 儲存庫必須具有儲存庫建立範本。當您或 Amazon ECR 為上游登錄檔建立私有儲存庫時，範本會定義 的組態設定。
每個範本都包含儲存庫命名空間字首，Amazon ECR 會使用此字首將新儲存庫與特定範本比對。範本會指定所有儲存庫設定的組態，包括資源型存取政策、標籤不可變性、加密和生命週期政策。
如需詳細資訊，請參閱《*Amazon Elastic Container Registry 使用者指南*》中的[儲存庫建立範本](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html)。
如何建立儲存庫建立範本：
1. 從 Amazon ECR 主控台開啟左側選單，在**私有登錄**檔下展開**功能和設定**。然後選擇**儲存庫建立範本**。
1. 選擇**建立範本**。
1. 在**範本詳細資訊**中，選擇**提取快取**。
1. 選擇將此範本套用至特定字首，還是套用至不符合其他範本的所有儲存庫。
如果您選擇**特定字首**，請在**字首**中輸入命名空間字首值。您在建立 PTC 規則時指定此字首。
1. 選擇**下一步**。
1. 在**新增儲存庫建立組態**頁面中，輸入**儲存庫許可**。使用其中一個範例政策陳述式，或輸入類似下列範例的範例：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "PTCRepoCreationTemplate",
"Effect": "Allow",
"Principal": {
"Service": "omics.amazonaws.com"
},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": "*"
}
]
}
```
------
1. 或者，您可以新增儲存庫設定，例如生命週期政策和標籤。Amazon ECR 會將這些規則套用至為提取使用指定字首的快取而建立的所有容器映像。
1. 選擇**下一步**。
1. 檢閱組態，然後選擇**下一步**。
#### 建立工作流程
當您建立新的工作流程或工作流程版本時，請檢閱登錄檔映射並視需要更新。如需詳細資訊，請參閱[建立私有工作流程](create-private-workflow.md)。
### 登錄檔映射
您可以定義登錄檔映射，以便在私有 Amazon ECR 登錄檔中的字首與上游登錄檔名稱之間進行映射。
如需 Amazon ECR 登錄檔映射的詳細資訊，請參閱[在 Amazon ECR 中建立提取快取規則](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html)。
下列範例顯示 Docker Hub、Quay 和 Amazon ECR Public 的登錄檔映射。
```
{
"registryMappings": [
{
"upstreamRegistryUrl": "registry-1.docker.io",
"ecrRepositoryPrefix": "docker-hub"
},
{
"upstreamRegistryUrl": "quay.io",
"ecrRepositoryPrefix": "quay"
},
{
"upstreamRegistryUrl": "public.ecr.aws",
"ecrRepositoryPrefix": "ecr-public"
}
]
}
```
### 影像映射
您可以定義映像映射，以在私有 Amazon ECR 工作流程中定義的映像名稱與上游登錄檔中的映像名稱之間進行映射。
您可以搭配支援提取快取的登錄檔使用映像映射。您也可以搭配上游登錄檔使用映像映射，其中 HealthOmics 不支援提取快取。您需要手動同步上游登錄檔與您的私有儲存庫。
如需 Amazon ECR 映像映射的詳細資訊，請參閱[在 Amazon ECR 中建立提取快取規則](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html)。
下列範例顯示從私有 Amazon ECR 映像到公有基因體映像和最新 Ubuntu 映像的映射。
```
{
"imageMappings": [
{
"sourceImage": "public.ecr.aws/aws-genomics/broadinstitute/gatk:4.6.0.2",
"destinationImage": "123456789012.dkr.ecr.us-east-1.amazonaws.com/broadinstitute/gatk:4.6.0.2"
},
{
"sourceImage": "ubuntu:latest",
"destinationImage": "123456789012.dkr.ecr.us-east-1.amazonaws.com/custom/ubuntu:latest",
}
]
}
```
## Amazon ECR 容器映像的一般考量
+ Architecture
HealthOmics 支援 x86\$164 容器。如果您的本機機器以 ARM 為基礎，例如 Apple Mac，請使用下列命令來建置 x86\$164 容器映像：
```
docker build --platform amd64 -t my_tool:latest .
```
+ 進入點和 shell
HealthOmics 工作流程引擎會將 bash 指令碼做為命令覆寫注入工作流程任務所使用的容器映像。因此，應該在沒有指定 ENTRYPOINT 的情況下建置容器映像，使得 bash shell 為預設值。
+ 掛載路徑
共用檔案系統掛載到位於 /tmp 的容器任務。此位置的容器映像內建的任何資料或工具都會遭到覆寫。
透過位於 /mnt/workflow 的唯讀掛載，工作流程定義可供任務使用。
+ 映像大小
如需容器映像大小上限[HealthOmics 工作流程固定大小配額](fixed-quotas.md#fixed-quotas-workflows)，請參閱 。
## HealthOmics 工作流程的環境變數
HealthOmics 提供環境變數，其中包含容器中執行之工作流程的相關資訊。您可以在工作流程任務的邏輯中使用這些變數的值。
所有 HealthOmics 工作流程變數都以 `AWS_WORKFLOW_`字首開頭。此字首是受保護的環境變數字首。請勿在工作流程容器中將此字首用於您自己的變數。
HealthOmics 提供下列工作流程環境變數：
**AWS\$1REGION**
此變數是容器執行所在的區域。
**AWS\$1WORKFLOW\$1RUN**
此變數是目前執行的名稱。
**AWS\$1WORKFLOW\$1RUN\$1ID**
此變數是目前執行的執行識別符。
**AWS\$1WORKFLOW\$1RUN\$1UUID**
此變數是目前執行的執行 UUID。
**AWS\$1WORKFLOW\$1TASK**
此變數是目前任務的名稱。
**AWS\$1WORKFLOW\$1TASK\$1ID**
此變數是目前任務的任務識別符。
**AWS\$1WORKFLOW\$1TASK\$1UUID**
此變數是目前任務的任務 UUID。
下列範例顯示每個環境變數的典型值：
```
AWS Region: us-east-1
Workflow Run: arn:aws:omics:us-east-1:123456789012:run/6470304
Workflow Run ID: 6470304
Workflow Run UUID: f4d9ed47-192e-760e-f3a8-13afedbd4937
Workflow Task: arn:aws:omics:us-east-1:123456789012:task/4192063
Workflow Task ID: 4192063
Workflow Task UUID: f0c9ed49-652c-4a38-7646-60ad835e0a2e
```
## 在 Amazon ECR 容器映像中使用 Java
如果工作流程任務使用 Java 應用程式，例如 GATK，請考慮容器的下列記憶體需求：
+ Java 應用程式使用堆疊記憶體和堆積記憶體。根據預設，堆積記憶體上限是容器中可用記憶體總數的百分比。此預設值取決於特定的 JVM 分佈和 JVM 版本，因此請參閱 JVM 的相關文件，或使用 Java 命令列選項 （例如 `-Xmx`) 明確設定堆積記憶體上限。
+ 請勿將堆積記憶體上限設定為容器記憶體配置的 100%，因為 JVM 堆疊也需要記憶體。JVM 垃圾收集器和容器內執行的任何其他作業系統程序也需要記憶體。
+ 有些 Java 應用程式，例如 GATK，可以使用原生方法叫用或其他最佳化，例如記憶體映射檔案。這些技術需要執行「關閉堆積」的記憶體配置，這些配置不受 JVM 最大堆積參數控制。
如果您知道 （或懷疑） Java 應用程式配置堆積外記憶體，請確定任務記憶體配置包含堆積外記憶體需求。
如果這些堆積外配置導致容器耗盡記憶體，您通常不會看到 Java **OutOfMemory**錯誤，因為 JVM 無法控制此記憶體。
## 將任務輸入新增至 Amazon ECR 容器映像
將執行工作流程任務所需的所有可執行檔、程式庫和指令碼新增至用於執行任務的 Amazon ECR 映像。
最佳實務是避免使用任務容器映像外部的指令碼、二進位檔和程式庫。這在使用將`bin`目錄做為`nf-core`工作流程套件一部分的工作流程時特別重要。雖然此目錄可供工作流程任務使用，但會掛載為唯讀目錄。此目錄中的必要資源應複製到任務映像中，並在執行時間或建置用於任務的容器映像時提供。
[HealthOmics 工作流程固定大小配額](fixed-quotas.md#fixed-quotas-workflows) 如需 HealthOmics 支援的容器映像大小上限，請參閱 。
# HealthOmics 工作流程 README 檔案
您可以上傳 README.md 檔案，其中包含工作流程的指示、圖表和重要資訊。每個工作流程版本都支援一個 README 檔案，您可以隨時更新。
**README 要求包括：**
+ README 檔案必須為 Markdown (.md) 格式
+ 檔案大小上限：500 KiB
**Topics**
+ [使用現有的 README](#workflows-add-readme)
+ [轉譯條件](#workflows-rendering-readme)
## 使用現有的 README
從 Git 儲存庫匯出READMEs 包含通常無法在儲存庫外部運作的相對連結。HealthOmics Git 整合會自動將這些連結轉換為絕對連結，以便在主控台中正確轉譯，無需手動 URL 更新。
對於從 Amazon S3 或本機磁碟機匯入READMEs，映像和連結必須使用公有 URLs 或更新其相對路徑，以進行適當的轉譯。
**注意**
必須公開託管映像，才能在 HealthOmics 主控台中顯示。存放在 GitHub Enterprise Server或 GitLab Self-Managed 儲存庫中的影像無法轉譯。
## 轉譯條件
HealthOmics 主控台會使用絕對路徑插入可公開存取的影像和連結。若要從私有儲存庫轉譯 URLs，使用者必須能夠存取儲存庫。對於使用自訂網域的 GitHub Enterprise Server或 GitLab Self-Managed 儲存庫，HealthOmics 無法解析存放在這些私有儲存庫中的相對連結或轉譯映像。
下表顯示 AWS 主控台 README 檢視支援的 Markdown 元素。
| Element | AWS 主控台 |
| --- | --- |
| Alerts (提醒) | 是，但沒有圖示 |
| 徽章 | 是 |
| 基本文字格式 | 是 |
| [程式碼區塊](https://www.markdownguide.org/basic-syntax/#code-blocks) | 是，但沒有[語法反白](https://www.markdownguide.org/extended-syntax/#syntax-highlighting)和複製按鈕功能 |
| 可摺疊區段 | 是 |
| [標題](https://www.markdownguide.org/basic-syntax/#headings) | 是 |
| [影像格式](https://www.markdownguide.org/basic-syntax/#images-1) | 是 |
| [影像 （可點選）](https://www.markdownguide.org/basic-syntax/#linking-images) | 是 |
| [換行](https://www.markdownguide.org/basic-syntax/#line-breaks) | 是 |
| 美人魚圖 | 只有 可以開啟圖形、移動圖形位置和複製程式碼 |
| 報價 | 是 |
| [下標](https://www.markdownguide.org/extended-syntax/#subscript)和[上標](https://www.markdownguide.org/extended-syntax/#superscript) | 是 |
| [資料表](https://www.markdownguide.org/extended-syntax/#tables) | 是，但不支援文字對齊 |
| 文字對齊 | 是 |
### 使用映像和連結 URLs
根據您的來源提供者，以下列格式建構頁面和映像的基本 URLs。
+ `{username}`：託管儲存庫的使用者名稱。
+ `{repo}`：儲存庫名稱。
+ `{ref}`：來源參考 （分支、標籤和遞交 ID)。
+ `{path}`：儲存庫中頁面或映像的檔案路徑。
| 來源提供者 | 頁面 URL | 影像 URL |
| --- | --- | --- |
| GitHub | https://github.com/\$1username\$1/\$1repo\$1/blob/\$1ref\$1/\$1path\$1 | `https://github.com/{username}/{repo}/blob/{ref}/{path}?raw=true` `https://raw.githubusercontent.com/{username}/{repo}/{ref}/{path}` |
| GitLab | https://gitlab.com/\$1username\$1/\$1repo\$1/-/blob/\$1ref\$1/\$1path\$1 | https://gitlab.com/\$1username\$1/\$1repo\$1/-/raw/\$1ref\$1/\$1path\$1 |
| Bitbucket | https://bitbucket.org/\$1username\$1/\$1repo\$1/src/\$1ref\$1/\$1path\$1 | https://bitbucket.org/\$1username\$1/\$1repo\$1/raw/\$1ref\$1/\$1path\$1 |
GitHubGitLab、 和 Bitbucket支援連結至公有儲存庫的頁面和映像 URLs。下表顯示每個來源提供者對私有儲存庫轉譯映像和連結 URLs的支援。
| 私有儲存庫支援 | 來源提供者 | 頁面 URL | 影像 URL |
| --- | --- | --- | --- |
| GitHub | 只能存取 儲存庫 | 否 |
| GitLab | 只能存取 儲存庫 | 否 |
| Bitbucket | 只能存取 儲存庫 | 否 |
# 請求私有工作流程的 Sentieon 授權
如果您的私有工作流程使用 Sentieon 軟體，您需要 Senieon 授權。請依照下列步驟請求和設定 Sentieon 軟體的授權：
+ 請求 Sentieon 授權
+ 傳送電子郵件至 Sentieon 支援群組 (support@sentieon.com) 以請求軟體授權。
+ 在電子郵件中提供 AWS 正式使用者 ID。
+ 請依照[這些指示](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#FindCanonicalId)尋找您的 AWS 正式使用者 ID。
+ 更新您的 HealthOmics 服務角色，以授予其存取您區域中的 Sentieon 授權伺服器代理和 Sentieon Omics 儲存貯體。下列範例會授予 中的存取權`us-east-1`。如有必要，請將此文字取代為您的 區域。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObjectAcl",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::omics-ap-us-east-1/*",
"arn:aws:s3:::sentieon-omics-license-us-east-1/*"
]
}
]
}
```
------
+ 產生 AWS 支援案例以存取 Sentieon 授權伺服器代理。
+ 若要建立支援案例，請導覽至 [ https：//support.console.aws.amazon.com。](https://support.console.aws.amazon.com)
+ 在支援案例中提供您的 AWS 帳戶 和 區域。您的帳戶會新增至授權伺服器代理的允許清單。
+ 使用 Sentieon 容器和 Sentieon 授權指令碼建置您的私有工作流程。
+ 如需在私有工作流程中使用 Sentieon 工具的其他說明，請參閱 GitHub 中的 [Sentieon-Amazon-Omics](https://github.com/Sentieon/sentieon-amazon-omics)。
+ Sentieon 軟體版本 202112.07 及更高版本支援 HealthOmics 授權伺服器代理。若要使用早於 202112.07 的 Sentieon 軟體版本，請聯絡 Sentieon 支援。
# HealthOmics 中的工作流程文字
建立工作流程之後，建議您先在工作流程上執行 linter，再開始第一次執行。linter 偵測到可能導致執行失敗的錯誤。
對於 WDL，HealthOmics 會在您建立工作流程時自動執行 linter。回應的 `statusMessage` 欄位提供 linter 輸出**get-workflow**。使用下列 CLI 命令擷取狀態輸出 （使用您建立之 WDL 工作流程的工作流程 ID)：
```
aws omics get-workflow
—id 123456
—query 'statusMessage'
```
HealthOmics 提供 linter，您可以在建立工作流程之前在工作流程棄用上執行。在您要遷移至 HealthOmics 的現有管道上執行這些文字。
+ **WDL** – 執行 [WDL linter](https://gallery.ecr.aws/aws-genomics/healthomics-linter) 的公有 Amazon ECR 映像。
+ **Nextflow** – 用於執行 [Nextflow Linter 規則的]( https://gallery.ecr.aws/aws-genomics/linter-rules-for-nextflow)公有 Amazon ECR 映像。您可以從 [GitHub](https://github.com/awslabs/linter-rules-for-nextflow) 存取此 linter 的原始碼。
+ **CWL** – 無法使用
# HealthOmics 工作流程操作
若要建立私有工作流程，您需要：
+ **Workflow definition file:** 以 WDL、 Nextflow或 編寫的工作流程定義檔案CWL。工作流程定義會指定使用工作流程之執行的輸入和輸出。它還包含工作流程執行和執行任務的規格，包括運算和記憶體需求。工作流程定義檔案必須為 `.zip` 格式。如需詳細資訊，請參閱 HealthOmics 中的[工作流程定義檔案](workflow-definition-files.md)。
+ 您可以使用 [Amazon Q CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/what-is.html) 在 WDL、Nextflow 和 CWL 中建置和驗證工作流程定義檔案。如需詳細資訊，請參閱 GitHub [上 Amazon Q CLI 的範例提示](getting-started.md#omics-q-prompts)和 [HealthOmics Agentic 生成式 AI 教學](https://github.com/aws-samples/aws-healthomics-tutorials/tree/main/generative-ai)課程。
+ **(Optional) Parameter template file:** 以 寫入的參數範本檔案JSON。建立 檔案以定義執行參數，或 HealthOmics 會為您產生參數範本。如需詳細資訊，請參閱 [ HealthOmics 工作流程的參數範本檔案](parameter-templates.md)。
+ **Amazon ECR container images:** 為工作流程中使用的每個容器建立私有 Amazon ECR 儲存庫。建立工作流程的容器映像，並將其存放在私有儲存庫中，或同步支援的上游登錄檔內容與您的 ECR 私有儲存庫。
+ **(Optional) Sentieon licenses:** 請求Sentieon授權以在私有工作流程中使用Sentieon軟體。
對於大於 4 MiB （壓縮） 的工作流程定義檔案，請在工作流程建立期間選擇下列其中一個選項：
+ 上傳至 Amazon Simple Storage Service 資料夾並指定位置。
+ 上傳至外部儲存庫 （大小上限為 1 GiB)，並指定儲存庫詳細資訊。
建立工作流程之後，您可以使用 `UpdateWorkflow`操作更新下列工作流程資訊：
+ 名稱
+ 描述
+ 預設儲存類型
+ 預設儲存容量 （具有工作流程 ID)
+ README.md 檔案
若要變更工作流程中的其他資訊，請建立新的工作流程或工作流程版本。
使用工作流程版本控制來組織和建構您的工作流程。版本也可協助您管理反覆工作流程更新的簡介。如需有關版本的詳細資訊，請參閱[建立工作流程版本](workflows-version-create.md)。
**Topics**
+ [建立私有工作流程](create-private-workflow.md)
+ [更新私有工作流程](update-private-workflow.md)
+ [刪除私有工作流程](delete-private-workflow.md)
+ [驗證工作流程狀態](using-get-workflow.md)
+ [從工作流程定義參考基因體檔案](create-ref-files.md)
# 建立私有工作流程
使用 HealthOmics 主控台、 AWS CLI 命令或其中一個 AWS SDKs建立工作流程。
**注意**
請勿在工作流程名稱中包含任何個人身分識別資訊 (PII)。這些名稱會顯示在 CloudWatch 日誌中。
當您建立工作流程時，HealthOmics 會將通用唯一識別碼 (UUID) 指派給工作流程。工作流程 UUID 是全域唯一識別符 (guid)，在工作流程和工作流程版本中是唯一的。基於資料來源目的，我們建議您使用工作流程 UUID 來唯一識別工作流程。
如果您的工作流程任務使用任何外部工具 （可執行檔、程式庫或指令碼），您可以將這些工具建置到容器映像中。您有下列選項來託管容器映像：
+ 在 ECR 私有登錄檔中託管容器映像。此選項的先決條件：
+ 建立 ECR 私有儲存庫，或選擇現有的儲存庫。
+ 如中所述設定 ECR 資源政策[Amazon ECR 許可](permissions-ecr.md)。
+ 將您的容器映像上傳至私有儲存庫。
+ 同步容器映像與支援的第三方登錄檔的內容。此選項的先決條件：
+ 在 ECR 私有登錄檔中，為每個上游登錄檔設定提取快取規則。如需詳細資訊，請參閱[影像映射](workflows-ecr.md#ecr-pull-through-mapping-format)。
+ 如中所述設定 ECR 資源政策[Amazon ECR 許可](permissions-ecr.md)。
+ 建立儲存庫建立範本。範本定義 Amazon ECR 為上游登錄檔建立私有儲存庫時的 設定。
+ 建立字首映射，將工作流程定義中的容器映像參考重新映射至 ECR 快取命名空間。
當您建立工作流程時，您會提供工作流程定義，其中包含工作流程、執行和任務的相關資訊。HealthOmics 可以將工作流程定義擷取為儲存在本機或 Amazon S3 儲存貯體中的 .zip 封存檔，或從支援的 Git 型儲存庫擷取。
**Topics**
+ [使用主控台建立工作流程](#console-create-workflows)
+ [使用 CLI 建立工作流程](#api-create-workflows)
+ [使用 SDK 建立工作流程](#sdk-create-workflows)
## 使用主控台建立工作流程
**建立工作流程的步驟**
1. 開啟 [HealthOmics 主控台](https://console.aws.amazon.com/omics/)。
1. 如有需要，請開啟左側導覽窗格 (≡)。選擇**私有工作流程**。
1. 在**私有工作流程**頁面上，選擇**建立工作流程**。
1. 在**定義工作流程**頁面上，提供下列資訊：
1. **工作流程名稱**：此工作流程的獨特名稱。建議您設定工作流程名稱，以在 AWS HealthOmics 主控台和 CloudWatch 日誌中組織您的執行。
1. **描述** （選用）：此工作流程的描述。
1. 在**工作流程定義**面板中，提供下列資訊：
1. **工作流程語言** （選用）：選取工作流程的規格語言。否則，HealthOmics 會從工作流程定義判斷語言。
1. 對於**工作流程定義來源**，選擇從 Git 型儲存庫、Amazon S3 位置或從本機磁碟機匯入定義資料夾。
1. 對於**從儲存庫服務匯入**：
**注意**
HealthOmics 支援 GitHub、、GitLab、Bitbucket、 的公有和私有儲存庫GitHub self-managedGitLab self-managed。
1. 選擇**連線**，將您的 AWS 資源連線至外部儲存庫。若要建立連線，請參閱 [與外部程式碼儲存庫連線](setting-up-new.md#setting-up-omics-repository)。
**注意**
TLV 區域中的客戶需要在 IAD(us-east-1) 區域中建立連線，才能建立工作流程。
1. 在**完整儲存庫 ID** 中，將您的儲存庫 ID 輸入為 user-name/repo-name。確認您有權存取此儲存庫中的檔案。
1. 在**來源參考** （選用） 中，輸入儲存庫來源參考 （分支、標籤或遞交 ID)。如果未指定來源參考，HealthOmics 會使用預設分支。
1. 在**排除檔案模式中**，輸入檔案模式以排除特定資料夾、檔案或副檔名。這有助於在匯入儲存庫檔案時管理資料大小。最多有 50 個模式，而且 修補程式必須遵循 [glob 模式語法](https://fossil-scm.org/home/doc/tip/www/globs.md)。例如：
1. `tests/`
1. `*.jpeg`
1. `large_data.zip`
1. 對於**從 S3 選取定義資料夾**：
1. 輸入包含壓縮工作流程定義資料夾的 Amazon S3 位置。Amazon S3 儲存貯體必須與工作流程位於相同的區域。
1. 如果您的帳戶沒有 Amazon S3 儲存貯體，請在 S3 儲存貯體擁有者 AWS 的帳戶 ID 中輸入儲存貯體擁有者的帳戶 ID。 **S3 ** 需要此資訊，以便 HealthOmics 可以驗證儲存貯體擁有權。
1. 對於**從本機來源選取定義資料夾**：
1. 輸入壓縮工作流程定義資料夾的本機磁碟機位置。
1. **主要工作流程定義檔案路徑** （選用）：輸入從壓縮工作流程定義資料夾或儲存庫到`main`檔案的檔案路徑。如果工作流程定義資料夾中只有一個檔案，或主要檔案名為「主要」，則不需要此參數。
1. 在 **README 檔案** （選用） 面板中，選取 **README 檔案的來源**，並提供下列資訊：
+ 對於**從儲存庫服務匯入**，在 **README 檔案路徑**中，輸入儲存庫中 README 檔案的路徑。
+ 針對**從 S3 選取檔案**，在 ** S3 的 README 檔案中**，輸入 README 檔案的 Amazon S3 URI。
+ 對於**從本機來源選取檔案**：在 **README - 選用**中，選擇**選擇檔案**以選取要上傳的 Markdown (.md) 檔案。
1. 在**預設執行儲存組態**面板中，為使用此工作流程的執行提供預設執行儲存類型和容量：
1. **執行儲存體類型**：選擇是否使用靜態或動態儲存體做為暫時執行儲存體的預設值。預設為靜態儲存。
1. **執行儲存容量** （選用）：對於靜態執行儲存類型，您可以輸入此工作流程所需的預設執行儲存量。此參數的預設值為 1200 GiB。您可以在開始執行時覆寫這些預設值。
1. **標籤 **（選用）：您最多可以將 50 個標籤與此工作流程建立關聯。
1. 選擇**下一步**。
1. 在**新增工作流程參數** （選用） 頁面上，選取**參數來源**：
1. 對於**從工作流程定義檔案剖析**，HealthOmics 會自動從工作流程定義檔案剖析工作流程參數。
1. 對於**從 Git 儲存庫提供參數範本**，請使用從儲存庫到參數範本檔案的路徑。
1. 對於**從本機來源選取 JSON 檔案**，請從指定參數的本機來源上傳JSON檔案。
1. 對於**手動輸入工作流程參數**，手動輸入參數名稱和描述。
1. 在**參數預覽**面板中，您可以檢閱或變更此工作流程版本的參數。如果您還原JSON檔案，則會遺失您所做的任何本機變更。
1. 選擇**下一步**。
1. 在**容器 URI 重新映射**頁面上的**映射規則**面板中，您可以定義工作流程的 URI 映射規則。
針對**映射檔案的來源**，選取下列其中一個選項：
+ **無** – 不需要映射規則。
+ **從 S3 選取 JSON 檔案** – 指定映射檔案的 S3 位置。
+ **從本機來源選取 JSON 檔案** – 在本機裝置上指定映射檔案位置。
+ **手動輸入映射** – 在映射面板中輸入登錄映射和映像**映射**。
1. 主控台會顯示**映射**面板。如果您選擇映射來源檔案，主控台會顯示檔案中的值。
1. 在**登錄檔映射**中，您可以編輯映射或新增映射 （最多 20 個登錄檔映射）。
每個登錄檔映射都包含下列欄位：
+ **上游登錄檔 URL** – 上游登錄檔的 URI。
+ **ECR 儲存庫字**首 – 要在 Amazon ECR 私有儲存庫中使用的儲存庫字首。
+ （選用） **上游儲存庫字首** – 上游登錄檔中儲存庫的字首。
+ （選用） **ECR 帳戶 ID** – 擁有上游容器映像之帳戶的帳戶 ID。
1. 在**影像映射**中，您可以編輯影像映射或新增映射 （最多 100 個影像映射）。
每個影像映射都包含下列欄位：
+ **來源映像** – 指定上游登錄檔中來源映像的 URI。
+ **目的地映像**：指定私有 Amazon ECR 登錄檔中對應映像的 URI。
1. 選擇**下一步**。
1. 檢閱工作流程組態，然後選擇**建立工作流程**。
## 使用 CLI 建立工作流程
如果您的工作流程檔案和參數範本檔案位於本機電腦上，您可以使用下列 CLI 命令建立工作流程。
```
aws omics create-workflow \
--name "my_workflow" \
--definition-zip fileb://my-definition.zip \
--parameter-template file://my-parameter-template.json
```
`create-workflow` 操作會傳回下列回應：
```
{
"arn": "arn:aws:omics:us-west-2:....",
"id": "1234567",
"status": "CREATING",
"tags": {
"resourceArn": "arn:aws:omics:us-west-2:...."
},
"uuid": "64c9a39e-8302-cc45-0262-2ea7116d854f"
}
```
### 建立工作流程時要使用的選用參數
您可以在建立工作流程時指定任何選用參數。如需語法詳細資訊，請參閱 AWS HealthOmics API 參考中的 [CreateWorkflow](https://docs.aws.amazon.com/omics/latest/api/API_CreateWorkflow.html)。
**Topics**
+ [指定工作流程定義 Amazon S3 位置](#create-defn-uri-parameter)
+ [使用 Git 型儲存庫中的工作流程定義](#create-defn-uri-git)
+ [指定讀我檔案](#specify-readme-file)
+ [指定**main**定義檔案](#create-main-parameter)
+ [指定執行儲存體類型](#create-run-storage-parameter)
+ [指定 GPU 組態](#create-accelerator-parameter)
+ [設定提取快取映射參數](#create-prefix-mapping-parameters)
#### 指定工作流程定義 Amazon S3 位置
如果您的工作流程定義檔案位於 Amazon S3 資料夾，請使用 `definition-uri` 參數指定位置，如下列範例所示。如果您的帳戶未擁有 Amazon S3 儲存貯體，請提供擁有者的 AWS 帳戶 ID。
```
aws omics create-workflow \
--name Test \
--definition-uri s3://omics-bucket/workflow-definition/ \
--owner-id 123456789012
...
```
#### 使用 Git 型儲存庫中的工作流程定義
若要從支援的 Git 型儲存庫使用工作流程定義，請在請求中使用 `definition-repository` 參數。請勿提供任何其他`definition`參數，因為如果請求包含多個輸入來源，則請求會失敗。
`definition-respository` 參數包含下列欄位：
+ **connectionArn** – Code Connection 的 ARN，可將您的 AWS 資源連線至外部儲存庫。
+ **fullRepositoryId** – 將儲存庫 ID 輸入為 `owner-name/repo-name`。確認您有權存取此儲存庫中的檔案。
+ **sourceReference** （選用） – 輸入儲存庫參考類型 (BRANCH、TAG 或 COMMIT) 和值。
如果您未指定來源參考，HealthOmics 會在預設分支上使用最新的遞交。
+ **excludeFilePatterns** （選用） – 輸入檔案模式以排除特定資料夾、檔案或副檔名。這有助於在匯入儲存庫檔案時管理資料大小。提供最多 50 個模式。模式必須遵循 [ glob 模式語法](https://fossil-scm.org/home/doc/tip/www/globs.md)。例如：
+ `tests/`
+ `*.jpeg`
+ `large_data.zip`
當您從 Git 型儲存庫指定工作流程定義時，請使用 `parameter-template-path` 指定參數範本檔案。如果您不提供此參數，HealthOmics 會建立沒有參數範本的工作流程。
下列範例顯示與 Git 型私有儲存庫內容相關的參數：
```
aws omics create-workflow \
--name custom-variant \
--description "Custom variant calling pipeline" \
--engine "WDL" \
--definition-repository '{
"connectionArn": "arn:aws:codeconnections:us-east-1:123456789012:connection/abcd1234-5678-90ab-cdef-1234567890ab",
"fullRepositoryId": "myorg/my-genomics-workflows",
"sourceReference": {
"type": "BRANCH",
"value": "main"
},
"excludeFilePatterns": ["tests/**", "*.log"]
}' \
--main "workflows/variant-calling/main.wdl" \
--parameter-template-path "parameters/variant-calling-params.json" \
--readme-path "docs/variant-calling-README.md" \
--storage-type "DYNAMIC" \
```
如需更多範例，請參閱部落格文章[如何從 Git 中的內容建立 AWS HealthOmics 工作流程](https://repost.aws/articles/ARCEN7AjhaRSmteczRoc_QsA/how-to-create-an-aws-healthomics-workflows-from-content-in-git)。
#### 指定讀我檔案
您可以使用下列其中一個參數來指定 README 檔案位置：
+ **readme-markdown** – 字串輸入或本機電腦上的檔案。
+ **readme-uri** – 存放在 S3 上的檔案的 URI。
+ **readme-path ** – 儲存庫中 README 檔案的路徑。
僅使用 readme-path 搭配 **definition-respository**。如果您未指定任何 README 參數，HealthOmics 會在儲存庫中匯入根層級 README.md 檔案 （如果存在）。
下列範例示範如何使用 readme-path 和 readme-uri 指定 README 檔案位置。
```
# Using README from repository
aws omics create-workflow \
--name "documented-workflow" \
--definition-repository '...' \
--readme-path "docs/workflow-guide.md"
# Using README from S3
aws omics create-workflow \
--name "s3-readme-workflow" \
--definition-repository '...' \
--readme-uri "s3://my-bucket/workflow-docs/readme.md"
```
如需詳細資訊，請參閱[HealthOmics 工作流程 README 檔案](workflows-readme.md)。
#### 指定**main**定義檔案
如果您包含多個工作流程定義檔案，請使用 `main` 參數來指定工作流程的主要定義檔案。
```
aws omics create-workflow \
--name Test \
--main multi_workflow/workflow2.wdl \
...
```
#### 指定執行儲存體類型
您可以指定預設執行儲存類型 (DYNAMIC 或 STATIC)，並執行儲存容量 （靜態儲存需要）。如需執行儲存體類型的詳細資訊，請參閱 [在 HealthOmics 工作流程中執行儲存類型](workflows-run-types.md)。
```
aws omics create-workflow \
--name my_workflow \
--definition-zip fileb://my-definition.zip \
--parameter-template file://my-parameter-template.json \
--storage-type 'STATIC' \
--storage-capacity 1200 \
```
#### 指定 GPU 組態
使用 加速器參數來建立在加速運算執行個體上執行的工作流程。下列範例示範如何使用 `accelerators` 參數。您可以在工作流程定義中指定 GPU 組態。請參閱 [加速運算執行個體](memory-and-compute-tasks.md#workflow-task-accelerated-computing-instances)。
```
aws omics create-workflow --name workflow name \
--definition-uri s3://amzn-s3-demo-bucket1/GPUWorkflow.zip \
--accelerators GPU
```
#### 設定提取快取映射參數
如果您使用 Amazon ECR 提取快取映射功能，您可以覆寫預設映射。如需容器設定參數的詳細資訊，請參閱 [私有工作流程的容器映像](workflows-ecr.md)。
在下列範例中， 檔案`mappings.json`包含此內容：
```
{
"registryMappings": [
{
"upstreamRegistryUrl": "registry-1.docker.io",
"ecrRepositoryPrefix": "docker-hub"
},
{
"upstreamRegistryUrl": "quay.io",
"ecrRepositoryPrefix": "quay",
"accountId": "123412341234"
},
{
"upstreamRegistryUrl": "public.ecr.aws",
"ecrRepositoryPrefix": "ecr-public"
}
],
"imageMappings": [{
"sourceImage": "docker.io/library/ubuntu:latest",
"destinationImage": "healthomics-docker-2/custom/ubuntu:latest",
"accountId": "123412341234"
},
{
"sourceImage": "nvcr.io/nvidia/k8s/dcgm-exporter",
"destinationImage": "healthomics-nvidia/k8s/dcgm-exporter"
}
]
}
```
在 create-workflow 命令中指定映射參數：
```
aws omics create-workflow \
...
--container-registry-map-file file://mappings.json
...
```
您也可以指定映射參數檔案的 S3 位置：
```
aws omics create-workflow \
...
--container-registry-map-uri s3://amzn-s3-demo-bucket1/test.zip
...
```
## 使用 SDK 建立工作流程
您可以使用其中一個 SDKs建立工作流程。下列範例示範如何使用 Python SDK 建立工作流程
```
import boto3
omics = boto3.client('omics')
with open('definition.zip', 'rb') as f:
definition = f.read()
response = omics.create_workflow(
name='my_workflow',
definitionZip=definition,
parameterTemplate={ ... }
)
```
# 更新私有工作流程
您可以使用 HealthOmics 主控台、 AWS CLI 命令或其中一個 AWS SDKs 來更新工作流程。
**注意**
請勿在工作流程名稱中包含任何個人身分識別資訊 (PII)。這些名稱會顯示在 CloudWatch 日誌中。
**Topics**
+ [使用主控台更新工作流程](#console-update-workflows)
+ [使用 CLI 更新工作流程](#api-update-workflows)
+ [使用 SDK 更新工作流程](#sdk-update-workflows)
## 使用主控台更新工作流程
**更新工作流程的步驟**
1. 開啟 [HealthOmics 主控台](https://console.aws.amazon.com/omics/)。
1. 如有需要，請開啟左側導覽窗格 (≡)。選擇**私有工作流程**。
1. 在**私有工作流程**頁面上，選擇要更新的工作流程。
1. 在**工作流程**頁面上：
+ 如果工作流程有版本，請確定您選取**預設版本**。
+ 從**動作**清單中選擇**編輯**。
1. 在**編輯工作流程**頁面上，您可以變更下列任何值：
+ **工作流程名稱**。
+ **工作流程描述**。
+ 工作流程的預設**執行儲存類型**。
+ 預設**執行儲存容量** （如果執行儲存類型是靜態儲存）。如需預設執行儲存組態的詳細資訊，請參閱 [使用主控台建立工作流程](create-private-workflow.md#console-create-workflows)。
1. 選擇**儲存變更**以套用變更。
## 使用 CLI 更新工作流程
如下列範例所示，您可以更新工作流程名稱和描述。您也可以變更預設執行儲存類型 (STATIC 或 DYNAMIC)，並執行儲存容量 （適用於靜態儲存類型）。如需執行儲存體類型的詳細資訊，請參閱 [在 HealthOmics 工作流程中執行儲存類型](workflows-run-types.md)。
```
aws omics update-workflow \
--id 1234567 \
--name my_workflow \
--description "updated workflow" \
--storage-type 'STATIC' \
--storage-capacity 1200
```
您不會收到對`update-workflow`請求的回應。
## 使用 SDK 更新工作流程
您可以使用其中一個 SDKs更新工作流程。
下列範例示範如何使用 Python SDK 更新工作流程
```
import boto3
omics = boto3.client('omics')
response = omics.update_workflow(
name='my_workflow',
description='updated workflow'
)
```
# 刪除私有工作流程
當您不再需要工作流程時，您可以使用 HealthOmics 主控台、 AWS CLI 命令或其中一個 AWS SDKs 將其刪除。您可以刪除符合下列條件的工作流程：
+ 其狀態為 ACTIVE 或 FAILED。
+ 它沒有作用中的共享。
+ 您已刪除所有工作流程版本。
刪除工作流程不會影響任何使用工作流程的持續執行。
**Topics**
+ [使用主控台刪除工作流程](#console-delete-workflows)
+ [使用 CLI 刪除工作流程](#api-delete-workflows)
+ [使用 SDK 刪除工作流程](#sdk-delete-workflows)
## 使用主控台刪除工作流程
**刪除工作流程**
1. 開啟 [HealthOmics 主控台](https://console.aws.amazon.com/omics/)。
1. 如有需要，請開啟左側導覽窗格 (≡)。選擇**私有工作流程**。
1. 在**私有工作流程**頁面上，選擇要刪除的工作流程。
1. 在**工作流程**頁面上，選擇**動作**清單中**選取的刪除**。
1. 在**刪除工作流程**模態中，輸入「確認」以確認刪除。
1. 選擇 **刪除**。
## 使用 CLI 刪除工作流程
下列範例示範如何使用 AWS CLI 命令來刪除工作流程。若要執行範例，`workflow id`請以您要刪除的工作流程 ID 取代 。
```
aws omics delete-workflow
--id workflow id
```
HealthOmics 不會傳送回應給`delete-workflow`請求。
## 使用 SDK 刪除工作流程
您可以使用其中一個 SDKs刪除工作流程。
下列範例示範如何使用 Python SDK 刪除工作流程。
```
import boto3
omics = boto3.client('omics')
response = omics.delete_workflow(
id='1234567'
)
```
# 驗證工作流程狀態
建立工作流程後，您可以使用 **get-workflow** 驗證狀態並檢視工作流程的其他詳細資訊，如下所示。
```
aws omics get-workflow --id 1234567
```
回應包含工作流程詳細資訊，包括狀態，如下所示。
```
{
"arn": "arn:aws:omics:us-west-2:....",
"creationTime": "2022-07-06T00:27:05.542459"
"id": "1234567",
"engine": "WDL",
"status": "ACTIVE",
"type": "PRIVATE",
"main": "workflow-crambam.wdl",
"name": "workflow_name",
"storageType": "STATIC",
"storageCapacity": "1200",
"uuid": "64c9a39e-8302-cc45-0262-2ea7116d854f"
}
```
在狀態轉換為 之後，您可以使用此工作流程開始執行`ACTIVE`。
# 從工作流程定義參考基因體檔案
HealthOmics 參考存放區物件可以使用如下的 URI 來參考。在指示`reference ID`的地方使用您自己的 `reference store ID`、 `account ID`和 。
```
omics://account ID.storage.us-west-2.amazonaws.com/reference store id/reference/id
```
有些工作流程需要參考基因體的 `SOURCE`和 `INDEX` 檔案。先前的 URI 是預設的短格式，並將預設為 SOURCE 檔案。若要指定任一檔案，您可以使用長 URI 表單，如下所示。
```
omics://account ID.storage.us-west-2.amazonaws.com/reference store id/reference/id/source
omics://account ID.storage.us-west-2.amazonaws.com/reference store id/reference/id/index
```
使用序列讀取集會有類似的模式，如下所示。
```
aws omics create-workflow \
--name workflow name \
--main sample workflow.wdl \
--definition-uri omics://account ID.storage.us-west-2.amazonaws.com/sequence_store_id/readSet/id \
--parameter-template file://parameters_sample_description.json
```
有些讀取集，例如以 FASTQ 為基礎的讀取集，可以包含配對的讀取。在下列範例中，它們稱為 SOURCE1 和 SOURCE2。BAM 和 CRAM 等格式只會有 SOURCE1 檔案。有些讀取集將包含 INDEX 檔案，例如 `bai`或 `crai` 檔案。上述 URI 是預設的短格式，預設為 SOURCE1 檔案。若要指定確切的檔案或索引，您可以使用長 URI 表單，如下所示。
```
omics://123456789012.storage.us-west-2.amazonaws.com//readSet//source1
omics://123456789012.storage.us-west-2.amazonaws.com//readSet//source2
omics://123456789012.storage.us-west-2.amazonaws.com//readSet//index
```
以下是使用兩個 Omics 儲存 URIs 的輸入 JSON 檔案範例。
```
{
"input_fasta": "omics://123456789012.storage.us-west-2.amazonaws.com//reference/",
"input_cram": "omics://123456789012.storage.us-west-2.amazonaws.com//readSet/"
}
```
將 `--inputs file://`新增至您的**開始執行**請求 AWS CLI ，以參考 中的輸入 JSON 檔案。