本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立私有工作流程
使用 HealthOmics 主控台、 AWS CLI 命令或其中一個 AWS SDKs建立工作流程。
**注意**
請勿在工作流程名稱中包含任何個人身分識別資訊 (PII)。這些名稱會顯示在 CloudWatch 日誌中。
當您建立工作流程時，HealthOmics 會將通用唯一識別碼 (UUID) 指派給工作流程。工作流程 UUID 是全域唯一識別符 (guid)，在工作流程和工作流程版本中是唯一的。基於資料來源目的，我們建議您使用工作流程 UUID 來唯一識別工作流程。
如果您的工作流程任務使用任何外部工具 （可執行檔、程式庫或指令碼），您可以將這些工具建置到容器映像中。您有下列選項來託管容器映像：
+ 在 ECR 私有登錄檔中託管容器映像。此選項的先決條件：
+ 建立 ECR 私有儲存庫，或選擇現有的儲存庫。
+ 如中所述設定 ECR 資源政策[Amazon ECR 許可](permissions-ecr.md)。
+ 將您的容器映像上傳至私有儲存庫。
+ 同步容器映像與支援的第三方登錄檔的內容。此選項的先決條件：
+ 在 ECR 私有登錄檔中，為每個上游登錄檔設定提取快取規則。如需詳細資訊，請參閱[影像映射](workflows-ecr.md#ecr-pull-through-mapping-format)。
+ 如中所述設定 ECR 資源政策[Amazon ECR 許可](permissions-ecr.md)。
+ 建立儲存庫建立範本。範本定義 Amazon ECR 為上游登錄檔建立私有儲存庫時的 設定。
+ 建立字首映射，將工作流程定義中的容器映像參考重新映射至 ECR 快取命名空間。
當您建立工作流程時，您會提供工作流程定義，其中包含工作流程、執行和任務的相關資訊。HealthOmics 可以將工作流程定義擷取為儲存在本機或 Amazon S3 儲存貯體中的 .zip 封存檔，或從支援的 Git 型儲存庫擷取。
**Topics**
+ [使用主控台建立工作流程](#console-create-workflows)
+ [使用 CLI 建立工作流程](#api-create-workflows)
+ [使用 SDK 建立工作流程](#sdk-create-workflows)
## 使用主控台建立工作流程
**建立工作流程的步驟**
1. 開啟 [HealthOmics 主控台](https://console.aws.amazon.com/omics/)。
1. 如有需要，請開啟左側導覽窗格 (≡)。選擇**私有工作流程**。
1. 在**私有工作流程**頁面上，選擇**建立工作流程**。
1. 在**定義工作流程**頁面上，提供下列資訊：
1. **工作流程名稱**：此工作流程的獨特名稱。建議您設定工作流程名稱，以在 AWS HealthOmics 主控台和 CloudWatch 日誌中組織您的執行。
1. **描述** （選用）：此工作流程的描述。
1. 在**工作流程定義**面板中，提供下列資訊：
1. **工作流程語言** （選用）：選取工作流程的規格語言。否則，HealthOmics 會從工作流程定義判斷語言。
1. 對於**工作流程定義來源**，選擇從 Git 型儲存庫、Amazon S3 位置或從本機磁碟機匯入定義資料夾。
1. 對於**從儲存庫服務匯入**：
**注意**
HealthOmics 支援 GitHub、、GitLab、Bitbucket、 的公有和私有儲存庫GitHub self-managedGitLab self-managed。
1. 選擇**連線**，將您的 AWS 資源連線至外部儲存庫。若要建立連線，請參閱 [與外部程式碼儲存庫連線](setting-up-new.md#setting-up-omics-repository)。
**注意**
TLV 區域中的客戶需要在 IAD(us-east-1) 區域中建立連線，才能建立工作流程。
1. 在**完整儲存庫 ID** 中，將您的儲存庫 ID 輸入為 user-name/repo-name。確認您有權存取此儲存庫中的檔案。
1. 在**來源參考** （選用） 中，輸入儲存庫來源參考 （分支、標籤或遞交 ID)。如果未指定來源參考，HealthOmics 會使用預設分支。
1. 在**排除檔案模式中**，輸入檔案模式以排除特定資料夾、檔案或副檔名。這有助於在匯入儲存庫檔案時管理資料大小。最多有 50 個模式，而且 修補程式必須遵循 [glob 模式語法](https://fossil-scm.org/home/doc/tip/www/globs.md)。例如：
1. `tests/`
1. `*.jpeg`
1. `large_data.zip`
1. 對於**從 S3 選取定義資料夾**：
1. 輸入包含壓縮工作流程定義資料夾的 Amazon S3 位置。Amazon S3 儲存貯體必須與工作流程位於相同的區域。
1. 如果您的帳戶沒有 Amazon S3 儲存貯體，請在 S3 儲存貯體擁有者 AWS 的帳戶 ID 中輸入儲存貯體擁有者的帳戶 ID。 **S3 ** 需要此資訊，以便 HealthOmics 可以驗證儲存貯體擁有權。
1. 對於**從本機來源選取定義資料夾**：
1. 輸入壓縮工作流程定義資料夾的本機磁碟機位置。
1. **主要工作流程定義檔案路徑** （選用）：輸入從壓縮工作流程定義資料夾或儲存庫到`main`檔案的檔案路徑。如果工作流程定義資料夾中只有一個檔案，或主要檔案名為「主要」，則不需要此參數。
1. 在 **README 檔案** （選用） 面板中，選取 **README 檔案的來源**，並提供下列資訊：
+ 對於**從儲存庫服務匯入**，在 **README 檔案路徑**中，輸入儲存庫中 README 檔案的路徑。
+ 針對**從 S3 選取檔案**，在 ** S3 的 README 檔案中**，輸入 README 檔案的 Amazon S3 URI。
+ 對於**從本機來源選取檔案**：在 **README - 選用**中，選擇**選擇檔案**以選取要上傳的 Markdown (.md) 檔案。
1. 在**預設執行儲存組態**面板中，為使用此工作流程的執行提供預設執行儲存類型和容量：
1. **執行儲存體類型**：選擇是否使用靜態或動態儲存體做為暫時執行儲存體的預設值。預設為靜態儲存。
1. **執行儲存容量** （選用）：對於靜態執行儲存類型，您可以輸入此工作流程所需的預設執行儲存量。此參數的預設值為 1200 GiB。您可以在開始執行時覆寫這些預設值。
1. **標籤 **（選用）：您最多可以將 50 個標籤與此工作流程建立關聯。
1. 選擇**下一步**。
1. 在**新增工作流程參數** （選用） 頁面上，選取**參數來源**：
1. 對於**從工作流程定義檔案剖析**，HealthOmics 會自動從工作流程定義檔案剖析工作流程參數。
1. 對於**從 Git 儲存庫提供參數範本**，請使用從儲存庫到參數範本檔案的路徑。
1. 對於**從本機來源選取 JSON 檔案**，請從指定參數的本機來源上傳JSON檔案。
1. 對於**手動輸入工作流程參數**，手動輸入參數名稱和描述。
1. 在**參數預覽**面板中，您可以檢閱或變更此工作流程版本的參數。如果您還原JSON檔案，則會遺失您所做的任何本機變更。
1. 選擇**下一步**。
1. 在**容器 URI 重新映射**頁面上的**映射規則**面板中，您可以定義工作流程的 URI 映射規則。
針對**映射檔案的來源**，選取下列其中一個選項：
+ **無** – 不需要映射規則。
+ **從 S3 選取 JSON 檔案** – 指定映射檔案的 S3 位置。
+ **從本機來源選取 JSON 檔案** – 在本機裝置上指定映射檔案位置。
+ **手動輸入映射** – 在映射面板中輸入登錄映射和映像**映射**。
1. 主控台會顯示**映射**面板。如果您選擇映射來源檔案，主控台會顯示檔案中的值。
1. 在**登錄檔映射**中，您可以編輯映射或新增映射 （最多 20 個登錄檔映射）。
每個登錄檔映射都包含下列欄位：
+ **上游登錄檔 URL** – 上游登錄檔的 URI。
+ **ECR 儲存庫字**首 – 要在 Amazon ECR 私有儲存庫中使用的儲存庫字首。
+ （選用） **上游儲存庫字首** – 上游登錄檔中儲存庫的字首。
+ （選用） **ECR 帳戶 ID** – 擁有上游容器映像之帳戶的帳戶 ID。
1. 在**影像映射**中，您可以編輯影像映射或新增映射 （最多 100 個影像映射）。
每個影像映射都包含下列欄位：
+ **來源映像** – 指定上游登錄檔中來源映像的 URI。
+ **目的地映像**：指定私有 Amazon ECR 登錄檔中對應映像的 URI。
1. 選擇**下一步**。
1. 檢閱工作流程組態，然後選擇**建立工作流程**。
## 使用 CLI 建立工作流程
如果您的工作流程檔案和參數範本檔案位於本機電腦上，您可以使用下列 CLI 命令建立工作流程。
```
aws omics create-workflow \
--name "my_workflow" \
--definition-zip fileb://my-definition.zip \
--parameter-template file://my-parameter-template.json
```
`create-workflow` 操作會傳回下列回應：
```
{
"arn": "arn:aws:omics:us-west-2:....",
"id": "1234567",
"status": "CREATING",
"tags": {
"resourceArn": "arn:aws:omics:us-west-2:...."
},
"uuid": "64c9a39e-8302-cc45-0262-2ea7116d854f"
}
```
### 建立工作流程時要使用的選用參數
您可以在建立工作流程時指定任何選用參數。如需語法詳細資訊，請參閱 AWS HealthOmics API 參考中的 [CreateWorkflow](https://docs.aws.amazon.com/omics/latest/api/API_CreateWorkflow.html)。
**Topics**
+ [指定工作流程定義 Amazon S3 位置](#create-defn-uri-parameter)
+ [使用 Git 型儲存庫中的工作流程定義](#create-defn-uri-git)
+ [指定讀我檔案](#specify-readme-file)
+ [指定**main**定義檔案](#create-main-parameter)
+ [指定執行儲存體類型](#create-run-storage-parameter)
+ [指定 GPU 組態](#create-accelerator-parameter)
+ [設定提取快取映射參數](#create-prefix-mapping-parameters)
#### 指定工作流程定義 Amazon S3 位置
如果您的工作流程定義檔案位於 Amazon S3 資料夾，請使用 `definition-uri` 參數指定位置，如下列範例所示。如果您的帳戶未擁有 Amazon S3 儲存貯體，請提供擁有者的 AWS 帳戶 ID。
```
aws omics create-workflow \
--name Test \
--definition-uri s3://omics-bucket/workflow-definition/ \
--owner-id 123456789012
...
```
#### 使用 Git 型儲存庫中的工作流程定義
若要從支援的 Git 型儲存庫使用工作流程定義，請在請求中使用 `definition-repository` 參數。請勿提供任何其他`definition`參數，因為如果請求包含多個輸入來源，則請求會失敗。
`definition-respository` 參數包含下列欄位：
+ **connectionArn** – Code Connection 的 ARN，可將您的 AWS 資源連線至外部儲存庫。
+ **fullRepositoryId** – 將儲存庫 ID 輸入為 `owner-name/repo-name`。確認您有權存取此儲存庫中的檔案。
+ **sourceReference** （選用） – 輸入儲存庫參考類型 (BRANCH、TAG 或 COMMIT) 和值。
如果您未指定來源參考，HealthOmics 會在預設分支上使用最新的遞交。
+ **excludeFilePatterns** （選用） – 輸入檔案模式以排除特定資料夾、檔案或副檔名。這有助於在匯入儲存庫檔案時管理資料大小。提供最多 50 個模式。模式必須遵循 [ glob 模式語法](https://fossil-scm.org/home/doc/tip/www/globs.md)。例如：
+ `tests/`
+ `*.jpeg`
+ `large_data.zip`
當您從 Git 型儲存庫指定工作流程定義時，請使用 `parameter-template-path` 指定參數範本檔案。如果您不提供此參數，HealthOmics 會建立沒有參數範本的工作流程。
下列範例顯示與 Git 型私有儲存庫內容相關的參數：
```
aws omics create-workflow \
--name custom-variant \
--description "Custom variant calling pipeline" \
--engine "WDL" \
--definition-repository '{
"connectionArn": "arn:aws:codeconnections:us-east-1:123456789012:connection/abcd1234-5678-90ab-cdef-1234567890ab",
"fullRepositoryId": "myorg/my-genomics-workflows",
"sourceReference": {
"type": "BRANCH",
"value": "main"
},
"excludeFilePatterns": ["tests/**", "*.log"]
}' \
--main "workflows/variant-calling/main.wdl" \
--parameter-template-path "parameters/variant-calling-params.json" \
--readme-path "docs/variant-calling-README.md" \
--storage-type "DYNAMIC" \
```
如需更多範例，請參閱部落格文章[如何從 Git 中的內容建立 AWS HealthOmics 工作流程](https://repost.aws/articles/ARCEN7AjhaRSmteczRoc_QsA/how-to-create-an-aws-healthomics-workflows-from-content-in-git)。
#### 指定讀我檔案
您可以使用下列其中一個參數來指定 README 檔案位置：
+ **readme-markdown** – 字串輸入或本機電腦上的檔案。
+ **readme-uri** – 存放在 S3 上的檔案的 URI。
+ **readme-path ** – 儲存庫中 README 檔案的路徑。
僅使用 readme-path 搭配 **definition-respository**。如果您未指定任何 README 參數，HealthOmics 會在儲存庫中匯入根層級 README.md 檔案 （如果存在）。
下列範例示範如何使用 readme-path 和 readme-uri 指定 README 檔案位置。
```
# Using README from repository
aws omics create-workflow \
--name "documented-workflow" \
--definition-repository '...' \
--readme-path "docs/workflow-guide.md"
# Using README from S3
aws omics create-workflow \
--name "s3-readme-workflow" \
--definition-repository '...' \
--readme-uri "s3://my-bucket/workflow-docs/readme.md"
```
如需詳細資訊，請參閱[HealthOmics 工作流程 README 檔案](workflows-readme.md)。
#### 指定**main**定義檔案
如果您包含多個工作流程定義檔案，請使用 `main` 參數來指定工作流程的主要定義檔案。
```
aws omics create-workflow \
--name Test \
--main multi_workflow/workflow2.wdl \
...
```
#### 指定執行儲存體類型
您可以指定預設執行儲存類型 (DYNAMIC 或 STATIC)，並執行儲存容量 （靜態儲存需要）。如需執行儲存體類型的詳細資訊，請參閱 [在 HealthOmics 工作流程中執行儲存類型](workflows-run-types.md)。
```
aws omics create-workflow \
--name my_workflow \
--definition-zip fileb://my-definition.zip \
--parameter-template file://my-parameter-template.json \
--storage-type 'STATIC' \
--storage-capacity 1200 \
```
#### 指定 GPU 組態
使用 加速器參數來建立在加速運算執行個體上執行的工作流程。下列範例示範如何使用 `accelerators` 參數。您可以在工作流程定義中指定 GPU 組態。請參閱 [加速運算執行個體](memory-and-compute-tasks.md#workflow-task-accelerated-computing-instances)。
```
aws omics create-workflow --name workflow name \
--definition-uri s3://amzn-s3-demo-bucket1/GPUWorkflow.zip \
--accelerators GPU
```
#### 設定提取快取映射參數
如果您使用 Amazon ECR 提取快取映射功能，您可以覆寫預設映射。如需容器設定參數的詳細資訊，請參閱 [私有工作流程的容器映像](workflows-ecr.md)。
在下列範例中， 檔案`mappings.json`包含此內容：
```
{
"registryMappings": [
{
"upstreamRegistryUrl": "registry-1.docker.io",
"ecrRepositoryPrefix": "docker-hub"
},
{
"upstreamRegistryUrl": "quay.io",
"ecrRepositoryPrefix": "quay",
"accountId": "123412341234"
},
{
"upstreamRegistryUrl": "public.ecr.aws",
"ecrRepositoryPrefix": "ecr-public"
}
],
"imageMappings": [{
"sourceImage": "docker.io/library/ubuntu:latest",
"destinationImage": "healthomics-docker-2/custom/ubuntu:latest",
"accountId": "123412341234"
},
{
"sourceImage": "nvcr.io/nvidia/k8s/dcgm-exporter",
"destinationImage": "healthomics-nvidia/k8s/dcgm-exporter"
}
]
}
```
在 create-workflow 命令中指定映射參數：
```
aws omics create-workflow \
...
--container-registry-map-file file://mappings.json
...
```
您也可以指定映射參數檔案的 S3 位置：
```
aws omics create-workflow \
...
--container-registry-map-uri s3://amzn-s3-demo-bucket1/test.zip
...
```
## 使用 SDK 建立工作流程
您可以使用其中一個 SDKs建立工作流程。下列範例示範如何使用 Python SDK 建立工作流程
```
import boto3
omics = boto3.client('omics')
with open('definition.zip', 'rb') as f:
definition = f.read()
response = omics.create_workflow(
name='my_workflow',
definitionZip=definition,
parameterTemplate={ ... }
)
```