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 类型都被标记为必填的输入参数。
+ 任何具有默认值的参数都被标记为可选的输入参数。
+ 描述是从`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 工作流引擎中，解析逻辑做出了以下假设：
+ 任何支持为空的类型都被标记为可选的输入参数。
+ 对于支持不可为空的类型：
+ 任何具有字面值或表达式赋值的输入变量都被标记为可选参数。例如：
```
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 插值示例。
| 输入 | 输入/输出示例 | 必需 |
| --- | --- | --- |
| 整数 x | 1 或 2 或... | 是 |
| 整数 x = 2 | 2 | 否 |
| Int x = 1\$12 | 3 | 否 |
| 整数 x = y\$1z | y\$1z | 否 |
| 整数？ x | 无、1 或 2 或... | 是 |
| 整数？ x = 2 | 无或 2 | 否 |
| 整数？ x = 1\$12 | 无或 3 | 否 |
| 整数？ x = y\$1z | 无或 y\$1z | 否 |
下表显示了复杂类型的 WDL 插值示例。复杂类型是原始类型的集合。
| 输入 | 输入/输出示例 | 必需 |
| --- | --- | --- |
| 数组 [整数] x | [1,2,3] 或 [] | 是 |
| 数组 [整数] \$1 x | [1]，但不是 [] | 是 |
| 数组 [整数]？ x | 无或 [] 或 [1,2,3] | 否 |
| 数组 [整数？] x | [] 或 [无、3、无] | 是 |
| 数组 [整数？] =？ x | [无] 或 “无” 或 [1,2,3] 或 [无，3] 但不是 [] | 否 |
| 结构示例 \$1字符串 a，整数 y\$1 稍后在输入中：示例 mySample | String a = mySample.a
Int y = mySample.y
| 是 |
| 结构示例 \$1字符串 a，整数 y\$1 稍后在输入中：样本？ 我的样本 | 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，如以下任一架构所定义：
+ [json 架构。 org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)。
+ [json 架构。 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 分析在主工作流定义文件和文件中找到的`params``nextflow.config`表达式。所有`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 解析文件**params**时会跳过嵌套。`nextflow_schema.json`例如，如果您定义了以下`nextflow_schema.json`文件：
```
{
"properties": {
"input": {
"properties": {
"input_file": { ... },
"input_num": { ... }
}
},
"input_bool": { ... }
}
}
```
HealthOmics 忽略`input_file`，`input_num`当它生成参数模板时：
```
{
"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 不收集嵌套**params**在`nextflow.config`文件中，并在解析过程中跳过它们。例如，如果您定义了以下`nextflow.config`文件：
```
params.alpha = "alpha"
params.nested.beta = "beta"
params {
gamma = "gamma"
group {
delta = "delta"
}
}
```
HealthOmics 忽略`params.nested.beta`，`params.group.delta`当它生成参数模板时：
```
{
"alpha": {
"description": None,
"optional": True
},
"gamma": {
"description": None,
"optional": True
}
}
```
#### Nextflow 插值示例
下表显示了主文件中参数的 Nextflow 插值示例。
| 参数 | 必需 |
| --- | --- |
| params.input\$1fil | 是 |
| params.input\$1file = “s3://bucket/data.json” | 否 |
| params.nested.input\$1file | 不适用 |
| params.nested.input\$1file = “s3://bucket/data.json” | 不适用 |
下表显示了文件中参数的 Nextflow 插值示例。`nextflow.config`
| 参数 | 必需 |
| --- | --- |
| params.input_file = "s3://bucket/data.json"
| 否 |
| params {
input_file = "s3://bucket/data.json"
} | 否 |
| params {
nested {
input_file = "s3://bucket/data.json"
}
} | 不适用 |
| input_file = params.input_file
| 不适用 |
# 私有工作流程的容器镜像
HealthOmics 支持托管在 Amazon ECR 私有存储库中的容器映像。您可以创建容器镜像并将其上传到私有存储库。您还可以使用您的 Amazon ECR 私有注册表作为直通缓存，以同步上游注册表的内容。
您的 Amazon ECR 存储库必须与调用该服务的账户位于同一 AWS 区域。只要源镜像存储库提供适当的权限，其他人 AWS 账户 就可以拥有容器镜像。有关更多信息，请参阅 [跨账户 Amazon ECR 访问政策](permissions-ecr.md#permissions-cross-account)。
我们建议您将您的 Amazon ECR 容器映 URIs 像定义为工作流程中的参数，以便在运行开始之前可以验证访问权限。通过更改 Region 参数，还可以更轻松地在新区域中运行工作流程。
**注意**
HealthOmics 不支持 ARM 容器，也不支持访问公共仓库。
有关为访问 Amazon ECR 配置 IAM 权限的信息，请参阅[HealthOmics 资源权限](permissions-resource.md)。 HealthOmics
**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 容器注册表
+ GitHub 容器注册表
+ 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://console.aws.amazon.com/ecr
1. 在左侧菜单的 “**私有注册表**” 下，展开 “**功能和设置”**。然后选择 P **ull through cache**。
1. 从 P **ull through 缓存**页面中，选择**添加规则**。
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 公有注册表创建一个缓存提取规则。它指定了存储库前缀 `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 容器注册表
以下示例为 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 资源名称（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 容器注册表
以下示例为 GitHub 容器注册表创建了通过缓存规则。它指定了存储库前缀 `github`，这导致使用缓存提取规则创建的每个存储库都具有 `github/upstream-repository-name` 命名方案。您必须指定包含您的 GitHub 容器注册凭证的密钥的完整 Amazon 资源名称 (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 容器注册表
以下示例为 Microsoft Azure 容器注册表创建了一个缓存提取规则。它指定了存储库前缀 `azure`，这导致使用缓存提取规则创建的每个存储库都具有 `azure/upstream-repository-name` 命名方案。您必须指定包含 Microsoft Azure 容器注册表凭证的密钥的完整 Amazon 资源名称（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 容器注册表创建了通过缓存规则。它指定了存储库前缀 `gitlab`，这导致使用缓存提取规则创建的每个存储库都具有 `gitlab/upstream-repository-name` 命名方案。您必须指定包含您的 GitLab 容器注册凭证的密钥的完整 Amazon 资源名称 (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 弹性容器注册表用户指南*中的[存储库创建模板](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 注册表映射的更多信息，请参阅在 A [mazon 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 图像映射的更多信息，请参阅在 A [mazon 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 容器镜像的一般注意事项
+ 架构
HealthOmics 支持 x86\$164 容器。如果您的本地计算机基于 ARM，例如 Apple Mac，请使用以下命令来构建 x86\$164 容器镜像：
```
docker build --platform amd64 -t my_tool:latest .
```
+ 入口点和外壳
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\$1任务**
此变量是当前任务的名称。
**AWS\$1WORKFLOW\$1任务\$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.md 文件，其中包含工作流程的说明、图表和基本信息。每个工作流程版本都支持一个 README 文件，您可以随时更新该文件。
**自述文件要求包括：**
+ 自述文件必须采用 markdown (.md) 格式
+ 最大文件大小：500 KiB
**Topics**
+ [使用现有的自述文件](#workflows-add-readme)
+ [渲染条件](#workflows-rendering-readme)
## 使用现有的自述文件
READMEs 从 Git 存储库导出的内容包含相对链接，这些链接通常在仓库之外不起作用。 HealthOmics Git 集成会自动将这些链接转换为绝对链接，以便在控制台中正确呈现，无需手动更新 URL。
对于从 Amazon S3 或本地驱动器 READMEs 导入的图像和链接，必须使用公共文件 URLs 或更新其相对路径才能正确呈现。
**注意**
图片必须公开托管才能显示在 HealthOmics 控制台中。存储在GitHub Enterprise Server或存储GitLab Self-Managed库中的图像无法呈现。
## 渲染条件
HealthOmics 控制台使用绝对路径插值可公开访问的图像和链接。要 URLs 从私有仓库进行渲染，用户必须有权访问存储库。对于GitHub Enterprise Server或使用自定义域名的GitLab Self-Managed存储库， HealthOmics 无法解析相对链接，也无法呈现存储在这些私有存储库中的图像。
下表显示了 AWS 控制台自述文件视图支持的 markdown 元素。
| 元素 | AWS 控制台 |
| --- | --- |
| 警报 | 是的，但没有图标 |
| 徽章 | 是 |
| 基本文本格式 | 是 |
| [代码块](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/#subscript) | 是 |
| [表](https://www.markdownguide.org/extended-syntax/#tables) | 是，但不支持文本对齐 |
| 文本对齐方式 | 是 |
### 使用图片和链接 URLs
根据您的来源提供商，请按以下格式构建页面和图像的基础 URLs 。
+ `{username}`：存储库所在的用户名。
+ `{repo}`：存储库名称。
+ `{ref}`: 源引用（分支、标签和提交 ID）。
+ `{path}`：存储库中页面或图像的文件路径。
| 源提供商 | 页面网址 | 图片网址 |
| --- | --- | --- |
| 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 的支持。
| 私有存储库支持 | 源提供商 | 页面网址 | 图片网址 |
| --- | --- | --- | --- |
| 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 许可证服务器代理的访问权限。
+ 要创建支持案例，请导航至 [support.console.aws.](https://support.console.aws.amazon.com) amazon.com。
+ 在支持案例中提供您的 AWS 账户 和区域。您的帐户已添加到许可服务器代理的许可名单中。
+ 使用 Sentieon 容器和 Sentieon 许可证脚本构建您的私有工作流程。
+ 有关在私有工作流程中使用 Sentieon 工具的其他说明，请参阅中的 S [en](https://github.com/Sentieon/sentieon-amazon-omics) tieon-Amazon-Omics。 GitHub
+ Sentieon 软件版本 202112.07 及更高版本支持许可服务器代理。 HealthOmics 要使用 202112.07 之前的 Sentieon 软件版本，请联系 Sentieon 支持人员。
# 中的工作流程提示 HealthOmics
创建工作流程后，我们建议您在开始第一次运行之前对该工作流程运行 linter。linter 会检测可能导致运行失败的错误。
对于 WDL，在创建工作流程时 HealthOmics 会自动运行 linter。linter 输出可在**get-workflow**响应的`statusMessage`字段中找到。使用以下 CLI 命令检索状态输出（使用您创建的 WDL 工作流程的工作流 ID）：
```
aws omics get-workflow
—id 123456
—query 'statusMessage'
```
HealthOmics 提供了可以在创建工作流程之前在工作流程定义上运行的 linter。在要迁移到的现有管道上运行这些 linter。 HealthOmics
+ **WDL**— 用于运行 [WDL l](https://gallery.ecr.aws/aws-genomics/healthomics-linter) inter 的公共 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`格式。有关更多信息，请参阅中的[工作流定义文件](workflow-definition-files.md) HealthOmics。
+ 您可以使用 [Amazon Q CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/what-is.html) 在 WDL、Nextflow 和 CWL 中构建和验证您的工作流程定义文件。有关更多信息，请参阅 [Amazon Q CLI 的示例提示](getting-started.md#omics-q-prompts)和上 GitHub的 A [HealthOmics gentic 生成人工智能教程](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 简单存储服务文件夹并指定位置。
+ 上传到外部存储库（最大大小 1 GiB）并指定存储库的详细信息。
创建工作流程后，您可以通过该`UpdateWorkflow`操作更新以下工作流信息：
+ Name
+ 描述
+ 默认存储类型
+ 默认存储容量（带工作流程 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、GitLabBitbucket、GitHub self-managed的公有和私有存储库GitLab self-managed。
1. 选择一个**连接**，将您的 AWS 资源连接到外部存储库。要创建连接，请参阅[Connect 连接外部代码存储库](setting-up-new.md#setting-up-omics-repository)。
**注意**
该TLV地区的客户需要在 IAD (us-east-1) 区域创建连接才能创建工作流程。
1. 在**完整存储库 ID** 中，输入您的存储库 ID 作为用户名/存储库名称。确认您有权访问此存储库中的文件。
1. 在**源引用**（可选）中，输入存储库源引用（分支、标签或提交 ID）。 HealthOmics 如果未指定源引用，则使用默认分支。
1. 在**排除文件模式**中，输入文件模式以排除特定的文件夹、文件或扩展名。这有助于在导入存储库文件时管理数据大小。最多有 50 个模式，并且模式必须遵循[全局模式语法](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**。为了验证存储桶所有权 HealthOmics ，必须提供此信息。
1. 对于**从本地来源选择定义文件夹**：
1. 输入压缩的工作流程定义文件夹的本地驱动器位置。
1. **工作流定义文件主路径**（可选）：输入从压缩的工作流定义文件夹或存储库到该`main`文件的文件路径。如果工作流定义文件夹中只有一个文件，或者主文件名为 “main”，则不需要此参数。
1. 在**自述文件**（可选）面板中，选择**自述文件来源**并提供以下信息：
+ 对于**从存储库服务导入**，在**自述文件路径**中，输入存储库中自述文件的路径。
+ 对于**从 S3 中选择文件**，在 S3 的**自述文件中**，输入自述文件的 Amazon S3 URI。
+ 对于 **“从本地来源选择文件**：在**自述文件-可选**” 中，选择 “选择**文件” 以选择**要上传的 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**— 将您的 AWS 资源连接到外部存储库的代码连接的 ARN。
+ **fullRepositoryId**— 将存储库 ID 输入为`owner-name/repo-name`。确认您有权访问此存储库中的文件。
+ **sourceReference**（可选）-输入存储库引用类型（BRANCH、TAG 或 COMMIT）和值。
HealthOmics 如果您未指定源引用，则使用默认分支上的最新提交。
+ **excludeFilePatterns**（可选）-输入文件模式以排除特定的文件夹、文件或扩展名。这有助于在导入存储库文件时管理数据大小。最多提供 50 个模式。这些模式必须遵循全局模式[语法](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 参数，则会在存储库中 HealthOmics 导入根级 README.md 文件（如果存在）。
以下示例说明如何使用自述文件路径和自述文件URI指定自述文件位置。
```
# 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 工作流程自述文件](workflows-readme.md)。
#### 指定**main**定义文件
如果您要包括多个工作流定义文件，请使用`main`参数为您的工作流程指定主定义文件。
```
aws omics create-workflow \
--name Test \
--main multi_workflow/workflow2.wdl \
...
```
#### 指定运行存储类型
您可以指定默认的运行存储类型（动态或静态）和运行存储容量（静态存储所必需的）。有关运行存储类型的更多信息，请参阅[在 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 参数创建在加速计算实例上运行的工作流程。以下示例说明如何使用该`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"
}
]
}
```
在创建工作流命令中指定映射参数：
```
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 开发工具包创建工作流程
```
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 更新工作流程
如以下示例所示，您可以更新工作流程名称和描述。您也可以更改默认的运行存储类型（静态或动态）和运行存储容量（对于静态存储类型）。有关运行存储类型的更多信息，请参阅[在 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 开发工具包更新工作流程
```
import boto3
omics = boto3.client('omics')
response = omics.update_workflow(
name='my_workflow',
description='updated workflow'
)
```
# 删除私有工作流程
当您不再需要某个工作流程时，可以使用 HealthOmics 控制台、 AWS CLI 命令或其中一个将其删除 AWS SDKs。您可以删除符合以下条件的工作流程：
+ 其状态为 “活动” 或 “失败”。
+ 它没有活跃股份。
+ 您已经删除了所有工作流程版本。
删除工作流程不会影响正在使用该工作流程的任何正在进行的运行。
**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 开发工具包删除工作流程。
```
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`。
# 从工作流程定义中引用基因组文件
可以使用如下所示的 URI 来引用 HealthOmics 参考存储对象。使用您自己的`account ID``reference store ID`、和（`reference ID`如果指示）。
```
omics://account ID.storage.us-west-2.amazonaws.com/reference store id/reference/id
```
有些工作流程需要同时使用`SOURCE`和`INDEX`文件作为参考基因组。之前的 URI 是默认的简写形式，默认为源文件。要指定任一文件，您可以使用长 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 某些读取集将包含索引文件，例如`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/"
}
```
AWS CLI 通过添加到`--inputs file://`您的**开始运行**请求中引用输入 JSON 文件。