Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Batch berjalan di HealthOmics
AWS HealthOmics batch run memungkinkan Anda mengirimkan beberapa proses dalam satu permintaan API. Setiap run dalam batch berbagi konfigurasi dasar yang sama tetapi dapat memiliki input yang berbeda dan parameter run-specific. Batch run mengurangi overhead pengiriman dan menyederhanakan manajemen siklus hidup untuk pemrosesan alur kerja skala besar.
Dengan batch run, Anda dapat:
+ Kirim hingga 100.000 proses dalam satu **StartRunBatch** panggilan, dengan konfigurasi bersama ditentukan sekali dan diterapkan di semua proses.
+ Terapkan penggantian parameter per-run untuk sampel individual, termasuk nama, URI keluaran, parameter, prioritas, dan tag.
+ Lacak status batch secara keseluruhan dan progres pengiriman lari individu melalui **GetBatch** dan**ListRunsInBatch**.
+ Batalkan semua proses dalam batch menggunakan**CancelRunBatch**.
+ Hapus semua proses dalam batch menggunakan**DeleteRunBatch**.
+ Hapus metadata batch dengan. **DeleteBatch**
**Topics**
+ [Konsep batch run](#batch-concepts)
+ [Prasyarat](#batch-prerequisites)
+ [Izin IAM untuk operasi batch](#batch-iam-permissions)
+ [Memulai: Kirim batch pertama Anda](#batch-getting-started)
+ [Memulai batch run](#batch-starting)
+ [Memantau kemajuan batch](#batch-monitoring)
+ [Penanganan gagal berjalan](#batch-handling-failures)
+ [Membatalkan batch](#batch-canceling)
+ [Menghapus batch berjalan](#batch-deleting-runs)
+ [Menghapus metadata batch](#batch-deleting-metadata)
+ [EventBridge acara untuk batch](#batch-eventbridge)
+ [Pertimbangan dan batasan](#batch-limitations)
## Konsep batch run
+ **Batch — Kumpulan** alur kerja berjalan yang berbagi konfigurasi umum, dikelola sebagai sumber daya tunggal dengan Nama Sumber Daya Amazon (ARN) dan status siklus hidupnya sendiri.
+ **Pengaturan jalankan default** (`defaultRunSetting`) — Parameter alur kerja yang dibagikan di semua proses dalam batch, seperti ID alur kerja, peran IAM, URI keluaran, dan parameter umum.
+ **Pengaturan khusus lari** (`inlineSettings`atau`s3UriSettings`) — Konfigurasi per lari yang menimpa atau bergabung dengan pengaturan run default. Setiap entri harus menyertakan yang unik`runSettingId`.
+ **Jalankan pengaturan ID** (`runSettingId`) - Pengidentifikasi unik yang diperlukan dan disediakan pelanggan untuk setiap konfigurasi run dalam satu batch. Setelah pengiriman, gunakan **ListRunsInBatch** untuk memetakan masing-masing `runSettingId` ke HealthOmics -generated`runId`, memungkinkan Anda untuk melacak run mana yang dibuat dari konfigurasi input mana.
+ **Status Batch** - Keadaan keseluruhan operasi batch. Kemungkinan nilai:
+ `CREATING`- Batch sedang dibuat.
+ `PENDING`— Batch telah dibuat; konfigurasi run sedang divalidasi secara asinkron.
+ `SUBMITTING`— Validasi selesai; proses individu sedang dikirimkan.
+ `INPROGRESS`— Semua pengiriman run telah dicoba; run sedang dijalankan.
+ `STOPPING`— Permintaan pembatalan telah diterima; proses sedang dihentikan.
+ `CANCELLED`Batch dibatalkan.
+ `PROCESSED`— Semua proses telah mencapai status terminal (selesai, gagal, atau dibatalkan).
+ `FAILED`- Batch itu sendiri gagal sebelum proses dapat dibuat. Lihat [Kegagalan tingkat batch](#batch-level-failures) untuk detail.
+ `RUNS_DELETING`— Berjalan dalam batch sedang dihapus.
+ `RUNS_DELETED`— Semua proses dalam batch telah dihapus.
+ **Status pengiriman** — Hasil pengiriman untuk individu yang dijalankan dalam batch. Kemungkinan nilai:
+ `SUCCESS`— Jalankan berhasil dikirimkan.
+ `FAILED`— Jalankan pengiriman gagal (misalnya, karena kesalahan validasi).
+ `CANCEL_SUCCESS`— Run berhasil dibatalkan.
+ `CANCEL_FAILED`— Jalankan pembatalan gagal.
+ `DELETE_SUCCESS`— Jalankan berhasil dihapus.
+ `DELETE_FAILED`— Jalankan penghapusan gagal.
## Prasyarat
Sebelum memulai batch run, pastikan Anda memiliki:
+ Alur kerja HealthOmics pribadi yang aktif. Batch run tidak didukung dengan alur kerja Ready2Run.
+ Peran layanan IAM dengan izin untuk menjalankan HealthOmics alur kerja dan mengakses bucket Amazon S3 Anda. Lihat perinciannya di [Peran layanan untuk AWS HealthOmics](permissions-service.md).
+ Lokasi Amazon S3 untuk data input dan hasil output.
+ Parameter khusus lari untuk setiap sampel atau konfigurasi eksperimental.
## Izin IAM untuk operasi batch
Identitas IAM Anda harus memiliki izin untuk operasi batch dan operasi lari individual yang mendasarinya. Contoh kebijakan berikut memberikan izin untuk semua operasi batch:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowBatchOperations",
"Effect": "Allow",
"Action": [
"omics:StartRunBatch",
"omics:GetBatch",
"omics:ListBatch",
"omics:ListRunsInBatch",
"omics:CancelRunBatch",
"omics:DeleteRunBatch",
"omics:DeleteBatch"
],
"Resource": "arn:aws:omics:*:123456789012:runBatch/*"
},
{
"Sid": "AllowRunCreation",
"Effect": "Allow",
"Action": "omics:StartRun",
"Resource": [
"arn:aws:omics:*:123456789012:run/*",
"arn:aws:omics:*:123456789012:workflow/*",
"arn:aws:omics:*:123456789012:runGroup/*"
]
},
{
"Sid": "AllowListOperations",
"Effect": "Allow",
"Action": [
"omics:ListBatch",
"omics:ListRunsInBatch"
],
"Resource": "*"
},
{
"Sid": "AllowPassRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::123456789012:role/OmicsRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "omics.amazonaws.com"
}
}
}
]
}
```
**catatan**
**StartRunBatch**memerlukan otorisasi ganda: `omics:StartRunBatch` pada sumber daya batch dan `omics:StartRun` saat menjalankan, alur kerja, dan menjalankan sumber daya grup. Kedua izin harus diberikan agar batch berhasil.
Peran layanan IAM yang diteruskan `roleArn` (digunakan oleh HealthOmics untuk menjalankan proses) memerlukan izin yang sama seperti untuk panggilan individual**StartRun**. Lihat perinciannya di [Peran layanan untuk AWS HealthOmics](permissions-service.md).
### Tagging dan kontrol akses berbasis tag
Batch menjalankan tag dukungan pada dua tingkat:
+ **Batch tag** (tag pada **StartRunBatch** permintaan) - Diterapkan ke sumber daya batch. Kontrol akses berbasis tag (TBAC) sepenuhnya diberlakukan untuk tag batch.
+ **Run tags** (`runTags`in `defaultRunSetting` dan per-run`runTags`) - Diterapkan ke sumber daya run individual. Tag ini digabungkan menggunakan aturan prioritas yang sama dengan parameter.
Jika Anda menggunakan kebijakan kontrol akses berbasis tag, pastikan kebijakan IAM Anda disertakan `omics:TagResource` dengan ketentuan `aws:RequestTag` dan `aws:TagKeys` ketentuan yang sesuai.
**Contoh: Batasi pembuatan batch ke lingkungan non-produksi**
Kebijakan berikut memungkinkan pengguna untuk membuat batch dan menjalankan, tetapi menolak menandai sumber daya apa pun dengan: `environment=production`
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowBatchAndRunCreation",
"Effect": "Allow",
"Action": [
"omics:StartRunBatch",
"omics:StartRun"
],
"Resource": "*"
},
{
"Sid": "AllowTaggingNonProd",
"Effect": "Allow",
"Action": "omics:TagResource",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestTag/environment": ["dev", "test"]
}
}
},
{
"Sid": "DenyProductionTags",
"Effect": "Deny",
"Action": "omics:TagResource",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestTag/environment": "production"
}
}
}
]
}
```
Dengan kebijakan ini:
+ `tags: {"environment": "dev"}`pada batch → Diizinkan
+ `tags: {"environment": "production"}`pada batch → Ditolak (403)
+ `runTags: {"environment": "production"}`di `defaultRunSetting` → Ditolak untuk proses individu selama pembuatan asinkron
## Memulai: Kirim batch pertama Anda
Contoh berikut berjalan melalui pengiriman batch kecil dari dua run, memeriksa kemajuan, dan meninjau hasil.
**Langkah 1: Kirim batch**
```
aws omics start-run-batch \
--batch-name "my-first-batch" \
--default-run-setting '{
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"storageType": "DYNAMIC",
"parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
}' \
--batch-run-settings '{
"inlineSettings": [
{
"runSettingId": "sample-A",
"parameters": {"inputUri": "s3://my-bucket/sampleA.fastq"}
},
{
"runSettingId": "sample-B",
"parameters": {"inputUri": "s3://my-bucket/sampleB.fastq"}
}
]
}'
```
Respons mengembalikan ID batch yang Anda gunakan untuk semua operasi berikutnya:
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"status": "CREATING"
}
```
**Langkah 2: Periksa kemajuan batch**
```
aws omics get-batch --batch-id 7123456
```
Perhatikan kemajuan `status` lapangan dari `CREATING` → `PENDING` → `SUBMITTING` → `INPROGRESS` →`PROCESSED`. Ini `submissionSummary` menunjukkan berapa banyak proses yang berhasil dikirimkan, dan `runSummary` menunjukkan kemajuan eksekusi.
**Langkah 3: Tinjau proses individu**
```
aws omics list-runs-in-batch --batch-id 7123456
```
Setiap entri memetakan Anda `runSettingId` (misalnya,`sample-A`) ke HealthOmics -generated`runId`, sehingga Anda dapat melacak hasil kembali ke sampel input Anda.
**Langkah 4: Periksa pengiriman yang gagal**
```
aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED
```
Jika ada proses yang gagal dikirimkan, tanggapannya termasuk `submissionFailureReason` dan `submissionFailureMessage` untuk membantu Anda mendiagnosis masalah.
## Memulai batch run
Gunakan **StartRunBatch** untuk mengirimkan beberapa proses dengan satu permintaan. Permintaan tersebut meliputi:
+ `defaultRunSetting`— Konfigurasi bersama untuk semua berjalan dalam batch.
+ `batchRunSettings`— Konfigurasi lari individu, disediakan sebagai salah satu dari:
+ `inlineSettings`— Sebuah array hingga 100 konfigurasi run-specific yang disediakan langsung di badan permintaan.
+ `s3UriSettings`— URI Amazon S3 yang menunjuk ke file JSON yang berisi konfigurasi run. Diperlukan untuk batch dengan lebih dari 100 run, dan mendukung hingga 100.000 run.
Anda juga dapat memberikan bidang-bidang berikut:
+ `batchName`— Nama opsional yang dapat dibaca manusia untuk batch.
+ `requestId`— Token idempotensi untuk mencegah pengiriman batch duplikat.
+ `tags`— Tag untuk dikaitkan dengan sumber daya batch itu sendiri.
### Kirim batch kecil dengan konfigurasi run inline
Menyediakan array konfigurasi run-specific langsung di badan permintaan menggunakan. `inlineSettings` Setiap entri harus menyertakan unik `runSettingId` (wajib). `runSettingId`Ini adalah kunci Anda untuk mengkorelasikan hasil — ketika Anda menelepon**ListRunsInBatch**, setiap entri memetakan Anda `runSettingId` ke HealthOmics -generated `runId` dan. `runArn`
Anda dapat menyertakan hingga 100 entri dengan konfigurasi sebaris.
```
{
"batchName": "genomics-cohort-analysis",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"tags": {
"project": "genomics-study",
"environment": "production"
},
"defaultRunSetting": {
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"parameters": {
"referenceUri": "s3://my-bucket/reference/genome.fasta"
},
"runTags": {
"analysis-type": "germline"
}
},
"batchRunSettings": {
"inlineSettings": [
{
"runSettingId": "sample-001",
"name": "Sample-001-Analysis",
"parameters": {
"inputUri": "s3://my-bucket/input/sample-001.fastq",
"sampleName": "sample-001"
},
"runTags": {
"patient-id": "patient001"
}
},
{
"runSettingId": "sample-002",
"name": "Sample-002-Analysis",
"outputUri": "s3://my-bucket/output/special/",
"parameters": {
"inputUri": "s3://my-bucket/input/sample-002.fastq",
"sampleName": "sample-002"
},
"runTags": {
"patient-id": "patient002"
}
}
]
}
}
```
**CLI**
```
aws omics start-run-batch \
--batch-name "genomics-cohort-analysis" \
--request-id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
--default-run-setting '{
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"storageType": "DYNAMIC",
"parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
}' \
--batch-run-settings '{
"inlineSettings": [
{
"runSettingId": "sample-001",
"name": "Run-001",
"parameters": {"inputUri": "s3://my-bucket/input1.fastq"}
},
{
"runSettingId": "sample-002",
"name": "Run-002",
"parameters": {"inputUri": "s3://my-bucket/input2.fastq"}
}
]
}'
```
### Kirim batch besar dengan konfigurasi run di S3
Untuk batch dengan lebih dari 100 run, simpan konfigurasi run Anda dalam file JSON di Amazon S3 dan sediakan URI yang digunakan. `s3UriSettings` File JSON harus berisi array objek pengaturan run-specific, masing-masing dengan unik. `runSettingId` File dapat berisi hingga 100.000 entri.
Format file S3 sama dengan `inlineSettings` array:
```
[
{
"runSettingId": "sample-001",
"name": "Sample-001-Analysis",
"parameters": {
"inputUri": "s3://my-bucket/input/sample-001.fastq",
"sampleName": "sample-001"
}
},
{
"runSettingId": "sample-002",
"name": "Sample-002-Analysis",
"parameters": {
"inputUri": "s3://my-bucket/input/sample-002.fastq",
"sampleName": "sample-002"
}
}
]
```
**Permintaan API**
```
{
"defaultRunSetting": {
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"parameters": {
"referenceUri": "s3://my-bucket/reference/genome.fasta"
}
},
"batchRunSettings": {
"s3UriSettings": "s3://my-bucket/configs/run-configs.json"
}
}
```
**CLI**
```
aws omics start-run-batch \
--default-run-setting '{
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
}' \
--batch-run-settings '{"s3UriSettings": "s3://my-bucket/configs/run-configs.json"}'
```
**penting**
Peran layanan IAM yang ditentukan `roleArn` harus memiliki akses baca ke objek Amazon S3 yang ditentukan dalam. `s3UriSettings` HealthOmics memvalidasi akses ke file Amazon S3 selama panggilan API sinkron dan merekam file. ETag Jika file dimodifikasi setelah pengiriman, batch gagal selama pemrosesan asinkron.
### Respons
Permintaan yang berhasil mengembalikan ID batch dan status awal:
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"status": "CREATING",
"uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
"tags": {
"project": "genomics-study",
"environment": "production"
}
}
```
Jika validasi sinkron gagal (misalnya, ID alur kerja yang tidak valid atau URI Amazon S3 yang tidak dapat diakses), API akan menampilkan kesalahan sebelum proses apa pun dikirimkan.
### Referensi parameter
Tabel berikut menunjukkan **StartRun** bidang mana yang dapat diatur per run dan yang berlaku hanya pada tingkat batch. Untuk deskripsi bidang lengkap, lihat referensi **StartRun** API.
| Bidang | Tingkat batch () `defaultRunSetting` | Per-run dapat dikonfigurasi () `inlineSettings` |
| --- | --- | --- |
| workflowId | Ya | Tidak |
| workflowType | Ya | Tidak |
| workflowVersionName | Ya | Tidak |
| workflowOwnerId | Ya | Tidak |
| roleArn | Ya | Tidak |
| storageCapacity | Ya | Tidak |
| storageType | Ya | Tidak |
| runGroupId | Ya | Tidak |
| logLevel | Ya | Tidak |
| cacheBehavior | Ya | Tidak |
| cacheId | Ya | Tidak |
| retentionMode | Ya | Tidak |
| name | Ya | Ya |
| outputUri | Ya | Ya |
| parameters | Ya | Ya (digabung) |
| priority | Ya | Ya |
| runTags | Ya | Ya (digabung) |
| outputBucketOwnerId | Ya | Ya |
**catatan**
Bidang `runId` (untuk dijalankan ulang individu) tidak didukung sebagai masukan ke**StartRunBatch**. Setiap pengiriman batch selalu membuat proses baru, dan setiap run akan menerima. `runId` Lihat [Jalankan kembali lari HealthOmics](rerun-a-run.md) untuk mencoba kembali lari individu.
### Penggabungan parameter
Parameter dari `defaultRunSetting` digabungkan dengan parameter run-specific yang disediakan di `inlineSettings` atau melalui URI S3. Nilai khusus lari diutamakan saat kunci tumpang tindih.
**Contoh:**
| Sumber | Parameter |
| --- | --- |
| defaultRunSetting | \$1"referenceUri": "s3://bucket/ref.fasta", "version": "v1"\$1 |
| inlineSettingsentri | \$1"inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
| Hasil gabungan | \$1"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
Perilaku penggabungan yang sama berlaku untuk`runTags`. Tag yang ditentukan dalam konfigurasi per-run mengganti tag dengan kunci yang sama dari`defaultRunSetting.runTags`, dan kunci baru ditambahkan.
**Contoh penggabungan tag:**
| Sumber | Tag |
| --- | --- |
| defaultRunSetting.runTags | \$1"project": "cancer-research", "pipeline-version": "v2.1"\$1 |
| inlineSettings[].runTags | \$1"patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
| Hasil gabungan (diterapkan untuk menjalankan) | \$1"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
**catatan**
Tag tingkat batch (atas **StartRunBatch** permintaan) hanya diterapkan ke sumber daya batch itu sendiri. Mereka tidak diwarisi oleh lari individu. Tag Run-level dikontrol melalui `defaultRunSetting.runTags` dan per-run. `runTags`
### Pengajuan bertahap
**StartRunBatch**memvalidasi bidang umum secara sinkron dan segera kembali dengan ID batch dan status. `CREATING` Berjalan dalam batch dikirimkan secara bertahap dan asinkron pada tingkat yang terkontrol sesuai dengan kuota throughput Anda.
Untuk daftar lengkap HealthOmics kuota, lihat[HealthOmics kuota layanan](service-quotas.md).
Transisi batch melalui status berikut selama pemrosesan normal:
1. `CREATING`- Batch sedang dibuat.
1. `PENDING`— Batch dibuat, menjalankan konfigurasi yang divalidasi.
1. `SUBMITTING`— Validasi selesai, proses individu sedang dikirimkan.
1. `INPROGRESS`— Semua pengiriman run dicoba, run dijalankan.
1. `PROCESSED`— Semua proses telah mencapai status terminal.
**penting**
Batch run submission berbagi kuota **StartRun** throughput yang sama dengan panggilan API langsung**StartRun**. Jika Anda menelepon **StartRun** langsung saat batch besar sedang diproses, baik pengiriman batch dan panggilan langsung Anda bersaing untuk kapasitas yang sama. Hal ini dapat menyebabkan batch run gagal dengan `ThrottlingException` (tingkat terlampaui) atau **StartRun** panggilan langsung Anda terhambat. Hal yang sama berlaku untuk **CancelRun** dan **DeleteRun** — kuota throughput berbagi dengan **CancelRunBatch** dan **DeleteRunBatch** masing-masing.
## Memantau kemajuan batch
### Dapatkan status batch
Gunakan **GetBatch** untuk mengambil status keseluruhan dan kemajuan pengiriman untuk batch.
```
aws omics get-batch --batch-id 7123456
```
Respons meliputi:
+ `status`— Status batch keseluruhan.
+ `submissionSummary`— Hitungan pengiriman yang berhasil dan gagal untuk memulai, membatalkan, dan menghapus operasi.
+ `runSummary`— Hitungan run di setiap status eksekusi. Nilai yang mungkin: `PENDING``STARTING`,`RUNNING`,`STOPPING`,`COMPLETED`,`DELETED`,`CANCELLED`, atau `FAILED`
+ Stempel waktu untuk peristiwa siklus hidup —`creationTime`,,,. `submittedTime` `processedTime` `failedTime`
**Contoh respon:**
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
"name": "genomics-cohort-analysis",
"status": "INPROGRESS",
"totalRuns": 96,
"defaultRunSetting": {
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/"
},
"submissionSummary": {
"successfulStartSubmissionCount": 94,
"failedStartSubmissionCount": 2,
"pendingStartSubmissionCount": 0
},
"runSummary": {
"pendingRunCount": 10,
"startingRunCount": 5,
"runningRunCount": 50,
"stoppingRunCount": 0,
"completedRunCount": 29,
"failedRunCount": 0,
"cancelledRunCount": 0,
"deletedRunCount": 0
},
"creationTime": "2025-03-15T10:00:00Z",
"submittedTime": "2025-03-15T10:05:00Z",
"tags": {
"project": "genomics-study"
}
}
```
**catatan**
Ringkasan eksekusi jalankan pada akhirnya konsisten dan mungkin tertinggal dari status run yang sebenarnya. Hitungan akhir direkonsiliasi ketika batch mencapai status. `PROCESSED`
### Daftar berjalan dalam batch
Gunakan **ListRunsInBatch** untuk mengambil informasi rinci untuk menjalankan individu dalam batch. Hasilnya diberi paginasi.
```
aws omics list-runs-in-batch --batch-id 7123456
```
Anda dapat memfilter hasil menggunakan salah satu parameter kueri berikut. Hanya satu filter per panggilan yang didukung.
| Filter | Deskripsi |
| --- | --- |
| submissionStatus | Filter berdasarkan status pengiriman:SUCCESS,,FAILED,CANCEL\$1SUCCESS, CANCEL\$1FAILEDDELETE\$1SUCCESS, atauDELETE\$1FAILED. |
| runSettingId | Ambil run untuk ID pengaturan run tertentu. |
| runId | Ambil run untuk ID run tertentu. |
**Contoh: Daftar kiriman gagal**
```
aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED
```
Setiap hasil meliputi:
+ `runSettingId`— Pengidentifikasi yang disediakan pelanggan untuk konfigurasi run.
+ `runId`— HealthOmics Pengidentifikasi run yang dihasilkan (kosong jika pengiriman gagal).
+ `runArn`— ARN penuh lari.
+ `submissionStatus`— Hasil pengajuan (`SUCCESS`,,`FAILED`,`CANCEL_SUCCESS`, `CANCEL_FAILED``DELETE_SUCCESS`, atau`DELETE_FAILED`).
+ `submissionFailureReason`dan `submissionFailureMessage` — Detail jika pengiriman gagal.
**catatan**
`runSettingId`adalah pengidentifikasi yang ditentukan pelanggan yang Anda berikan dalam konfigurasi run. `runId`adalah pengidentifikasi HealthOmics -generated yang ditetapkan setelah pengiriman berhasil. Jika pengiriman gagal, `runId` kosong.
### Daftar batch
Gunakan **ListBatch** untuk mengambil semua sumber daya batch di akun Anda. Hasilnya diberi paginasi.
```
aws omics list-batch
```
Anda dapat memfilter hasil menggunakan parameter kueri berikut:
| Filter | Deskripsi |
| --- | --- |
| status | Filter berdasarkan status batch. |
| name | Filter berdasarkan nama batch. |
| runGroupId | Filter berdasarkan menjalankan ID grup. |
## Penanganan gagal berjalan
Ada dua jenis kegagalan yang berbeda dalam pemrosesan batch. Memahami perbedaan sangat penting untuk pemecahan masalah.
### Kegagalan tingkat batch
Kegagalan tingkat batch berarti batch itu sendiri gagal — tidak ada proses yang dibuat (atau hanya beberapa yang dibuat sebelum kegagalan). Status batch adalah`FAILED`.
Panggil **GetBatch** dan periksa `failureReason` bidangnya. Alasan kegagalan umum meliputi:
| Kategori kegagalan | Contoh `failureReason` pesan | Tindakan |
| --- | --- | --- |
| Kesalahan validasi | “Batch memiliki 100001 run tetapi 100000 run adalah maks. “, “Diharapkan 50 unik runSettingIds tetapi ada 49", “Format JSON tidak valid dalam konfigurasi run” | Perbaiki konfigurasi dan kirimkan batch baru. Kesalahan ini tidak dapat dicoba kembali. |
| Konfigurasi S3 berubah | “Diharapkan s3 UriConfigs etag:\$1" abc123\$1” tetapi:\$1 "def456\$1”. s3 telah berubah sejak memanggil” UriConfigs StartRunBatch | Jangan memodifikasi file S3 setelah pengiriman. Kirim ulang dengan file saat ini. |
| Kesalahan layanan sementara | “Ada kesalahan sementara dalam layanan. Coba lagi batch.” | Coba lagi dengan mengirimkan batch yang sama lagi. Gunakan hal yang sama requestId untuk idempotensi. |
**Contoh: Batch gagal karena validasi**
```
aws omics get-batch --batch-id 7123456
```
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"status": "FAILED",
"failureReason": "Batch has 100001 runs but 100000 runs is the max.",
"failedTime": "2025-03-15T10:01:00Z"
}
```
### Kegagalan tingkat lari
Kegagalan run-level berarti batch itu sendiri berhasil (statusnya adalah `INPROGRESS` atau`PROCESSED`), tetapi proses individu gagal dikirimkan. Batch terus memproses proses lainnya — tidak berhenti pada kegagalan pertama.
**1. Periksa ringkasan pengiriman**
```
aws omics get-batch --batch-id 7123456
```
Lihat`submissionSummary.failedStartSubmissionCount`. Jika ini lebih besar dari nol, beberapa proses gagal selama pengiriman.
**2. Daftar kiriman gagal**
```
aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED
```
Setiap entri yang gagal meliputi:
+ `runSettingId`— Konfigurasi yang menjalankan gagal.
+ `submissionFailureReason`— Kategori kesalahan.
+ `submissionFailureMessage`— Pesan kesalahan terperinci.
**3. Alasan kegagalan pengiriman**
Tabel berikut mencantumkan nilai yang mungkin untuk `submissionFailureReason` setiap proses:
| `submissionFailureReason` | Arti | Dicoba ulang? |
| --- | --- | --- |
| ValidationException | Parameter run tidak valid — misalnya, parameter tidak cocok dengan definisi alur kerja, format URI S3 tidak valid, atau pelanggaran kendala. | Tidak - perbaiki konfigurasi. |
| AccessDeniedException | Peran layanan IAM tidak memiliki izin untuk mengakses sumber daya yang diperlukan (input S3, kunci KMS, Log, gambar ECR). CloudWatch | Tidak - perbarui kebijakan peran. |
| ResourceNotFoundException | Sumber daya yang direferensikan (alur kerja, jalankan grup, atau jalankan cache) tidak ada atau tidak dalam keadaan aktif. | Tidak - verifikasi sumber daya IDs. |
| ServiceQuotaExceededException | Akun telah mencapai jumlah maksimum proses aktif atau kuota layanan lain. | Tunggu hingga proses selesai, atau minta kenaikan kuota. |
| ConflictException | Operasi yang saling bertentangan sedang berlangsung — misalnya, upaya pembuatan duplikat run. | Biasanya menyelesaikan dengan sendirinya. |
| ThrottlingException | Permintaan dibatasi karena batas tarif API. | Layanan mencoba ulang secara otomatis. Jika berlanjut setelah mencoba ulang, kurangi pengiriman batch bersamaan. |
| RequestTimeoutException | Permintaan habis waktu selama pemrosesan. | Layanan mencoba ulang secara otomatis. Jika terus berlanjut, periksa masalah hilir. |
| InternalServerException | Terjadi kesalahan layanan tak terduga. | Layanan mencoba ulang secara otomatis. Jika terus berlanjut setelah mencoba lagi, hubungi Support AWS . |
**catatan**
HealthOmics secara otomatis mencoba ulang kesalahan sementara (`ThrottlingException`,`RequestTimeoutException`,`InternalServerException`) untuk setiap proses. Lari ditandai sebagai `FAILED` hanya setelah semua upaya coba lagi habis. Kesalahan yang tidak dapat dicoba ulang (`ValidationException`,`AccessDeniedException`,`ResourceNotFoundException`) segera gagal tanpa mencoba lagi.
**4. Kirim ulang gagal berjalan**
Buat batch baru yang hanya berisi konfigurasi run yang dikoreksi. Gunakan yang sama `defaultRunSetting` dan sertakan hanya `runSettingId` entri yang gagal. Tidak ada mekanisme coba ulang bawaan untuk proses yang gagal - Anda harus mengirimkan batch baru.
## Membatalkan batch
Gunakan **CancelRunBatch** untuk membatalkan batch yang sedang berlangsung. Operasi pembatalan:
+ Mencegah not-yet-submitted dan menunggu proses mulai
+ Mengirimkan **CancelRun** permintaan untuk proses yang sudah dimulai.
```
aws omics cancel-run-batch --batch-id 7123456
```
**penting**
Pembatalan hanya diperbolehkan pada batch di`PENDING`,`SUBMITTING`, atau `INPROGRESS` negara bagian.
Hanya satu operasi pembatalan atau hapus per batch yang diizinkan pada satu waktu.
Operasi pembatalan bersifat non-atom dan mungkin sebagian berhasil. Gunakan **GetBatch** untuk meninjau `successfulCancelSubmissionCount` dan `failedCancelSubmissionCount` di`submissionSummary`.
## Menghapus batch berjalan
Gunakan **DeleteRunBatch** untuk menghapus individu berjalan dalam batch.
```
aws omics delete-run-batch --batch-id 7123456
```
**penting**
Hapus hanya diperbolehkan pada batch di `PROCESSED` atau `CANCELLED` negara bagian.
Hanya satu operasi pembatalan atau hapus per batch yang diizinkan pada satu waktu.
Operasi penghapusan non-atomik dan mungkin sebagian berhasil. Gunakan **GetBatch** untuk meninjau `successfulDeleteSubmissionCount` dan `failedDeleteSubmissionCount` di`submissionSummary`.
## Menghapus metadata batch
Gunakan **DeleteBatch** untuk menghapus sumber daya batch dan metadata terkait. Ini adalah operasi terpisah dari**DeleteRunBatch**.
```
aws omics delete-batch --batch-id 7123456
```
**penting**
**DeleteBatch**mengharuskan batch berada dalam status terminal (`PROCESSED`,`FAILED`,`CANCELLED`, atau`RUNS_DELETED`).
**DeleteBatch**tidak menghapus proses individu. Gunakan **DeleteRunBatch** dulu jika Anda ingin menghapus run juga.
Setelah **DeleteBatch** selesai, metadata batch tidak lagi dapat diakses. Anda tidak dapat menelepon **GetBatch****ListRunsInBatch**,**DeleteRunBatch**,, atau **CancelRunBatch** pada batch yang dihapus.
## EventBridge acara untuk batch
HealthOmics mengirimkan peristiwa ke Amazon EventBridge setiap kali batch mengubah status. Anda dapat menggunakan peristiwa ini untuk mengotomatiskan alur kerja—misalnya, untuk memicu pemberitahuan saat batch selesai atau gagal, atau untuk memulai pipeline hilir saat semua proses selesai.
Batch event menggunakan bus acara dan sumber yang sama dengan HealthOmics event lainnya. Untuk petunjuk penyiapan umum, lihat[Menggunakan EventBridge dengan AWS HealthOmics](eventbridge.md).
### Jenis detail acara
| Nama peristiwa | Dipancarkan saat |
| --- | --- |
| RunBatch Perubahan Status | Batch transisi ke status baru (CREATING,,PENDING,SUBMITTING, INPROGRESSSTOPPING,CANCELLED,PROCESSED, FAILEDRUNS\$1DELETING,RUNS\$1DELETED) |
### Bidang detail acara
`detail`Objek dalam acara batch mencakup bidang-bidang berikut:
| Bidang | Tipe | Deskripsi |
| --- | --- | --- |
| omicsVersion | String | Versi skema acara (saat ini 1.0.0). |
| arn | String | Batch ARN. |
| batchId | String | Pengenal batch. |
| status | String | Status batch baru. |
| uuid | String | Batch UUID. |
| batchName | String | Nama batch (jika disediakan). |
| totalRuns | String | Jumlah total run dalam batch. |
| failureReason | String | Alasan kegagalan (hadir hanya ketika status adalahFAILED). |
| failureMessage | String | Pesan kegagalan terperinci (hadir hanya ketika statusFAILED). |
| successfulStartSubmissionCount | String | Jumlah run yang berhasil dikirimkan. |
| failedStartSubmissionCount | String | Jumlah run yang gagal dikirimkan. |
| pendingStartSubmissionCount | String | Jumlah run masih tertunda pengiriman. |
| pendingRunCount | String | Jumlah run dalam status tertunda. |
| startingRunCount | String | Jumlah lari yang dimulai. |
| runningRunCount | String | Jumlah run yang sedang berjalan. |
| stoppingRunCount | String | Jumlah lari yang dihentikan. |
| completedRunCount | String | Jumlah run yang selesai. |
| failedRunCount | String | Jumlah run yang gagal. |
| cancelledRunCount | String | Jumlah proses yang dibatalkan. |
| deletedRunCount | String | Jumlah proses yang dihapus. |
| workflowId | String | Pengidentifikasi alur kerja. |
| workflowArn | String | Alur kerja ARN. |
| workflowVersionArn | String | Alur kerja versi ARN (jika ada). |
| workflowOwnerId | String | ID akun pemilik alur kerja (untuk alur kerja bersama). |
| runCache | String | Jalankan cache ARN (jika ada). |
| runCacheBehavior | String | Perilaku run cache (jika ada). |
### Contoh acara
**Contoh: Acara Batch selesai**
```
{
"version": "0",
"id": "a1b2c3d4-5678-90ab-cdef-example11111",
"detail-type": "RunBatch Status Change",
"source": "aws.omics",
"account": "123456789012",
"time": "2025-03-15T12:30:00Z",
"region": "us-west-2",
"resources": [
"arn:aws:omics:us-west-2:123456789012:runBatch/7123456"
],
"detail": {
"omicsVersion": "1.0.0",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"batchId": "7123456",
"status": "PROCESSED",
"uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
"batchName": "genomics-cohort-analysis",
"totalRuns": "96",
"successfulStartSubmissionCount": "94",
"failedStartSubmissionCount": "2",
"pendingStartSubmissionCount": "0",
"completedRunCount": "90",
"failedRunCount": "4",
"cancelledRunCount": "0",
"workflowId": "1234567"
}
}
```
**Contoh: Acara gagal Batch**
```
{
"version": "0",
"id": "a1b2c3d4-5678-90ab-cdef-example22222",
"detail-type": "RunBatch Status Change",
"source": "aws.omics",
"account": "123456789012",
"time": "2025-03-15T10:01:00Z",
"region": "us-west-2",
"resources": [
"arn:aws:omics:us-west-2:123456789012:runBatch/7123456"
],
"detail": {
"omicsVersion": "1.0.0",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"batchId": "7123456",
"status": "FAILED",
"failureReason": "VALIDATION_EXCEPTION",
"failureMessage": "Expected 100 unique runSettingIds but there were 99"
}
}
```
**Contoh: EventBridge aturan untuk penyelesaian batch**
Pola peristiwa berikut cocok ketika batch apa pun mencapai status terminal:
```
{
"source": ["aws.omics"],
"detail-type": ["RunBatch Status Change"],
"detail": {
"status": ["PROCESSED", "FAILED", "CANCELLED"]
}
}
```
## Pertimbangan dan batasan
+ **Kuota throughput bersama** — Operasi batch berbagi kuota per akun yang sama dengan rekan API masing-masing. **StartRunBatch**mengkonsumsi kuota **StartRun** layanan. **CancelRunBatch**mengkonsumsi **CancelRun** kuota, dan **DeleteRunBatch** mengkonsumsi **DeleteRun** kuota. Hindari memanggil run individual APIs saat batch besar sedang berlangsung, karena ini dapat menyebabkan kegagalan pengiriman.
+ **Pengajuan bertahap** - Berjalan dalam batch dikirimkan secara bertahap dan asinkron sesuai dengan kuota throughput Anda.
+ **Operasi non-atom** —**StartRunBatch**,**CancelRunBatch**, dan semuanya **DeleteRunBatch** dapat berhasil sebagian. Selalu periksa ringkasan pengiriman untuk mengidentifikasi proses yang perlu dicoba lagi.
+ **Konsistensi akhir** - Jalankan jumlah status eksekusi **GetBatch** mungkin tertinggal dari status run yang sebenarnya. Hitungan akhir akurat setelah batch mencapai`PROCESSED`.
+ **Filter tunggal per daftar panggilan** - **ListRunsInBatch** dan hanya **ListBatch** mendukung satu filter per panggilan API.
+ **Jalankan kembali tidak didukung** - Bidang `runId` (jalankan kembali) tidak didukung di. **StartRunBatch** Setiap pengiriman batch selalu membuat proses baru.
+ Alur **kerja Ready2Run - Batch run tidak didukung dengan alur** kerja Ready2Run.
+ **Batas konfigurasi sebaris** - Konfigurasi sebaris (`inlineSettings`) mendukung hingga 100 entri. Untuk batch yang lebih besar, gunakan`s3UriSettings`. Batas ini tidak dapat disesuaikan.
+ **File konfigurasi S3 - File** konfigurasi S3 harus berupa array JSON dari objek pengaturan run. Ukuran file maksimum adalah 6 GB, mendukung hingga 100.000 konfigurasi run.
+ **Kekekalan file S3** - Jangan memodifikasi file konfigurasi S3 setelah mengirimkan batch. HealthOmics memvalidasi tag entitas file (ETag) selama pengiriman dan gagal batch jika file telah berubah.