本頁面由 Cloud Translation API 翻譯而成。

在 Batch 上執行 dsub 管道，藉此自動化調度工作

本教學課程說明如何在 Batch 上執行 dsub pipeline。具體來說，這個範例 dsub 管道會處理二進位對齊對應 (BAM) 檔案中的 DNA 序列資料，建立 BAM 索引 (BAI) 檔案。

本教學課程適用於想要搭配 Batch 使用 dsub 的 Batch 使用者。dsub 是開放原始碼作業排程器，可自動化調度 Google Cloud上的批次處理工作流程。如要進一步瞭解如何搭配使用 Batch 與 dsub，請參閱 Batch 的 dsub 說明文件。

目標

在 Batch 上執行 dsub 管道，讀取及寫入 Cloud Storage 值區中的檔案。
在 Cloud Storage bucket 中查看輸出檔案。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

Batch
Cloud Storage

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用資格。

假設您及時完成所有步驟 (包括清除作業)，本教學課程建立的資源通常不會產生超過 $1 美元的費用。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

如果您使用外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

Install the Google Cloud CLI.

如果您使用外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

確認專案至少有一個服務帳戶，且該帳戶具備本教學課程所需的權限。

注意：如果您使用新專案，則不需要執行這個步驟，除非貴機構禁止預設服務帳戶自動取得角色。根據預設，系統會自動將編輯者 (roles/editor) IAM 角色授予 Compute Engine 預設服務帳戶，這個角色已具備本教學課程所需的所有權限。

每個作業都需要服務帳戶，Batch 服務代理程式才能建立及存取執行作業所需的資源。在本教學課程中，作業的服務帳戶是 Compute Engine 預設服務帳戶。

為確保 Compute Engine 預設服務帳戶具備必要權限，允許 Batch 服務代理建立及存取 Batch 作業的資源，請要求管理員授予 Compute Engine 預設服務帳戶下列 IAM 角色：

重要事項：您必須將這些角色授予 Compute Engine 預設服務帳戶，而非使用者帳戶。如果未將角色授予正確的主體，可能會導致權限錯誤。
- 批次工作代理程式回報者 (roles/batch.agentReporter) 專案
- 專案的儲存空間管理員 (roles/storage.admin)
- (建議) 讓作業在 Cloud Logging 中產生記錄：專案的「記錄檔寫入者」 (roles/logging.logWriter) 角色
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，授予 Compute Engine 預設服務帳戶必要權限。

請確認您具備本教學課程所需的權限。

注意：如果您建立了這個專案，則不需要執行這個步驟。身為專案建立者，您會自動獲授予擁有者 (roles/owner) IAM 角色，這個角色已具備本教學課程所需的所有權限。

如要取得完成本教學課程所需的權限，請要求管理員授予下列 IAM 角色：
- 批次工作編輯者 (roles/batch.jobsEditor) 專案
- 服務帳戶使用者 (roles/iam.serviceAccountUser) 在作業的服務帳戶上，本教學課程使用的是 Compute Engine 預設服務帳戶
- 專案的Storage 物件管理員 (roles/storage.objectAdmin)

安裝 dsub 及其依附元件。詳情請參閱dsub安裝說明文件。

請確認您已安裝最新版 dsub 支援的 Python 和 pip 版本。如要查看目前安裝的版本，請執行下列指令：
```
pip --version
```
如需安裝或更新 pip 或 Python，請按照安裝 Python 的步驟操作。
建議：為避免安裝 dsub 時發生依附元件衝突錯誤，請建立並啟用 Python 虛擬環境：
```
python -m venv dsub_libs && source dsub_libs/bin/activate
```

使用 git 複製 dsub GitHub 存放區，然後開啟：

git clone https://github.com/databiosphere/dsub.git && cd dsub

安裝 dsub 及其依附元件：

python -m pip install .

輸出結果會與下列內容相似：

...
Successfully installed cachetools-5.3.1 certifi-2023.7.22 charset-normalizer-3.3.1 dsub-0.4.9 funcsigs-1.0.2 google-api-core-2.11.0 google-api-python-client-2.85.0 google-auth-2.17.3 google-auth-httplib2-0.1.0 google-cloud-batch-0.10.0 googleapis-common-protos-1.61.0 grpcio-1.59.0 grpcio-status-1.59.0 httplib2-0.22.0 idna-3.4 mock-4.0.3 parameterized-0.8.1 proto-plus-1.22.3 protobuf-4.24.4 pyasn1-0.4.8 pyasn1-modules-0.2.8 pyparsing-3.1.1 python-dateutil-2.8.2 pytz-2023.3 pyyaml-6.0 requests-2.31.0 rsa-4.9 six-1.16.0 tabulate-0.9.0 tenacity-8.2.2 uritemplate-4.1.1 urllib3-2.0.7

建立 Cloud Storage 值區

如要使用 gcloud CLI 建立 Cloud Storage bucket，以便儲存範例 dsub 管道的輸出檔案，請執行 gcloud storage buckets create 指令：

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

更改下列內容：

BUCKET_NAME：值區的全域不重複名稱。
PROJECT_ID：您的 Google Cloud 專案的專案 ID。

輸出結果會與下列內容相似：

Creating gs://BUCKET_NAME/...

執行 `dsub` 管道

範例 dsub 管道會為 1,000 種基因體專案中的 BAM 檔案建立索引，並將結果輸出至 Cloud Storage 值區。

如要執行範例 dsub 管道，請執行下列 dsub 指令：

dsub \
    --provider google-batch \
    --project PROJECT_ID \
    --logging gs://BUCKET_NAME/WORK_DIRECTORY/logs \
    --input BAM=gs://genomics-public-data/1000-genomes/bam/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam \
    --output BAI=gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai \
    --image quay.io/cancercollaboratory/dockstore-tool-samtools-index \
    --command 'samtools index ${BAM} ${BAI}' \
    --wait

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案的專案 ID。
BUCKET_NAME：您建立的 Cloud Storage bucket 名稱。
WORK_DIRECTORY：新目錄的名稱，管道可用於儲存記錄和輸出內容。例如輸入 workDir。

dsub 管道會執行 Batch 工作，將 BAI 檔案和記錄寫入 Cloud Storage bucket 中的指定目錄。具體來說，dsub 存放區包含預先建構的 Docker 映像檔，該映像檔使用 samtools 為您在 --input 旗標中指定的 BAM 檔案建立索引。

指令會在 dsub 管道執行完畢後才會完成，這可能因 Batch 工作排程而異。通常需要約 10 分鐘：Batch 通常會在幾分鐘內開始執行工作，而工作執行時間約為 8 分鐘。

一開始，指令仍在執行，輸出內容類似如下：

Job properties:
  job-id: JOB_NAME
  job-name: samtools
  user-id: USERNAME
Provider internal-id (operation): projects/PROJECT_ID/locations/us-central1/jobs/JOB_NAME
Launched job-id: JOB_NAME
To check the status, run:
  dstat --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME' --status '*'
To cancel the job, run:
  ddel --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME'
Waiting for job to complete...
Waiting for: JOB_NAME.

然後，作業成功完成後，指令會結束，輸出內容類似如下：

  JOB_NAME: SUCCESS
JOB_NAME

這項輸出內容包含下列值：

JOB_NAME：作業名稱。
USERNAME：您的 Google Cloud 使用者名稱。
PROJECT_ID：您的 Google Cloud 專案的專案 ID。

查看輸出檔案

如要使用 gcloud CLI 查看範例 dsub 管道建立的輸出檔案，請執行 gcloud storage ls 指令：

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

更改下列內容：

BUCKET_NAME：您建立的 Cloud Storage bucket 名稱。
WORK_DIRECTORY：您在 dsub 指令中指定的目錄。
PROJECT_ID：您的 Google Cloud 專案的專案 ID。

輸出結果會與下列內容相似：

gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/

這項輸出內容包括 BAI 檔案，以及含有工作記錄的目錄。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免付費，最簡單的方法就是刪除目前的專案。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

刪除個別資源

如要繼續使用目前的專案，請刪除本教學課程中使用的個別資源。

刪除值區

管道執行完畢後，會在 Cloud Storage 值區的 WORK_DIRECTORY 目錄中建立並儲存輸出檔案。

如要減少目前Google Cloud 帳戶的 Cloud Storage 費用，請採取下列任一做法：

如果您不再需要本教學課程中使用的值區，請使用帶有 --recursive 標記的 gcloud storage rm 指令，刪除值區及其中的所有內容：
```
gcloud storage rm gs://BUCKET_NAME \
    --recursive \
    --project PROJECT_ID
```
更改下列內容：
- BUCKET_NAME：您建立的 Cloud Storage bucket 名稱。
- PROJECT_ID：您的 Google Cloud 專案的專案 ID。
否則，如果仍需要該值區，請使用帶有 --recursive 標記的 gcloud storage rm 指令，只刪除 WORK_DIRECTORY 目錄及其所有內容：
```
gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
    --recursive \
    --project PROJECT_ID
```
更改下列內容：
- BUCKET_NAME：您建立的 Cloud Storage bucket 名稱。
- WORK_DIRECTORY：您在 dsub 指令中指定的目錄。
- PROJECT_ID：您的 Google Cloud 專案的專案 ID。

刪除工作

如要使用 gcloud CLI 刪除工作，請執行 gcloud batch jobs delete 指令。

gcloud batch jobs delete JOB_NAME \
    --location us-central1 \
    --project PROJECT_ID

更改下列內容：

JOB_NAME：作業名稱。
PROJECT_ID：您的 Google Cloud 專案的專案 ID。

後續步驟

進一步瞭解 dsub 和 dsub for Batch。
進一步瞭解如何搭配 Batch 使用儲存空間磁碟區。

在 Batch 上執行 dsub 管道，藉此自動化調度工作 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

建立 Cloud Storage 值區

執行 dsub 管道

查看輸出檔案

清除所用資源

刪除專案

刪除個別資源

刪除值區

刪除工作

後續步驟

在 Batch 上執行 dsub 管道，藉此自動化調度工作

執行 `dsub` 管道