本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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 URIs 存取 HealthOmics 讀取集](s3-access.md)
+ [在 HealthOmics 中啟用讀取集](activating-read-sets.md)
# HealthOmics ETags和資料來源
HealthOmics ETag （實體標籤） 是序列存放區中擷取內容的雜湊。這可簡化資料擷取和處理，同時維持擷取資料檔案的內容完整性。ETag 會反映物件語意內容的變更，而非其中繼資料。指定的讀取集類型和演算法決定如何計算 ETag。ETag 計算不會改變實際的檔案或基因體資料。當讀取集的檔案類型結構描述允許時，序列存放區會更新連結至資料來源的欄位。
檔案具有位元身分和語意身分。位元身分表示檔案的位元相同，語意身分表示檔案的內容相同。語意身分在擷取檔案的內容完整性時，對中繼資料變更和壓縮變更具有彈性。
HealthOmics 序列存放區中的讀取集會在整個物件的生命週期進行壓縮/解壓縮週期和資料來源追蹤。在此處理期間，擷取檔案的位元身分可能會變更，並預期每次啟動檔案時都會變更；不過，會維護檔案的語意身分。語意身分會擷取為 HealthOmics 實體標籤，或在序列存放區擷取期間計算的 ETag，並以讀取集中繼資料的形式提供。
當讀取集的檔案類型結構描述允許時，序列存放區更新欄位會連結至資料來源。對於 uBAM、BAM 和 CRAM 檔案，新的 `@CO`或 `Comment`標籤會新增至 標頭。註解包含序列存放區 ID 和擷取時間戳記。
## Amazon S3 ETags
使用 Amazon S3 URI 存取檔案時，Amazon S3 API 操作也可能傳回 Amazon 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 是從擷取檔案內容的雜湊產生。ETag 演算法系列預設為 MD5up，但可以在序列存放區建立期間以不同方式設定。計算 ETag 時，演算法和計算的雜湊會新增至讀取集。檔案類型支援的 MD5 演算法如下所示。
+ *FASTQ\$1MD5up* – 計算未壓縮、完整 FASTQ 讀取集來源的 MD5 雜湊。
+ *BAM\$1MD5up* – 計算未壓縮 BAM 或 uBAM 讀取集來源的對齊區段的 MD5 雜湊，如 SAM 所示，如果有連結的參考可用的話。
+ *CRAM\$1MD5up* – 根據連結的參考，計算未壓縮 CRAM 讀取集來源之對齊區段的 MD5 雜湊，如 SAM 中所表示。
**注意**
已知 MD5 雜湊容易遭受碰撞。因此，如果兩個不同的檔案為了利用已知的碰撞而製造，則可能具有相同的 ETag。
SHA256 系列支援下列演算法。演算法的計算方式如下：
+ *FASTQ\$1SHA256up* – 計算未壓縮、完整 FASTQ 讀取集來源的 SHA-256 雜湊。
+ *BAM\$1SHA256up* – 計算未壓縮 BAM 或 uBAM 讀取集來源的對齊區段的 SHA-256 雜湊，如 SAM 所示，如果可用，則根據連結的參考。
+ *CRAM\$1SHA256up* – 根據連結的參考，計算未壓縮 CRAM 讀取集來源之對齊區段的 SHA-256 雜湊，如 SAM 所示。
SHA512 系列支援下列演算法。演算法的計算方式如下：
+ *FASTQ\$1SHA512up* – 計算未壓縮、完整 FASTQ 讀取集來源的 SHA-512 雜湊。
+ *BAM\$1SHA512up* – 計算未壓縮 BAM 或 uBAM 讀取集來源的對齊區段的 SHA-512 雜湊，如 SAM 所示，如果可用，則根據連結的參考。
+ *CRAM\$1SHA512up * – 根據連結的參考，計算未壓縮 CRAM 讀取集來源之對齊區段的 SHA-512 雜湊，如 SAM 所示。
# 建立 HealthOmics 參考存放區
HealthOmics 中的參考存放區是用於儲存參考基因體的資料存放區。您可以在每個 AWS 帳戶 和區域中擁有單一參考存放區。您可以使用 主控台或 CLI 建立參考存放區。
**Topics**
+ [使用主控台建立參考存放區](#console-create-reference-store)
+ [使用 CLI 建立參考存放區](#api-create-reference-store)
## 使用主控台建立參考存放區
**建立參考存放區**
1. 開啟 [HealthOmics 主控台](https://console.aws.amazon.com/omics/)。
1. 如有需要，請開啟左側導覽窗格 (≡)。選擇**參考存放區**。
1. 從 Genomics 資料儲存選項中選擇**參考基因體**。
1. 您可以選擇先前匯入的參考基因體，或匯入新的參考基因體。如果您尚未匯入參考基因體，請選擇右上角的**匯入參考基因體**。
1. 在**建立參考基因體匯入任務**頁面上，選擇**快速建立**或**手動建立**選項來建立參考存放區，然後提供下列資訊。
+ **參考基因體名稱** - 此存放區的唯一名稱。
+ **描述** （選用） - 此參考存放區的描述。
+ **IAM 角色** - 選取可存取參考基因體的角色。
+ **來自 Amazon S3 的參考** - 選取 Amazon S3 儲存貯體中的參考序列檔案。
+ **標籤 **（選用） - 為此參考存放區提供最多 50 個標籤。
## 使用 CLI 建立參考存放區
下列範例說明如何使用 建立參考存放區 AWS CLI。每個 AWS 區域可以有一個參考存放區。
參考存放區支援儲存副檔名為 `.fasta`、`.fa`、`.fas`、`.fsa`、`.faa`、`.fna`、`.ffn`、`.frn``.mpfa`、、、 `.seq`的 FASTA 檔案`.txt`。也支援這些擴充功能的`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"
}
]
}
```
------
您現在可以匯入參考基因體。此範例使用 Genome Reference Consortium Human Build 38 (hg38)，這是開放存取，可從 [上的開放資料登錄 AWS](https://registry.opendata.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
```
然後，您可以開始匯入任務。`source file path` 使用您自己的輸入取代 `reference store ID``role ARN`、 和 。
```
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`將 取代為您的參考存放區 ID，並將 取代`reference ID`為您想要進一步了解的參考 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`為參考存放區 ID，並將 `reference ID` 取代為您要從中下載的參考 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 存取許可，以透過 Amazon S3 getObjectTagging API 操作查看傳播的標籤。
1. 在文字方塊中輸入一個索引鍵值。主控台會建立新的文字方塊，以新增下一個金鑰。
1. （選用） 選擇**移除**以移除所有金鑰。
1. 在**資料加密**下，選取您希望資料加密由 擁有和管理， AWS 還是使用客戶受管 CMK。
1. （選用） 在 **S3 資料存取**下，選取是否要建立新的角色和政策，以透過 Amazon S3 存取序列存放區。
1. （選用） 對於 **S3 存取記錄**，`Enabled`如果您希望 Amazon S3 收集存取日誌記錄，請選取 。
對於 ** S3 中的存取記錄位置**，指定要存放日誌的 Amazon S3 位置。只有在您啟用 S3 存取記錄時，才會顯示此欄位。
1. **標籤 **（選用） - 為此序列存放區提供最多 50 個標籤。這些標籤與讀取集匯入/標籤更新期間設定的讀取集標籤不同
建立 存放區後，即可使用 [匯入基因體檔案](#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"
}
]
}
```
您可以使用 **get-sequence-store** 來進一步了解序列存放區，方法是使用其 ID，如下列範例所示：
```
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`為您的參考存放區 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**
+ [將檔案上傳至 Amazon 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)
## 將檔案上傳至 Amazon 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
```
此範例中`CRAM`使用的範例 `BAM` 和 需要不同的基因體參考 `Hg19`和 `Hg38`。若要進一步了解或存取這些參考，請參閱 [上的開放資料登錄檔中的廣泛 Genome 參考](https://registry.opendata.aws/broad-references/) AWS。
## 建立清單檔案
您還必須在 JSON 中建立資訊清單檔案，以在 中建立匯入任務的模型 `import.json`（請參閱下列範例）。如果您在主控台中建立序列存放區，則不需要指定 `sequenceStoreId`或 `roleARN`，因此資訊清單檔案會從 `sources` 輸入開始。
------
#### [ API manifest ]
下列範例使用 API 匯入三個讀取集：一個 `BAM`、`FASTQ`一個 和一個 `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 URIs 存取 HealthOmics 讀取集](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 Transfer Manager 下載 HealthOmics 參考或讀取集的檔案。您可以[在這裡](https://pypi.org/project/amazon-omics-tools/)下載 HealthOmics Transfer Manager。如需使用和設定 Transfer Manager 的詳細資訊，請參閱此 [GitHub 儲存庫](https://github.com/awslabs/amazon-omics-tools/)。
# 直接上傳至 HealthOmics 序列存放區
我們建議您使用 HealthOmics Transfer Manager 將檔案新增至序列存放區。如需使用 Transfer Manager 的詳細資訊，請參閱此 [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-parts** 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. 若要檢視所有作用中的分段讀取集上傳，請使用 **list-multipart-read-set-uploads，**如下所示。`sequence store ID` 將 取代為您自己的序列存放區的 ID。
```
aws omics list-multipart-read-set-uploads --sequence-store-id
sequence store ID
```
此 API 只會傳回進行中的分段讀取集上傳。在擷取的讀取集為 之後`ACTIVE`，或者如果上傳失敗，則在對 **list-multipart-read-set-uploads** API 的回應中將不會傳回上傳。若要檢視作用中的讀取集，請使用 **list-read-sets** API。**list-multipart-read-set-uploads** 的範例回應如下所示。
```
{
"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**complete-multipart-read-set-upload** 的回應是匯入讀取集IDs。
```
{
"readSetId": "0000000001"
}
```
1. 若要停止上傳，請使用 **abort-multipart-read-set-upload** 搭配上傳 ID 來結束上傳程序。`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 儲存貯體政策，以授予 HealthOmics 對 Amazon S3 備用位置的寫入存取權，如下列範例所示：
```
{
"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 操作來執行此操作。在下列範例中，以您的輸入取代所有參數，例如 `sources`、、 `sequence store ID` `destination` `role ARN`和 。
```
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 URIs 存取 HealthOmics 讀取集](s3-access.md)。
# 使用 Amazon S3 URIs 存取 HealthOmics 讀取集
您可以使用 Amazon S3 URI 路徑來存取作用中的序列存放區讀取集。
透過 Amazon S3 URI 路徑，您可以使用 Amazon S3 操作來列出、共用和下載您的讀取集。透過 S3 APIs存取 可加速協作和工具整合，因為許多產業工具已建置為可從 S3 讀取。此外，您可以與其他帳戶共用對 S3 APIs存取權，並提供資料的跨區域讀取存取權。
HealthOmics 不支援 Amazon S3 URI 存取封存的讀取集。當您啟用讀取集時，每次都會還原至相同的 URI 路徑。
將資料載入 HealthOmics 存放區時，由於 Amazon S3 URI 是以 Amazon S3 存取點為基礎，因此您可以直接與讀取 Amazon S3 URIs 的業界標準工具整合，如下所示：
+ 視覺化分析應用程式，例如 Integrative Genomics Viewer (IGV) 或 UCSC Genome 瀏覽器。
+ 具有 Amazon S3 延伸模組的常見工作流程，例如 CWL、WDL 和 Nextflow。
+ 任何可以驗證和讀取存取點 Amazon S3 URIs 或讀取預先簽章 Amazon S3 URIs 的工具。
+ Amazon S3 公用程式，例如掛載點或 CloudFront。
Amazon S3 掛載點可讓您使用 Amazon S3 儲存貯體做為本機檔案系統。若要進一步了解掛載點並安裝以供使用，請參閱適用於 [Amazon S3 的掛載點](https://github.com/awslabs/mountpoint-s3)。
Amazon CloudFront 是一種內容交付網路 (CDN) 服務，專為高效能、安全性和開發人員便利性而打造。若要進一步了解如何使用 Amazon CloudFront，請參閱 [Amazon CloudFront 文件](https://docs.aws.amazon.com/cloudfront/)。若要使用序列存放區設定 CloudFront，請聯絡 AWS HealthOmics 團隊。
序列存放區字首上的動作 S3：GetObject、S3：GetObjectTagging 和 S3：List 儲存貯體已啟用資料擁有者根帳戶。若要讓帳戶中的使用者存取資料，您可以建立 IAM 政策，並將其連接到使用者或角色。如需政策範例，請參閱 [使用 Amazon S3 URIs 存取資料的許可](s3-sharing.md)。
您可以在作用中讀取集上使用下列 Amazon S3 API 操作來列出和擷取您的資料。啟用封存的讀取集後，您可以透過 Amazon S3 URIs 存取它們。
+ [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 儲存體中的 Amazon S3 URI 結構](#s3-uri-structure)
+ [使用託管或本機 IGV 存取讀取集](#s3-access-igv)
+ [在 HealthOmics 中使用 Samtools 或 HTSlib](#s3-access-Samtools)
+ [使用掛載點 HealthOmics](#s3-access-Mountpoint)
+ [搭配 HealthOmics 使用 CloudFront](#s3-access-CloudFront)
## HealthOmics 儲存體中的 Amazon S3 URI 結構
具有 Amazon S3 URIs 的所有檔案都有 `omics:sampleId` `omics:subjectId`和資源標籤。您可以使用這些標籤，透過 等模式使用 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 副檔*名，副檔名為 `.bam`或 `.cram`。例如，`NA193948.bam`。
對於 BAM 或 CRAM 的讀取集，索引檔案會在擷取過程中自動產生。對於產生的索引檔案，檔案名稱結尾會套用適當的索引副檔名。其模式*為 <索引所在的來源名稱>.<檔案索引延伸＞。*索引延伸為 `.bai`或 `.crai`。
## 使用託管或本機 IGV 存取讀取集
IGV 是一種用於分析 BAM 和 CRAM 檔案的基因體瀏覽器。它同時需要 檔案和 索引，因為它一次只會顯示一部分的基因體。IGV 可在本機下載和使用，並有建立 AWS 託管 IGV 的指南。不支援公有 Web 版本，因為它需要 CORS。
本機 IGV 依賴本機 AWS 組態來存取檔案。請確定該組態中使用的角色已連接政策，以啟用對所存取讀取集的 s3 URI 的 kms:Decrypt 和 s3：GetObject 許可。之後，在 IGV 中，您可以使用「從 URL 檔案 > 載入」並在 URI 中貼上來源和索引。或者，可以用相同的方式產生和使用預先簽章URLs，這會略過 AWS 組態。請注意，Amazon S3 URI 存取不支援 CORS，因此不支援依賴 CORS 的請求。
AWS 託管 IGV 範例依賴 AWS Cognito 在環境中建立正確的組態和許可。確保已建立政策以啟用 Amazon S3 URI 的 Amazon S3 URI：Decrypt 和 s3：GetObject 許可，並將此政策新增至指派給 Cognito 使用者集區的角色。之後，在 IGV 中，您可以使用「從 URL 檔案 > 載入」，然後在 URI 中輸入來源和索引。或者，可以用相同的方式產生和使用預先簽章URLs，這會略過 AWS 組態。
請注意，序列存放區不會出現在「Amazon」索引標籤下，因為 只會顯示您在設定 AWS 設定檔的區域中擁有的儲存貯體。
## 在 HealthOmics 中使用 Samtools 或 HTSlib
HTSlib 是由多種工具共用的核心程式庫，例如 Samtools、rSamtools、PySam 等。使用 HTSlib 1.20 版或更新版本，取得 Amazon S3 存取點的無縫支援。對於較舊版本的 HTSlib 程式庫，您可以使用下列解決方法：
+ 使用 設定 HTS Amazon S3 主機的環境變數：`export HTS_S3_HOST="s3.region.amazonaws.com"`。
+ 為您要使用的檔案產生預先簽章的 URL。如果使用 BAM 或 CRAM，請確保為檔案和索引產生預先簽章的 URL。之後，這兩個檔案都可以與程式庫搭配使用。
+ 使用掛載點，在您使用 HTSlib 程式庫的相同環境中掛載序列存放區或讀取集字首。從這裡，可以使用本機檔案路徑存取檔案。
## 使用掛載點 HealthOmics
Amazon S3 掛載點是簡單的高輸送量檔案用戶端，可將 [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 的掛載點，您的應用程式可以透過開啟和讀取等檔案操作存取存放在 Amazon S3 中的物件。Amazon S3 掛載點會自動將這些操作轉換為 Amazon S3 物件 API 呼叫，讓您的應用程式透過檔案界面存取 Amazon S3 的彈性儲存體和輸送量。
您可以使用掛載點安裝[指示來安裝掛載點](https://github.com/awslabs/mountpoint-s3/blob/main/doc/INSTALL.md)。掛載點使用安裝的本機 AWS 設定檔，可在 Amazon S3 字首層級運作。確保使用的設定檔具有啟用 s3：GetObject、s3：ListBucket 和 kms:Decrypt 許可的政策，以存取讀取集合或序列存放區的 Amazon S3 URI 字首 (Amazon S3 URI)。之後，可以使用下列路徑掛載儲存貯體：
```
mount-s3 access point arn local path to mount --prefix prefix to sequence store or read set --region region
```
## 搭配 HealthOmics 使用 CloudFront
Amazon CloudFront 是一種內容交付網路 (CDN) 服務，專為高效能、安全性和開發人員便利性而打造。想要使用 CloudFront 的客戶必須與 Service 團隊合作，以開啟 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"
}
]
}
```