本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# HealthOmics 存储
使用 HealthOmics 存储以低成本高效地存储、检索、组织和共享基因组学数据。 HealthOmics 存储了解不同数据对象之间的关系，因此您可以定义哪些读取集源自相同的源数据。这为您提供了数据来源。
存储在`ACTIVE`状态下的数据可以立即检索。30 天或更长时间未被访问的数据将以`ARCHIVE`状态存储。要访问存档的数据，您可以通过 API 操作或控制台将其重新激活。
HealthOmics 序列存储旨在保持文件的内容完整性。但是，由于在活动分层和存档分层期间会进行压缩，因此无法保留导入的数据文件和导出文件的按位等效性。
在摄取期间， HealthOmics 生成实体标签 *HealthOmics ETag*，或，以便验证数据文件的内容完整性。测序部分在读取集的 ETag 源级别被识别和捕获。 ETag 计算结果不会改变实际文件或基因组数据。创建读取集后，在读取集源的整个生命周期中 ETag 不应发生变化。这意味着重新导入相同的文件会导致计算出相同的 ETag 值。
**Topics**
+ [HealthOmics ETags 和数据来源](etags-and-provenance.md)
+ [创建 HealthOmics 参考库](create-reference-store.md)
+ [创建 HealthOmics 序列存储](create-sequence-store.md)
+ [删除 HealthOmics 引用和序列存储](deleting-reference-and-sequence-stores.md)
+ [将读取集导入 HealthOmics 序列存储](import-sequence-store.md)
+ [直接上传到 HealthOmics 序列存储](synchronous-uploads.md)
+ [将 HealthOmics 读取集导出到 Amazon S3 存储桶](read-set-exports.md)
+ [使用 Amazon S3 访问 HealthOmics 读取集 URIs](s3-access.md)
+ [在中激活读取集 HealthOmics](activating-read-sets.md)
# HealthOmics ETags 和数据来源
HealthOmics ETag （实体标签）是序列存储中摄取内容的哈希值。这简化了数据检索和处理，同时保持了摄取的数据文件的内容完整性。 ETag 反映的是对象语义内容的变化，而不是其元数据的变化。指定的读取集类型和算法决定 ETag 如何计算。 ETag 计算结果不会改变实际文件或基因组数据。当读取集的文件类型架构允许时，序列存储会更新与数据来源相关的字段。
文件具有按位标识和语义标识。按位标识意味着文件的各个位是相同的，而语义标识意味着文件的内容是相同的。语义标识可以捕获文件的内容完整性，因此可以抵御元数据更改和压缩更改。
HealthOmics 序列存储中的读取集在对象的整个生命 compression/decompression 周期中经历周期和数据来源跟踪。在此处理过程中，载入文件的按位标识可能会发生变化，并且预计每次激活文件时都会发生变化；但是，文件的语义标识会保持不变。语义标识被捕获为 HealthOmics 实体标签 ETag ，或者在序列存储摄取期间计算出来并作为读取集元数据使用。
当读取集的文件类型架构允许时，序列存储更新字段将与数据来源相关联。对于 uBam、BAM 和 CRAM 文件，标题中会添加一个新的`@CO`或`Comment`标签。注释包含序列存储 ID 和摄取时间戳。
## 亚马逊 S3 ETags
使用 Amazon S3 URI 访问文件时，Amazon S3 API 操作也可能返回亚马逊 S3 ETag 和校验和值。Amazon S3 ETag 和校验和值之所以与不同， HealthOmics ETags 是因为它们代表文件的按位标识。要了解有关描述性元数据和对象的更多信息，请参阅 Amazon S3 [对象 API 文档](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Object.html)。Amazon S3 的 ETag 值可能会随着读取集的每个激活周期而变化，您可以使用它们来验证文件的读取。但是，不要缓存 Amazon S3 ETag 值以在文件生命周期中用于文件身份验证，因为它们不会保持一致。相比之下，在读取集的整个生命周期中都 HealthOmics ETag 保持一致。
## 如何 HealthOmics 计算 ETags
ETag 是根据提取的文件内容的哈希值生成的。 MD5up 默认情况下， ETag 算法系列设置为，但在创建序列存储期间可以对其进行不同的配置。计算 ETag 完毕后，算法和计算出的哈希值将添加到读取集合中。支持的文件类型 MD5 算法如下。
+ *FASTQ\$1 MD5up* — 计算未压缩、完整 FASTQ 读取集源的 MD5哈希值。
+ *BAM\$1 MD5up* — 根据链接的引用（如果有）计算 SAM 中表示的未压缩 BAM 或 uBam 读取集源的对齐部分的 MD5 哈希值。
+ *CRAM\$1 MD5up* — 根据链接的 MD5 引用，计算 SAM 中表示的未压缩 CRAM 读取集源的对齐部分的哈希值。
**注意**
MD5 众所周知，哈希很容易发生冲突。因此， ETag 如果两个不同的文件是为了利用已知的碰撞而制造的，则它们可能具有相同的效果。
该 SHA256 系列支持以下算法。算法的计算方法如下：
+ *FASTQ\$1 SHA256up* — 计算未压缩、完整 FASTQ 读取集源的 SHA-256 哈希值。
+ *BAM\$1 SHA256up* — 根据链接的引用（如果有）计算 SAM 中表示的未压缩 BAM 或 uBam 读取集源的对齐部分的 SHA-256 哈希值。
+ *CRAM\$1 SHA256up* — 根据链接的引用，计算 SAM 中表示的未压缩 CRAM 读取集源的对齐部分的 SHA-256 哈希值。
该 SHA512 系列支持以下算法。算法的计算方法如下：
+ *FASTQ\$1 SHA512up* — 计算未压缩、完整 FASTQ 读取集源的 SHA-512 哈希值。
+ *BAM\$1 SHA512up* — 根据链接的引用（如果有）计算 SAM 中表示的未压缩 BAM 或 uBam 读取集源的对齐部分的 SHA-512 哈希值。
+ *CRAM\$1 SHA512up * — 根据链接的引用，计算 SAM 中表示的未压缩 CRAM 读取集源的对齐部分的 SHA-512 哈希值。
# 创建 HealthOmics 参考库
中的参考存储 HealthOmics 是用于存储参考基因组的数据存储。您可以在每个 AWS 账户 区域中拥有一个参考资料库。您可以使用控制台或 CLI 创建参考存储。
**Topics**
+ [使用控制台创建参考库](#console-create-reference-store)
+ [使用 CLI 创建参考存储库](#api-create-reference-store)
## 使用控制台创建参考库
**创建参考存储**
1. 打开 [HealthOmics 控制台](https://console.aws.amazon.com/omics/)。
1. 如果需要，请打开左侧导航窗格 (►)。选择**参考商店**。
1. 从 “**基因组学” 数据存储选项中选择参考**基因组。
1. 您可以选择先前导入的参考基因组，也可以导入新的参考基因组。如果您尚未导入参考基因组，请选择右上角的**导入参考基因组**。
1. 在 “**创建参考基因组导入作业**” 页面上，选择 “**快速创****建” 或 “手动**创建” 选项来创建参考存储库，然后提供以下信息。
+ **参考基因组名称**-此存储的唯一名称。
+ **描述**（可选）-此参考库的描述。
+ **IAM 角色**-选择有权访问您的参考基因组的角色。
+ **来自 Amazon S3** 的参考-在 Amazon S3 存储桶中选择您的参考序列文件。
+ **标签**（可选）-为此参考商店提供最多 50 个标签。
## 使用 CLI 创建参考存储库
以下示例向您展示了如何使用创建参考存储库 AWS CLI。每个 AWS 地区可以有一个参考库。
参考存储支持存储扩展名为`.fasta`、、、、、、、、、`.fa`、`.fas`、`.fsa`、`.faa``.fna``.ffn``.frn``.mpfa``.seq`、`.txt`的 FASTA 文件。还支持这些扩展的`bgzip`版本。
在以下示例中，`reference store name`使用您为参考商店选择的名称替换。
```
aws omics create-reference-store --name "reference store name"
```
您会收到一个 JSON 响应，其中包含参考存储库 ID 和名称、ARN 以及创建参考存储的时间戳。
```
{
"id": "3242349265",
"arn": "arn:aws:omics:us-west-2:555555555555:referenceStore/3242349265",
"name": "MyReferenceStore",
"creationTime": "2022-07-01T20:58:42.878Z"
}
```
您可以在其他 AWS CLI 命令中使用参考存储库 ID。您可以使用**list-reference-stores**命令检索与您的账户 IDs 关联的参考商店列表，如以下示例所示。
```
aws omics list-reference-stores
```
作为回应，您将收到新创建的参考商店的名称。
```
{
"referenceStores": [
{
"id": "3242349265",
"arn": "arn:aws:omics:us-west-2:555555555555:referenceStore/3242349265",
"name": "MyReferenceStore",
"creationTime": "2022-07-01T20:58:42.878Z"
}
]
}
```
创建参考存储后，您可以创建导入任务以将基因组参考文件加载到其中。为此，您必须使用或创建 IAM 角色来访问数据。以下是示例策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket1",
"arn:aws:s3:::amzn-s3-demo-bucket1/*"
]
}
]
}
```
------
您还必须有类似于以下示例的信任策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"omics.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
您现在可以导入参考基因组了。此示例使用基因组参考联盟 Human Build 38 (hg38)，该联盟是开放访问的，可从[开放数据注册处](https://registry.opendata.aws/)获得。 AWS托管此数据的存储桶位于美国东部（俄亥俄州）。要在其他 AWS 区域使用存储桶，您可以将数据复制到您所在地区托管的 Amazon S3 存储桶。使用以下 AWS CLI 命令将基因组复制到您的 Amazon S3 存储桶。
```
aws s3 cp s3://broad-references/hg38/v0/Homo_sapiens_assembly38.fasta s3://amzn-s3-demo-bucket
```
然后，您可以开始导入任务。用您自己的输入替换`reference store ID``role ARN`、和`source file path`。
```
aws omics start-reference-import-job --reference-store-id reference store ID --role-arn role ARN --sources source file path
```
导入数据后，您将收到以下 JSON 格式的响应。
```
{
"id": "7252016478",
"referenceStoreId": "3242349265",
"roleArn": "arn:aws:iam::111122223333:role/OmicsReferenceImport",
"status": "CREATED",
"creationTime": "2022-07-01T21:15:13.727Z"
}
```
您可以使用以下命令监控作业的状态。在以下示例中，将`reference store ID`和`job ID`替换为您的参考商店 ID 和您想进一步了解的任务 ID。
```
aws omics get-reference-import-job --reference-store-id reference store ID --id job ID
```
作为回应，您会收到一条回复，其中包含该参考库的详细信息及其状态。
```
{
"id": "7252016478",
"referenceStoreId": "3242349265",
"roleArn": "arn:aws:iam::555555555555:role/OmicsReferenceImport",
"status": "RUNNING",
"creationTime": "2022-07-01T21:15:13.727Z",
"sources": [
{
"sourceFile": "s3://amzn-s3-demo-bucket/Homo_sapiens_assembly38.fasta",
"status": "IN_PROGRESS",
"name": "MyReference"
}
]
}
```
您还可以通过列出您的参考文献并根据参考名称对其进行筛选来查找已导入的参考文献。`reference store ID`替换为您的参考商店 ID，然后添加可选筛选条件以缩小列表范围。
```
aws omics list-references --reference-store-id reference store ID --filter name=MyReference
```
作为回应，您会收到以下信息。
```
{
"references": [
{
"id": "1234567890",
"arn": "arn:aws:omics:us-west-2:555555555555:referenceStore/1234567890/reference/1234567890",
"referenceStoreId": "12345678",
"md5": "7ff134953dcca8c8997453bbb80b6b5e",
"status": "ACTIVE",
"name": "MyReference",
"creationTime": "2022-07-02T00:15:19.787Z",
"updateTime": "2022-07-02T00:15:19.787Z"
}
]
}
```
要了解有关参考元数据的更多信息，请使用 **get-reference-metadata**API 操作。在以下示例中，`reference store ID`替换为您的参考商店编号和`reference ID`您想进一步了解的参考编码。
```
aws omics get-reference-metadata --reference-store-id reference store ID --id reference ID
```
作为回应，您会收到以下信息。
```
{
"id": "1234567890",
"arn": "arn:aws:omics:us-west-2:555555555555:referenceStore/referencestoreID/reference/referenceID",
"referenceStoreId": "1234567890",
"md5": "7ff134953dcca8c8997453bbb80b6b5e",
"status": "ACTIVE",
"name": "MyReference",
"creationTime": "2022-07-02T00:15:19.787Z",
"updateTime": "2022-07-02T00:15:19.787Z",
"files": {
"source": {
"totalParts": 31,
"partSize": 104857600,
"contentLength": 3249912778
},
"index": {
"totalParts": 1,
"partSize": 104857600,
"contentLength": 160928
}
}
}
```
您也可以使用 **get-** reference 下载部分参考文件。在以下示例中，`reference store ID`替换为您的参考商店编号和`reference ID`您要从中下载的参考编码。
```
aws omics get-reference --reference-store-id reference store ID --id reference ID --part-number 1 outfile.fa
```
# 创建 HealthOmics 序列存储
HealthOmics 序列存储支持以`FASTQ`（仅限 gzip）和的未对齐格式存储基因组文件。`uBAM`它还支持`BAM`和的对齐格式`CRAM`。
导入的文件存储为读取集。您可以为读取集添加标签，并使用 IAM 策略来控制对读取集的访问权限。对齐的读取集需要参考基因组来对齐基因组序列，但对于未对齐的读取集，它是可选的。
要存储读取集，请先创建序列存储。创建序列存储时，您可以指定一个可选的 Amazon S3 存储桶作为备用位置以及存储 S3 访问日志的位置。备用位置用于存储在直接上传期间未能创建读取集的任何文件。备用位置可用于 2023 年 5 月 15 日之后创建的序列存储。您可以在创建序列存储时指定后备位置。
您最多可以指定五个读取集标签密钥。当您使用与其中一个密钥匹配的标签密钥创建或更新读取集时，读取集标签会传播到相应的 Amazon S3 对象。默认情况下，由创建的系统标签会 HealthOmics 被传播。
**Topics**
+ [使用控制台创建序列存储](#console-create-sequence-store)
+ [使用 CLI 创建序列存储](#api-create-sequence-store)
+ [更新序列存储](#update-sequence-store)
+ [更新序列存储的读取集标签](#sequence-store-manage-tags)
+ [导入基因组文件](#import-genomic-files)
## 使用控制台创建序列存储
**创建序列存储**
1. 打开 [HealthOmics 管理控制台](https://console.aws.amazon.com/omics/)。
1. 如果需要，请打开左侧导航窗格 (►)。选择**序列存储**。
1. 在 “**创建序列存储**” 页面上，提供以下信息
+ **序列存储名称**-此存储的唯一名称。
+ **描述**（可选）-此序列存储的描述。
1. 对于 **S3 中的备用位置**，请指定 Amazon S3 位置。 HealthOmics 使用备用位置来存储在直接上传期间未能创建读取集的所有文件。您需要向该 HealthOmics 服务授予对 Amazon S3 备用位置的写入权限。有关策略示例，请参阅 [配置备用位置](synchronous-uploads.md#synchronous-uploads-fallback)。
备用位置不适用于 2023 年 5 月 16 日之前创建的序列存储库。
1. （可选）对于用于 **S3 传播的读取集标签键**，您最多可以输入五个读取集密钥，从读取集传播到底层 S3 对象。通过将标签从读取集传播到 S3 对象，您可以根据标签授予 S3 访问权限，允许 and/or 最终用户通过 Amazon S3 getObjectTagging API 操作查看传播的标签。
1. 在文本框中输入一个键值。控制台会创建一个新的文本框来添加下一个密钥。
1. （可选）选择 “**移除**” 以删除所有密钥。
1. 在 “**数据加密**” 下，选择是否要让数据加密由客户管理的 CMK 拥有和管理， AWS 还是要使用客户托管的 CMK。
1. （可选）在 “**S3 数据访问**” 下，选择是否创建新的角色和策略以通过 Amazon S3 访问序列存储。
1. （可选）对于 **S3 访问日志**，请选择`Enabled`是否希望 Amazon S3 收集访问日志记录。
对于 **S3 中的访问日志位置**，请指定用于存储日志的 Amazon S3 位置。只有启用了 S3 访问日志记录后，此字段才可见。
1. **标签**（可选）-为此序列存储提供最多 50 个标签。这些标签与读取集 import/tag 更新期间设置的读取集标签是分开的
创建商店后，就可以开始了[导入基因组文件](#import-genomic-files)。
## 使用 CLI 创建序列存储
在以下示例中，`sequence store name`使用您为序列存储选择的名称替换。
```
aws omics create-sequence-store --name sequence store name --fallback-location "s3://amzn-s3-demo-bucket"
```
您将收到以下 JSON 格式的响应，其中包括您新创建的序列存储的 ID 号。
```
{
"id": "3936421177",
"arn": "arn:aws:omics:us-west-2:111122223333:sequenceStore/3936421177",
"name": "sequence_store_example_name",
"creationTime": "2022-07-13T20:09:26.038Z"
"fallbackLocation" : "s3://amzn-s3-demo-bucket"
}
```
您还可以使用**list-sequence-stores**命令查看与您的账户关联的所有序列存储，如下所示。
```
aws omics list-sequence-stores
```
您会收到以下回复。
```
{
"sequenceStores": [
{
"arn": "arn:aws:omics:us-west-2:111122223333:sequenceStore/3936421177",
"id": "3936421177",
"name": "MySequenceStore",
"creationTime": "2022-07-13T20:09:26.038Z",
"updatedTime": "2024-09-13T04:11:31.242Z",
"fallbackLocation" : "s3://amzn-s3-demo-bucket",
"status": "Active"
}
]
}
```
您可以使用序列存储的 ID **get-sequence-store**来了解有关序列存储的更多信息，如以下示例所示：
```
aws omics get-sequence-store --id sequence store ID
```
您会收到以下回复：
```
{
"arn": "arn:aws:omics:us-west-2:123456789012:sequenceStore/sequencestoreID",
"creationTime": "2024-01-12T04:45:29.857Z",
"updatedTime": "2024-09-13T04:11:31.242Z",
"description": null,
"fallbackLocation": null,
"id": "2015356892",
"name": "MySequenceStore",
"s3Access": {
"s3AccessPointArn": "arn:aws:s3:us-west-2:123456789012:accesspoint/592761533288-2015356892",
"s3Uri": "s3://592761533288-2015356892-ajdpi90jdas90a79fh9a8ja98jdfa9jf98-s3alias/592761533288/sequenceStore/2015356892/",
"accessLogLocation": "s3://IAD-seq-store-log/2015356892/"
},
"sseConfig": {
"keyArn": "arn:aws:kms:us-west-2:123456789012:key/eb2b30f5-635d-4b6d-b0f9-d3889fe0e648",
"type": "KMS"
},
"status": "Active",
"statusMessage": null,
"setTagsToSync": ["withdrawn","protocol"],
}
```
创建后，还可以更新多个商店参数。这可以通过控制台或 API `updateSequenceStore` 操作来完成。
## 更新序列存储
要更新序列存储，请执行以下步骤：
1. 打开 [HealthOmics 管理控制台](https://console.aws.amazon.com/omics/)。
1. 如果需要，请打开左侧导航窗格 (►)。选择**序列存储**。
1. 选择要更新的序列存储。
1. 在**详细信息**面板中，选择**编辑**。
1. 在**编辑详细信息**页面上，您可以更新以下字段：
+ **序列存储名称**-此存储的唯一名称。
+ **描述**-此序列存储的描述。
+ **在 S3 中的备用位置**，请指定 Amazon S3 的位置。 HealthOmics 使用备用位置来存储在直接上传期间未能创建读取集的所有文件。
+ **读取 S3 传播的设置标签密钥**您最多可以输入五个读取集密钥以传播到 Amazon S3。
+ （可选）对于 **S3 访问日志**，请选择`Enabled`是否希望 Amazon S3 收集访问日志记录。
对于 **S3 中的访问日志位置**，请指定用于存储日志的 Amazon S3 位置。只有启用了 S3 访问日志记录后，此字段才可见。
+ **标签**（可选）-为此序列存储提供最多 50 个标签。
## 更新序列存储的读取集标签
要更新序列存储的读取集标签或其他字段，请执行以下步骤：
1. 打开 [HealthOmics 管理控制台](https://console.aws.amazon.com/omics/)。
1. 如果需要，请打开左侧导航窗格 (►)。选择**序列存储**。
1. 选择要更新的序列存储。
1. 选择**详细信息**选项卡。
1. 选择**编辑**。
1. 根据需要添加新的读取集标签或删除现有标签。
1. 根据需要更新名称、描述、备用位置或 S3 数据访问权限。
1. 选择**保存更改**。
## 导入基因组文件
要将基因组文件导入序列存储，请执行以下步骤：
**导入基因组学文件**
1. 打开 [HealthOmics 管理控制台](https://console.aws.amazon.com/omics/)。
1. 如果需要，请打开左侧导航窗格 (►)。选择选择**序列存储**。
1. 在**序列存储**页面上，选择要将文件导入到的序列存储。
1. 在单个序列存储页面上，选择**导入基因组文件**。
1. 在 “**指定导入详情**” 页面上，提供以下信息
+ **IAM 角色**-可以访问 Amazon S3 上的基因组文件的 IAM 角色。
+ **参考基因组**-该基因组学数据的参考基因组。
1. **在 “指定导入清单**” 页面上，指定以下信息**清单文件**。清单文件是一个 JSON 或 YAML 文件，用于描述基因组学数据的基本信息。有关清单文件的信息，请参阅[将读取集导入 HealthOmics 序列存储](import-sequence-store.md)。
1. 单击 “**创建导入任务**”。
# 删除 HealthOmics 引用和序列存储
引用和序列存储均可删除。仅当序列存储不包含读取集时才能将其删除，并且只有在引用存储不包含引用时才能将其删除。删除序列或参考存储也会删除与该存储关联的所有标签。
以下示例说明如何使用删除参考资料库 AWS CLI。如果操作成功，您将不会收到回复。在以下示例中，`reference store ID`使用您的参考商店编号替换。
```
aws omics delete-reference-store --id reference store ID
```
以下示例向您展示如何删除序列存储。如果操作成功，您将不会收到回复。在以下示例中，`sequence store ID`替换为您的序列存储 ID。
```
aws omics delete-sequence-store --id sequence store ID
```
您也可以删除参考文献库中的参考文献，如以下示例所示。只有在未在读取集、变体存储或注释存储中使用引用时，才能将其删除。在以下示例中，`reference store ID`替换为您的参考商店 ID，然后`reference ID`替换为要删除的参考文献的 ID。
```
aws omics delete-reference --id reference ID --reference-store-id reference store ID
```
# 将读取集导入 HealthOmics 序列存储
创建序列存储后，创建导入任务以将读取集上传到数据存储中。您可以从 Amazon S3 存储桶上传文件，也可以使用同步 API 操作直接上传。您的 Amazon S3 存储桶必须与您的序列存储位于同一区域。
您可以将对齐和未对齐读取集的任意组合上传到序列存储中，但是，如果导入中的任何读取集是对齐的，则必须包括参考基因组。
您可以重复使用用于创建参考存储的 IAM 访问策略。
以下主题描述了将读取集导入序列存储然后获取有关导入数据信息的主要步骤。
**Topics**
+ [将文件上传到亚马逊 S3](#upload-files-to-s3)
+ [创建清单文件](#create-manifest-file)
+ [启动导入任务](#start-import-job)
+ [监控导入作业](#monitor-import-job)
+ [查找导入的序列文件](#list-read-sets)
+ [获取有关阅读集的详细信息](#get-read-set-metadata)
+ [下载读取集数据文件](#get-read-set-data)
## 将文件上传到亚马逊 S3
以下示例显示了如何将文件移动到您的 Amazon S3 存储桶中。
```
aws s3 cp s3://1000genomes/phase1/data/HG00100/alignment/HG00100.chrom20.ILLUMINA.bwa.GBR.low_coverage.20101123.bam s3://your-bucket
aws s3 cp s3://1000genomes/phase3/data/HG00146/sequence_read/SRR233106_1.filt.fastq.gz s3://your-bucket
aws s3 cp s3://1000genomes/phase3/data/HG00146/sequence_read/SRR233106_2.filt.fastq.gz s3://your-bucket
aws s3 cp s3://1000genomes/data/HG00096/alignment/HG00096.alt_bwamem_GRCh38DH.20150718.GBR.low_coverage.cram s3://your-bucket
aws s3 cp s3://gatk-test-data/wgs_ubam/NA12878_20k/NA12878_A.bam s3://your-bucket
```
本示例`BAM`中`CRAM`使用的样本需要不同的基因组参考文献，`Hg19`以及`Hg38`。要了解更多信息或访问这些参考文献，请参阅开放数据注册表中的[广泛基因组参考文献](https://registry.opendata.aws/broad-references/) AWS。
## 创建清单文件
您还必须以 JSON 格式创建清单文件来对导入任务进行建模`import.json`（参见以下示例）。如果您在控制台中创建序列存储，则无需指定`sequenceStoreId`或`roleARN`，因此清单文件以`sources`输入开头。
------
#### [ API manifest ]
以下示例使用 API 导入三个读取集：一个`FASTQ``BAM`、一个和一个`CRAM`。
```
{
"sequenceStoreId": "3936421177",
"roleArn": "arn:aws:iam::555555555555:role/OmicsImport",
"sources":
[
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/HG00100.chrom20.ILLUMINA.bwa.GBR.low_coverage.20101123.bam"
},
"sourceFileType": "BAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"referenceArn": "arn:aws:omics:us-west-2:555555555555:referenceStore/0123456789/reference/0000000001",
"name": "HG00100",
"description": "BAM for HG00100",
"generatedFrom": "1000 Genomes"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/SRR233106_1.filt.fastq.gz",
"source2": "s3://amzn-s3-demo-bucket/SRR233106_2.filt.fastq.gz"
},
"sourceFileType": "FASTQ",
"subjectId": "mySubject",
"sampleId": "mySample",
// NOTE: there is no reference arn required here
"name": "HG00146",
"description": "FASTQ for HG00146",
"generatedFrom": "1000 Genomes"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/HG00096.alt_bwamem_GRCh38DH.20150718.GBR.low_coverage.cram"
},
"sourceFileType": "CRAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"referenceArn": "arn:aws:omics:us-west-2:555555555555:referenceStore/0123456789/reference/0000000001",
"name": "HG00096",
"description": "CRAM for HG00096",
"generatedFrom": "1000 Genomes"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/NA12878_A.bam"
},
"sourceFileType": "UBAM",
"subjectId": "mySubject",
"sampleId": "mySample",
// NOTE: there is no reference arn required here
"name": "NA12878_A",
"description": "uBAM for NA12878",
"generatedFrom": "GATK Test Data"
}
]
}
```
------
#### [ Console manifest ]
此示例代码用于使用控制台导入单个读取集。
```
[
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/HG00100.chrom20.ILLUMINA.bwa.GBR.low_coverage.20101123.bam"
},
"sourceFileType": "BAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"name": "HG00100",
"description": "BAM for HG00100",
"generatedFrom": "1000 Genomes"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/SRR233106_1.filt.fastq.gz",
"source2": "s3://amzn-s3-demo-bucket/SRR233106_2.filt.fastq.gz"
},
"sourceFileType": "FASTQ",
"subjectId": "mySubject",
"sampleId": "mySample",
"name": "HG00146",
"description": "FASTQ for HG00146",
"generatedFrom": "1000 Genomes"
},
{
"sourceFiles":
{
"source1": "s3://your-bucket/HG00096.alt_bwamem_GRCh38DH.20150718.GBR.low_coverage.cram"
},
"sourceFileType": "CRAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"name": "HG00096",
"description": "CRAM for HG00096",
"generatedFrom": "1000 Genomes"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/NA12878_A.bam"
},
"sourceFileType": "UBAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"name": "NA12878_A",
"description": "uBAM for NA12878",
"generatedFrom": "GATK Test Data"
}
]
```
------
或者，您可以上传 YAML 格式的清单文件。
## 启动导入任务
要启动导入作业，请使用以下 AWS CLI 命令。
```
aws omics start-read-set-import-job --cli-input-json file://import.json
```
您会收到以下响应，表示成功创建了就业机会。
```
{
"id": "3660451514",
"sequenceStoreId": "3936421177",
"roleArn": "arn:aws:iam::111122223333:role/OmicsImport",
"status": "CREATED",
"creationTime": "2022-07-13T22:14:59.309Z"
}
```
## 监控导入作业
导入任务启动后，您可以使用以下命令监控其进度。在以下示例中，`sequence store id`替换为您的序列存储 ID，然后`job import ID`替换为导入 ID。
```
aws omics get-read-set-import-job --sequence-store-id sequence store id --id job import ID
```
下图显示了与指定序列存储 ID 关联的所有导入任务的状态。
```
{
"id": "1234567890",
"sequenceStoreId": "1234567890",
"roleArn": "arn:aws:iam::111122223333:role/OmicsImport",
"status": "RUNNING",
"statusMessage": "The job is currently in progress.",
"creationTime": "2022-07-13T22:14:59.309Z",
"sources": [
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/HG00100.chrom20.ILLUMINA.bwa.GBR.low_coverage.20101123.bam"
},
"sourceFileType": "BAM",
"status": "IN_PROGRESS",
"statusMessage": "The job is currently in progress."
"subjectId": "mySubject",
"sampleId": "mySample",
"referenceArn": "arn:aws:omics:us-west-2:111122223333:referenceStore/3242349265/reference/8625408453",
"name": "HG00100",
"description": "BAM for HG00100",
"generatedFrom": "1000 Genomes",
"readSetID": "1234567890"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/SRR233106_1.filt.fastq.gz",
"source2": "s3://amzn-s3-demo-bucket/SRR233106_2.filt.fastq.gz"
},
"sourceFileType": "FASTQ",
"status": "IN_PROGRESS",
"statusMessage": "The job is currently in progress."
"subjectId": "mySubject",
"sampleId": "mySample",
"name": "HG00146",
"description": "FASTQ for HG00146",
"generatedFrom": "1000 Genomes",
"readSetID": "1234567890"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/HG00096.alt_bwamem_GRCh38DH.20150718.GBR.low_coverage.cram"
},
"sourceFileType": "CRAM",
"status": "IN_PROGRESS",
"statusMessage": "The job is currently in progress."
"subjectId": "mySubject",
"sampleId": "mySample",
"referenceArn": "arn:aws:omics:us-west-2:111122223333:referenceStore/3242349265/reference/1234568870",
"name": "HG00096",
"description": "CRAM for HG00096",
"generatedFrom": "1000 Genomes",
"readSetID": "1234567890"
},
{
"sourceFiles":
{
"source1": "s3://amzn-s3-demo-bucket/NA12878_A.bam"
},
"sourceFileType": "UBAM",
"status": "IN_PROGRESS",
"statusMessage": "The job is currently in progress."
"subjectId": "mySubject",
"sampleId": "mySample",
"name": "NA12878_A",
"description": "uBAM for NA12878",
"generatedFrom": "GATK Test Data",
"readSetID": "1234567890"
}
]
}
```
## 查找导入的序列文件
任务完成后，您可以使用 **list-read-sets**API 操作来查找导入的序列文件。在以下示例中，`sequence store id`替换为您的序列存储 ID。
```
aws omics list-read-sets --sequence-store-id sequence store id
```
您会收到以下回复。
```
{
"readSets": [
{
"id": "0000000001",
"arn": "arn:aws:omics:us-west-2:111122223333:sequenceStore/01234567890/readSet/0000000001",
"sequenceStoreId": "1234567890",
"subjectId": "mySubject",
"sampleId": "mySample",
"status": "ACTIVE",
"name": "HG00100",
"description": "BAM for HG00100",
"referenceArn": "arn:aws:omics:us-west-2:111122223333:referenceStore/01234567890/reference/0000000001",
"fileType": "BAM",
"sequenceInformation": {
"totalReadCount": 9194,
"totalBaseCount": 928594,
"generatedFrom": "1000 Genomes",
"alignment": "ALIGNED"
},
"creationTime": "2022-07-13T23:25:20Z"
"creationType": "IMPORT",
"etag": {
"algorithm": "BAM_MD5up",
"source1": "d1d65429212d61d115bb19f510d4bd02"
}
},
{
"id": "0000000002",
"arn": "arn:aws:omics:us-west-2:111122223333:sequenceStore/0123456789/readSet/0000000002",
"sequenceStoreId": "0123456789",
"subjectId": "mySubject",
"sampleId": "mySample",
"status": "ACTIVE",
"name": "HG00146",
"description": "FASTQ for HG00146",
"fileType": "FASTQ",
"sequenceInformation": {
"totalReadCount": 8000000,
"totalBaseCount": 1184000000,
"generatedFrom": "1000 Genomes",
"alignment": "UNALIGNED"
},
"creationTime": "2022-07-13T23:26:43Z"
"creationType": "IMPORT",
"etag": {
"algorithm": "FASTQ_MD5up",
"source1": "ca78f685c26e7cc2bf3e28e3ec4d49cd"
}
},
{
"id": "0000000003",
"arn": "arn:aws:omics:us-west-2:111122223333:sequenceStore/0123456789/readSet/0000000003",
"sequenceStoreId": "0123456789",
"subjectId": "mySubject",
"sampleId": "mySample",
"status": "ACTIVE",
"name": "HG00096",
"description": "CRAM for HG00096",
"referenceArn": "arn:aws:omics:us-west-2:111122223333:referenceStore/0123456789/reference/0000000001",
"fileType": "CRAM",
"sequenceInformation": {
"totalReadCount": 85466534,
"totalBaseCount": 24000004881,
"generatedFrom": "1000 Genomes",
"alignment": "ALIGNED"
},
"creationTime": "2022-07-13T23:30:41Z"
"creationType": "IMPORT",
"etag": {
"algorithm": "CRAM_MD5up",
"source1": "66817940f3025a760e6da4652f3e927e"
}
},
{
"id": "0000000004",
"arn": "arn:aws:omics:us-west-2:111122223333:sequenceStore/0123456789/readSet/0000000004",
"sequenceStoreId": "0123456789",
"subjectId": "mySubject",
"sampleId": "mySample",
"status": "ACTIVE",
"name": "NA12878_A",
"description": "uBAM for NA12878",
"fileType": "UBAM",
"sequenceInformation": {
"totalReadCount": 20000,
"totalBaseCount": 5000000,
"generatedFrom": "GATK Test Data",
"alignment": "ALIGNED"
},
"creationTime": "2022-07-13T23:30:41Z"
"creationType": "IMPORT",
"etag": {
"algorithm": "BAM_MD5up",
"source1": "640eb686263e9f63bcda12c35b84f5c7"
}
}
]
}
```
## 获取有关阅读集的详细信息
要查看有关读取集的更多详细信息，请使用 **GetReadSetMetadata**API 操作。在以下示例中，`sequence store id`替换为您的序列存储 ID，然后`read set id`替换为您的读取集 ID。
```
aws omics get-read-set-metadata --sequence-store-id sequence store id --id read set id
```
您会收到以下回复。
```
{
"arn": "arn:aws:omics:us-west-2:123456789012:sequenceStore/2015356892/readSet/9515444019",
"creationTime": "2024-01-12T04:50:33.548Z",
"creationType": "IMPORT",
"creationJobId": "33222111",
"description": null,
"etag": {
"algorithm": "FASTQ_MD5up",
"source1": "00d0885ba3eeb211c8c84520d3fa26ec",
"source2": "00d0885ba3eeb211c8c84520d3fa26ec"
},
"fileType": "FASTQ",
"files": {
"index": null,
"source1": {
"contentLength": 10818,
"partSize": 104857600,
"s3Access": {
"s3Uri": "s3://accountID-sequence store ID-ajdpi90jdas90a79fh9a8ja98jdfa9jf98-s3alias/592761533288/sequenceStore/2015356892/readSet/9515444019/import_source1.fastq.gz"
},
"totalParts": 1
},
"source2": {
"contentLength": 10818,
"partSize": 104857600,
"s3Access": {
"s3Uri": "s3://accountID-sequence store ID-ajdpi90jdas90a79fh9a8ja98jdfa9jf98-s3alias/592761533288/sequenceStore/2015356892/readSet/9515444019/import_source1.fastq.gz"
},
"totalParts": 1
}
},
"id": "9515444019",
"name": "paired-fastq-import",
"sampleId": "sampleId-paired-fastq-import",
"sequenceInformation": {
"alignment": "UNALIGNED",
"generatedFrom": null,
"totalBaseCount": 30000,
"totalReadCount": 200
},
"sequenceStoreId": "2015356892",
"status": "ACTIVE",
"statusMessage": null,
"subjectId": "subjectId-paired-fastq-import"
}
```
## 下载读取集数据文件
您可以使用 Amazon S3 **GetObject** API 操作访问活动读取集的对象。该对象的 URI 将在 **GetReadSetMetadata**API 响应中返回。有关更多信息，请参阅 [使用 Amazon S3 访问 HealthOmics 读取集 URIs](s3-access.md)。
或者，也可以使用 HealthOmics **GetReadSet** API 操作。您可以使用**GetReadSet**通过下载各个部分来并行下载。这些部分与 Amazon S3 部件类似。以下是如何从读取集下载第 1 部分的示例。在以下示例中，`sequence store id`替换为您的序列存储 ID，然后`read set id`替换为您的读取集 ID。
```
aws omics get-read-set --sequence-store-id sequence store id --id read set id --part-number 1 outfile.bam
```
您也可以使用 HealthOmics 传输管理器下载文件以 HealthOmics 供参考或读取。您可以[在此](https://pypi.org/project/amazon-omics-tools/)处下载 HealthOmics 转接管理器。有关使用和设置传输管理器的更多信息，请参阅此[GitHub存储库](https://github.com/awslabs/amazon-omics-tools/)。
# 直接上传到 HealthOmics 序列存储
我们建议您使用 HealthOmics 传输管理器将文件添加到序列存储中。有关使用传输管理器的更多信息，请参阅此[GitHub存储库](https://github.com/awslabs/amazon-omics-tools/)。您也可以通过直接上传 API 操作将读取集直接上传到序列存储。
直接上传读取集首先处于`PROCESSING_UPLOAD`状态。这意味着文件段当前正在上传，您可以访问读取集元数据。上传分段并验证校验和后，读取集将变为`ACTIVE`和行为与导入的读取集相同。
如果直接上传失败，则读取集状态将显示为`UPLOAD_FAILED`。您可以将 Amazon S3 存储桶配置为上传失败的文件的备用位置。备用位置可用于 2023 年 5 月 15 日之后创建的序列存储。
**Topics**
+ [使用直接上传到序列存储库 AWS CLI](#synchronous-uploads-api)
+ [配置备用位置](#synchronous-uploads-fallback)
## 使用直接上传到序列存储库 AWS CLI
首先，开始分段上传。您可以使用来执行此操作 AWS CLI，如以下示例所示。
**使用 AWS CLI 命令直接上传**
1. 通过分隔数据来创建各个部分，如以下示例所示。
```
split -b 100MiB SRR233106_1.filt.fastq.gz source1_part_
```
1. 将源文件分段后，创建分段读取集上传，如以下示例所示。将和其他参数替换`sequence store ID`为您的序列存储 ID 和其他值。
```
aws omics create-multipart-read-set-upload \
--sequence-store-id sequence store ID \
--name upload name \
--source-file-type FASTQ \
--subject-id subject ID \
--sample-id sample ID \
--description "FASTQ for HG00146" "description of upload" \
--generated-from "1000 Genomes""source of imported files"
```
你会在响应中获得`uploadID`和其他元数据。使用`uploadID`进行上传过程的下一步操作。
```
{
"sequenceStoreId": "1504776472",
"uploadId": "7640892890",
"sourceFileType": "FASTQ",
"subjectId": "mySubject",
"sampleId": "mySample",
"generatedFrom": "1000 Genomes",
"name": "HG00146",
"description": "FASTQ for HG00146",
"creationTime": "2023-11-20T23:40:47.437522+00:00"
}
```
1. 将您的阅读集添加到上传内容中。如果您的文件足够小，则只需执行一次此步骤即可。对于较大的文件，您可以对文件的每个部分执行此步骤。如果您使用之前使用的分段号上传新分段，则它会覆盖之前上传的分段。
在以下示例中，将`sequence store ID``upload ID`、和其他参数替换为您的值。
```
aws omics upload-read-set-part \
--sequence-store-id sequence store ID \
--upload-id upload ID \
--part-source SOURCE1 \
--part-number part number \
--payload source1/source1_part_aa.fastq.gz
```
响应是一个 ID，您可以使用它来验证上传的文件是否与您想要的文件匹配。
```
{
"checksum": "984979b9928ae8d8622286c4a9cd8e99d964a22d59ed0f5722e1733eb280e635"
}
```
1. 如有必要，请继续上传文件的各个部分。要验证您的读取集是否已上传，请使用 **list-read-set-upload-par** ts API 操作，如下所示。在以下示例中，将`sequence store ID `、和`upload ID`，替换为`part source`您自己的输入。
```
aws omics list-read-set-upload-parts \
--sequence-store-id sequence store ID \
--upload-id upload ID \
--part-source SOURCE1
```
响应返回读取集的数量、大小和最近更新时间的时间戳。
```
{
"parts": [
{
"partNumber": 1,
"partSize": 104857600,
"partSource": "SOURCE1",
"checksum": "MVMQk+vB9C3Ge8ADHkbKq752n3BCUzyl41qEkqlOD5M=",
"creationTime": "2023-11-20T23:58:03.500823+00:00",
"lastUpdatedTime": "2023-11-20T23:58:03.500831+00:00"
},
{
"partNumber": 2,
"partSize": 104857600,
"partSource": "SOURCE1",
"checksum": "keZzVzJNChAqgOdZMvOmjBwrOPM0enPj1UAfs0nvRto=",
"creationTime": "2023-11-21T00:02:03.813013+00:00",
"lastUpdatedTime": "2023-11-21T00:02:03.813025+00:00"
},
{
"partNumber": 3,
"partSize": 100339539,
"partSource": "SOURCE1",
"checksum": "TBkNfMsaeDpXzEf3ldlbi0ipFDPaohKHyZ+LF1J4CHk=",
"creationTime": "2023-11-21T00:09:11.705198+00:00",
"lastUpdatedTime": "2023-11-21T00:09:11.705208+00:00"
}
]
}
```
1. 要查看所有活跃的分段读取集上传，请使用 up **list-multipart-read-setloads，**如下所示。`sequence store ID`替换为您自己的序列存储的 ID。
```
aws omics list-multipart-read-set-uploads --sequence-store-id
sequence store ID
```
此 API 仅返回正在进行的分段读取集上传。在提取的读取集之后`ACTIVE`，或者如果上传失败，则不会在对 uploads API 的响应中返回上**list-multipart-read-set传**。要查看活跃的读取集，请使用 **list-read-sets**API。**list-multipart-read-set上传**的响应示例如下所示。
```
{
"uploads": [
{
"sequenceStoreId": "1234567890",
"uploadId": "8749584421",
"sourceFileType": "FASTQ",
"subjectId": "mySubject",
"sampleId": "mySample",
"generatedFrom": "1000 Genomes",
"name": "HG00146",
"description": "FASTQ for HG00146",
"creationTime": "2023-11-29T19:22:51.349298+00:00"
},
{
"sequenceStoreId": "1234567890",
"uploadId": "5290538638",
"sourceFileType": "BAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"generatedFrom": "1000 Genomes",
"referenceArn": "arn:aws:omics:us-west-2:123456789012:referenceStore/8168613728/reference/2190697383",
"name": "HG00146",
"description": "BAM for HG00146",
"creationTime": "2023-11-29T19:23:33.116516+00:00"
},
{
"sequenceStoreId": "1234567890",
"uploadId": "4174220862",
"sourceFileType": "BAM",
"subjectId": "mySubject",
"sampleId": "mySample",
"generatedFrom": "1000 Genomes",
"referenceArn": "arn:aws:omics:us-west-2:123456789012:referenceStore/8168613728/reference/2190697383",
"name": "HG00147",
"description": "BAM for HG00147",
"creationTime": "2023-11-29T19:23:47.007866+00:00"
}
]
}
```
1. 上传文件的所有部分后，使用 **complete-multipart-read-set-** upload 结束上传过程，如以下示例所示。用您自己的值替换`sequence store ID`零件的`upload ID`、和参数。
```
aws omics complete-multipart-read-set-upload \
--sequence-store-id sequence store ID \
--upload-id upload ID \
--parts '[{"checksum":"gaCBQMe+rpCFZxLpoP6gydBoXaKKDA/Vobh5zBDb4W4=","partNumber":1,"partSource":"SOURCE1"}]'
```
**complete-multipart-read-set-uploa** d 的响应是您导入的读 IDs 取集的读取集。
```
{
"readSetId": "0000000001"
}
```
1. 要停止上传，请使用带有**abort-multipart-read-set上传 ID 的-** upload 来结束上传过程。`upload ID`用您自己的参数值替换`sequence store ID`和。
```
aws omics abort-multipart-read-set-upload \
--sequence-store-id sequence store ID \
--upload-id upload ID
```
1. 上传完成后，使用从读取集中检索数据 **get-read-set**，如下所示。如果上传仍在处理中，则**get-read-set**返回有限的元数据，并且生成的索引文件不可用。`sequence store ID`用您自己的输入替换和其他参数。
```
aws omics get-read-set
--sequence-store-id sequence store ID \
--id read set ID \
--file SOURCE1 \
--part-number 1 myfile.fastq.gz
```
1. 要检查元数据，包括上传状态，请使用 **get-read-set-metadata**API 操作。
```
aws omics get-read-set-metadata --sequence-store-id sequence store ID --id read set ID
```
响应包含元数据详细信息，例如文件类型、引用 ARN、文件数量和序列长度。它还包括状态。可能的状态是`PROCESSING_UPLOAD``ACTIVE`、和。`UPLOAD_FAILED`
```
{
"id": "0000000001",
"arn": "arn:aws:omics:us-west-2:555555555555:sequenceStore/0123456789/readSet/0000000001",
"sequenceStoreId": "0123456789",
"subjectId": "mySubject",
"sampleId": "mySample",
"status": "PROCESSING_UPLOAD",
"name": "HG00146",
"description": "FASTQ for HG00146",
"fileType": "FASTQ",
"creationTime": "2022-07-13T23:25:20Z",
"files": {
"source1": {
"totalParts": 5,
"partSize": 123456789012,
"contentLength": 6836725,
},
"source2": {
"totalParts": 5,
"partSize": 123456789056,
"contentLength": 6836726
}
},
'creationType": "UPLOAD"
}
```
## 配置备用位置
创建或更新序列存储时，您可以将 Amazon S3 存储桶配置为上传失败的文件的备用位置。这些读取集的文件部分被传输到备用位置。备用位置可用于 2023 年 5 月 15 日之后创建的序列存储。
创建 Amazon S3 存储桶策略以授予对 Amazon S3 备用位置的 HealthOmics 写入权限，如以下示例所示：
```
{
"Effect": "Allow",
"Principal": {
"Service": "omics.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
```
如果用于备用或访问日志的 Amazon S3 存储桶使用客户托管密钥，请向密钥策略添加以下权限：
```
{
"Sid": "Allow use of key",
"Effect": "Allow",
"Principal": {
"Service": "omics.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*"
],
"Resource": "*"
}
```
# 将 HealthOmics 读取集导出到 Amazon S3 存储桶
您可以将读取集作为批量导出任务导出到 Amazon S3 存储桶。为此，请先创建一个具有存储桶写入权限的 IAM 策略，类似于以下 IAM 策略示例。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket1",
"arn:aws:s3:::amzn-s3-demo-bucket1/*"
]
}
]
}
```
------
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"omics.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
IAM 策略到位后，开始您的读取集导出任务。以下示例向您展示了如何使用 **start-read-set-export-job** API 操作来执行此操作。在以下示例中，将所有参数（例如、`sequence store ID``destination``role ARN``sources`、和）替换为您的输入。
```
aws omics start-read-set-export-job
--sequence-store-id sequence store id \
--destination valid s3 uri \
--role-arn role ARN \
--sources readSetId=read set id_1 readSetId=read set id_2
```
您会收到以下响应，其中包含有关源序列存储和目标 Amazon S3 存储桶的信息。
```
{
"id": ,
"sequenceStoreId": ,
"destination": ,
"status": "SUBMITTED",
"creationTime": "2022-10-22T01:33:38.079000+00:00"
}
```
作业启动后，您可以使用 **get-read-set-export-job** API 操作确定其状态，如下所示。将`sequence store ID`和`job ID`分别替换为您的序列存储 ID 和作业 ID。
```
aws omics get-read-set-export-job --id job-id --sequence-store-id sequence store ID
```
您可以使用 ** list-read-set-export-jobs API 操作查看为序列存储初始化的所有导出作业**，如下所示。`sequence store ID`用您的序列存储 ID 替换。
```
aws omics list-read-set-export-jobs --sequence-store-id sequence store ID.
```
```
{
"exportJobs": [
{
"id": ,
"sequenceStoreId": ,
"destination": ,
"status": "COMPLETED",
"creationTime": "2022-10-22T01:33:38.079000+00:00",
"completionTime": "2022-10-22T01:34:28.941000+00:00"
}
]
}
```
除了导出读取集外，您还可以使用 Amazon S3 访问权限共享读取集 URIs。要了解更多信息，请参阅[使用 Amazon S3 访问 HealthOmics 读取集 URIs](s3-access.md)。
# 使用 Amazon S3 访问 HealthOmics 读取集 URIs
您可以使用 Amazon S3 URI 路径来访问您的活动序列存储读取集。
通过 Amazon S3 URI 路径，您可以使用 Amazon S3 操作列出、共享和下载您的读取集。鉴于许多行业工具已经构建为可从 S3 读取，因此通过 S3 进行访问可以 APIs 加快协作和工具集成。此外，您可以 APIs 与其他账户共享对 S3 的访问权限，并提供对数据的跨区域读取权限。
HealthOmics 不支持 Amazon S3 URI 访问存档的读取集。当您激活读取集时，它每次都会恢复到相同的 URI 路径。
将数据加载到 HealthOmics 商店后，由于 Amazon S3 URI 基于 Amazon S3 接入点，因此您可以直接与读取 Amazon S3 的行业标准工具集成 URIs，例如：
+ 视觉分析应用程序，例如综合基因组学查看器 (IGV) 或加州大学圣地亚哥分校基因组浏览器。
+ 使用 Amazon S3 扩展程序（例如 CWL、WDL 和 Nextflow）的常见工作流程。
+ 任何可以从接入点 Amazon S3 进行身份验证和读取 URIs 或读取预签名的 Amazon S3 URIs 的工具。
+ Amazon S3 实用工具，例如 Mountpoint 或。 CloudFront
Amazon S3 Mountpoint 使您可以将 Amazon S3 存储桶用作本地文件系统。要了解有关 Mountpoint 的更多信息并安装它以供使用，请参阅适用于 [Amazon S3 的 Mountpo](https://github.com/awslabs/mountpoint-s3) int。
Amazon CloudFront 是一项内容分发网络 (CDN) 服务，专为高性能、安全性和开发者便利性而构建。要了解有关使用亚马逊的更多信息 CloudFront[，请参阅亚马逊 CloudFront 文档](https://docs.aws.amazon.com/cloudfront/)。要设置 CloudFront 序列存储，请联系 AWS HealthOmics 团队。
数据所有者根账户已启用序列存储前缀上的 S3: GetObject、S3: GetObjectTagging 和 S3: List Bucket 操作。要让账户中的用户访问数据，您可以创建一个 IAM 策略并将其附加到该用户或角色。有关策略示例，请参阅 [使用 Amazon S3 访问数据的权限 URIs](s3-sharing.md)。
您可以对活动读取集使用以下 Amazon S3 API 操作来列出和检索您的数据。激活存档读取集 URIs 后，您可以通过 Amazon S3 访问这些读取集。
+ [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)— 从 Amazon S3 检索对象。
+ [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html.html)— HEAD 操作从对象检索元数据，而不返回对象本身。如果您只需要对象的元数据，则此操作很有用。
+ [ListObjects 和 ListObject v2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)-返回存储桶中的部分或全部（最多 1,000 个）对象。
+ [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)— 创建已存储在 Amazon S3 中的对象的副本。 HealthOmics支持复制到 Amazon S3 接入点，但不支持写入到接入点。
HealthOmics 序列存储通过 ETags维护文件的语义标识。在文件的整个生命周期中，基于按位身份的 Amazon S3 ETag 可能会发生变化，但 HealthOmics ETag 保持不变。要了解更多信息，请参阅[HealthOmics ETags 和数据来源](etags-and-provenance.md)。
**Topics**
+ [HealthOmics 存储中的亚马逊 S3 URI 结构](#s3-uri-structure)
+ [使用托管或本地 IGV 访问读取集](#s3-access-igv)
+ [使用 Samtools 或者 HTSlib 在 HealthOmics](#s3-access-Samtools)
+ [使用挂载点 HealthOmics](#s3-access-Mountpoint)
+ [CloudFront 与一起使用 HealthOmics](#s3-access-CloudFront)
## HealthOmics 存储中的亚马逊 S3 URI 结构
所有带有 Amazon S3 的文件 URIs `omics:subjectId`都有`omics:sampleId`资源标签。您可以使用这些标签通过以下模式使用 IAM 策略来共享访问权限`"s3:ExistingObjectTag/omics:subjectId": "pattern desired"`。
文件结构如下：
`.../account_id/sequenceStore/seq_store_id/readSet/read_set_id/files.`
对于从 Amazon S3 导入到序列存储中的文件，序列存储会尝试保留原始源名称。当名称冲突时，系统会附加读取集信息以确保文件名是唯一的。例如，对于 fastq 读取集，如果两个文件名相同，则为了使名称唯一，`sourceX`则将其插入到.fastq.gz 或.fq.gz 之前。对于直接上传，文件名遵循以下模式：
+ 对于 FASTQ — *read\$1set\$1name* \$1 *sourcex* .fastq.gz
+ 对于 uBAM/BAM/CRAM —*read\$1set\$1name*. *file extension*扩展名为`.bam`或`.cram`。例如，`NA193948.bam`。
对于 BAM 或 CRAM 的读取集，将在摄取过程中自动生成索引文件。对于生成的索引文件，将在文件名末尾应用正确的索引扩展名。它的模式索*..*引扩展名是`.bai`或`.crai`。
## 使用托管或本地 IGV 访问读取集
IGV 是一款用于分析 BAM 和 CRAM 文件的基因组浏览器。它同时需要文件和索引，因为它一次只能显示基因组的一部分。IGV 可以在本地下载和使用，还有创建 AWS 托管的 IGV 的指南。不支持公共网络版本，因为它需要 CORS。
本地 IGV 依靠本地 AWS 配置来访问文件。确保该配置中使用的角色附加了一个策略，该策略启用 kms: Decrypt 和 s3: 对正在访问的读取集的 s3 URI 的GetObject 权限。之后，在 IGV 中，您可以使用 “文件 > 从 URL 加载”，然后粘贴源和索引的 URI。或者，也可以以相同的方式生成和使用预签名 URLs ，这将绕过 AWS 配置。请注意，Amazon S3 URI 访问不支持 CORS，因此不支持依赖跨域访问的请求。
示例 AWS 托管 IGV 依靠 AWS Cognito 在环境内部创建正确的配置和权限。确保创建的策略启用 KMS: Decrypt 和 s3: 对GetObject正在访问的读取集的 Amazon S3 URI 的权限，并将此策略添加到分配给 Cognito 用户池的角色中。之后，在 IGV 中，您可以使用 “文件 > 从 URL 加载” 并输入源和索引的 URI。或者， URLs 可以按相同的方式生成和使用预签名，从而绕过 AWS 配置。
请注意，序列存储不会显示在 “Amazon” 选项卡下，因为这只会显示配置 AWS 文件所在区域中您拥有的存储桶。
## 使用 Samtools 或者 HTSlib 在 HealthOmics
HTSlib 是由 Samtools、RSamTools 等多种工具共享的核心库。 PySam使用 1.20 或更高 HTSlib 版本获得对 Amazon S3 接入点的无缝支持。对于 HTSlib 库的旧版本，您可以使用以下解决方法：
+ 使用:设置 HTS Amazon S3 主机的环境变量`export HTS_S3_HOST="s3.region.amazonaws.com"`。
+ 为您要使用的文件生成预签名 URL。如果正在使用 BAM 或 CRAM，请确保为文件和索引生成预签名 URL。之后，两个文件都可以与库一起使用。
+ 使用 Mountpoint 在使用 HTSlib 库的相同环境中挂载序列存储或读取集前缀。从这里，可以使用本地文件路径访问这些文件。
## 使用挂载点 HealthOmics
适用于 Amazon S3 的 Mountpoint 是一款简单、高吞吐量的文件客户端，用于[将 Amazon S3 存储桶作为本地文件系统进行安装](https://aws.amazon.com/blogs/storage/the-inside-story-on-mountpoint-for-amazon-s3-a-high-performance-open-source-file-client/)。借助适用于 Amazon S3 的 Mountpoint，您的应用程序可以通过文件操作（例如打开和读取）访问存储在 Amazon S3 中的对象。适用于 Amazon S3 的 Mountpoint 会自动将这些操作转换为 Amazon S3 对象 API 调用，从而使您的应用程序能够通过文件接口访问 Amazon S3 的弹性存储和吞吐量。
可以使用 Mountpoint 安装说明来安装 M [ount](https://github.com/awslabs/mountpoint-s3/blob/main/doc/INSTALL.md) point。Mountpoint 使用安装本地的 AWS 配置文件，在 Amazon S3 前缀级别上运行。确保正在使用的配置文件具有启用对正在访问的读取集或序列存储的 Amazon S3 URI 前缀的 s3: ListBucket、s3: 和 kms:解密权限的策略。GetObject之后，可以使用以下路径挂载存储桶：
```
mount-s3 access point arn local path to mount --prefix prefix to sequence store or read set --region region
```
## CloudFront 与一起使用 HealthOmics
Amazon CloudFront 是一项内容分发网络 (CDN) 服务，专为实现高性能、安全性和开发者便利性而构建。想要使用的客户 CloudFront 必须与服务团队合作才能开启 CloudFront 分发。与您的客户团队合作，与 HealthOmics 服务团队合作。
# 在中激活读取集 HealthOmics
您可以激活使用 **start-read-set-activation-job** API 操作或通过存档的读取集 AWS CLI，如以下示例所示。将`sequence store ID`和`read set id`替换为您的序列存储 ID 和读取集 IDs。
```
aws omics start-read-set-activation-job
--sequence-store-id sequence store ID \
--sources readSetId=read set ID readSetId=read set id_1 read set id_2
```
您会收到一条包含激活任务信息的响应，如下所示。
```
{
"id": "12345678",
"sequenceStoreId": "1234567890",
"status": "SUBMITTED",
"creationTime": "2022-10-22T00:50:54.670000+00:00"
}
```
激活作业启动后，您可以使用 **get-read-set-activation-job** API 操作监控其进度。以下是如何使用 AWS CLI 来检查激活任务状态的示例。将`job ID`和`sequence store ID`分别替换为您的序列存储 ID 和作 IDs业。
```
aws omics get-read-set-activation-job --id job ID --sequence-store-id sequence store ID
```
响应汇总了激活作业，如下所示。
```
{
"id": 123567890,
"sequenceStoreId": 123467890,
"status": "SUBMITTED",
"statusUpdateReason": "The job is submitted and will start soon.",
"creationTime": "2022-10-22T00:50:54.670000+00:00",
"sources": [
{
"readSetId": ,
"status": "NOT_STARTED",
"statusUpdateReason": "The source is queued for the job."
},
{
"readSetId": ,
"status": "NOT_STARTED",
"statusUpdateReason": "The source is queued for the job."
}
]
}
```
您可以通过 **get-read-set-metadata**API 操作检查激活任务的状态。可能的状态是`ACTIVE``ACTIVATING`、和。`ARCHIVED`在以下示例中，`sequence store ID`替换为您的序列存储 ID，然后`read set ID`替换为您的读取集 ID。
```
aws omics get-read-set-metadata --sequence-store-id sequence store ID --id read set ID
```
以下响应显示读取集处于活动状态。
```
{
"id": "12345678",
"arn": "arn:aws:omics:us-west-2:555555555555:sequenceStore/1234567890/readSet/12345678",
"sequenceStoreId": "0123456789",
"subjectId": "mySubject",
"sampleId": "mySample",
"status": "ACTIVE",
"name": "HG00100",
"description": "HG00100 aligned to HG38 BAM",
"fileType": "BAM",
"creationTime": "2022-07-13T23:25:20Z",
"sequenceInformation": {
"totalReadCount": 1513467,
"totalBaseCount": 163454436,
"generatedFrom": "Pulled from SRA",
"alignment": "ALIGNED"
},
"referenceArn": "arn:aws:omics:us-west-2:555555555555:referenceStore/0123456789/reference/0000000001",
"files": {
"source1": {
"totalParts": 2,
"partSize": 10485760,
"contentLength": 17112283,
"s3Access": {
"s3Uri": "s3://accountID-sequence store ID-ajdpi90jdas90a79fh9a8ja98jdfa9jf98-s3alias/592761533288/sequenceStore/2015356892/readSet/9515444019/import_source1.fastq.gz"
},
},
"index": {
"totalParts": 1,
"partSize": 53216,
"contentLength": 10485760
"s3Access": {
"s3Uri": "s3://accountID-sequence store ID-ajdpi90jdas90a79fh9a8ja98jdfa9jf98-s3alias/592761533288/sequenceStore/2015356892/readSet/9515444019/import_source1.fastq.gz"
},
}
},
"creationType": "IMPORT",
"etag": {
"algorithm": "BAM_MD5up",
"source1": "d1d65429212d61d115bb19f510d4bd02"
}
}
```
您可以使用 **list-read-set-activation-jobs 查看所有读取集激活作业**，如以下示例所示。在以下示例中，`sequence store ID`替换为您的序列存储 ID。
```
aws omics list-read-set-activation-jobs --sequence-store-id sequence store ID
```
您会收到以下回复。
```
{
"activationJobs": [
{
"id": 1234657890,
"sequenceStoreId": "1234567890",
"status": "COMPLETED",
"creationTime": "2022-10-22T01:33:38.079000+00:00",
"completionTime": "2022-10-22T01:34:28.941000+00:00"
}
]
}
```