기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# HealthOmics에서 배치 실행
AWS HealthOmics 배치 실행을 사용하면 단일 API 요청으로 여러 실행을 제출할 수 있습니다. 배치의 각 실행은 공통 기본 구성을 공유하지만 입력과 실행별 파라미터가 다를 수 있습니다. 배치 실행은 제출 오버헤드를 줄이고 대규모 워크플로 처리를 위한 수명 주기 관리를 간소화합니다.
배치 실행을 통해 다음을 수행할 수 있습니다.
+ 단일 **StartRunBatch** 호출로 최대 100,000개의 실행을 제출하고 공유 구성을 한 번 정의하고 모든 실행에 적용합니다.
+ 이름, 출력 URI, 파라미터, 우선 순위 및 태그를 포함하여 개별 샘플에 대해 실행당 파라미터 재정의를 적용합니다.
+ **GetBatch** 및를 통해 전체 배치 상태 및 개별 실행 제출 진행 상황을 추적합니다**ListRunsInBatch**.
+ 를 사용하여 배치의 모든 실행을 취소합니다**CancelRunBatch**.
+ 를 사용하여 배치의 모든 실행을 삭제합니다**DeleteRunBatch**.
+ 를 사용하여 배치 메타데이터를 삭제합니다**DeleteBatch**.
**Topics**
+ [배치 실행 개념](#batch-concepts)
+ [사전 조건](#batch-prerequisites)
+ [배치 작업에 대한 IAM 권한](#batch-iam-permissions)
+ [시작하기: 첫 번째 배치 제출](#batch-getting-started)
+ [배치 실행 시작](#batch-starting)
+ [배치 진행 상황 모니터링](#batch-monitoring)
+ [실패한 실행 처리](#batch-handling-failures)
+ [배치 취소](#batch-canceling)
+ [배치 실행 삭제](#batch-deleting-runs)
+ [배치 메타데이터 삭제](#batch-deleting-metadata)
+ [배치에 대한 EventBridge 이벤트](#batch-eventbridge)
+ [제한 사항 및 고려 사항](#batch-limitations)
## 배치 실행 개념
+ **배치** - 공통 구성을 공유하는 워크플로 실행 모음으로, 자체 Amazon 리소스 이름(ARN) 및 수명 주기 상태를 사용하여 단일 리소스로 관리됩니다.
+ **기본 실행 설정**(`defaultRunSetting`) - 워크플로 ID, IAM 역할, 출력 URI 및 공통 파라미터와 같이 배치의 모든 실행에서 공유되는 워크플로 파라미터입니다.
+ **실행별 설정**(`inlineSettings` 또는 `s3UriSettings`) - 기본 실행 설정을 재정의하거나 병합하는 실행당 구성입니다. 각 항목에는 고유한가 포함되어야 합니다`runSettingId`.
+ **실행 설정 ID**(`runSettingId`) - 배치 내의 각 실행 구성에 대해 고객이 제공하는 필수 고유 식별자입니다. 제출 후 **ListRunsInBatch**를 사용하여 각 `runSettingId`를 HealthOmics 생성에 매핑`runId`하면 입력 구성에서 생성된 실행을 추적할 수 있습니다.
+ **배치 상태** - 배치 작업의 전체 상태입니다. 가능한 값은 다음과 같습니다.
+ `CREATING` - 배치가 생성 중입니다.
+ `PENDING` - 배치가 생성되었습니다. 실행 구성이 비동기적으로 검증되고 있습니다.
+ `SUBMITTING` - 검증이 완료되었습니다. 개별 실행이 제출되고 있습니다.
+ `INPROGRESS` - 모든 실행 제출을 시도했습니다. 실행이 실행 중입니다.
+ `STOPPING` - 취소 요청이 수신되어 실행이 중지되고 있습니다.
+ `CANCELLED` - 배치가 취소되었습니다.
+ `PROCESSED` - 모든 실행이 터미널 상태(완료됨, 실패 또는 취소됨)에 도달했습니다.
+ `FAILED` - 실행을 생성하기 전에 배치 자체가 실패했습니다. 세부 정보는 [배치 수준 실패](#batch-level-failures) 섹션을 참조하세요.
+ `RUNS_DELETING` - 배치의 실행이 삭제되고 있습니다.
+ `RUNS_DELETED` - 배치의 모든 실행이 삭제되었습니다.
+ **제출 상태** - 배치 내의 개별 실행에 대한 제출 결과입니다. 가능한 값은 다음과 같습니다.
+ `SUCCESS` - 실행이 성공적으로 제출되었습니다.
+ `FAILED` - 실행 제출에 실패했습니다(예: 검증 오류로 인해).
+ `CANCEL_SUCCESS` - 실행이 성공적으로 취소되었습니다.
+ `CANCEL_FAILED` - 실행 취소에 실패했습니다.
+ `DELETE_SUCCESS` - 실행이 성공적으로 삭제되었습니다.
+ `DELETE_FAILED` - 실행 삭제에 실패했습니다.
## 사전 조건
배치 실행을 시작하기 전에 다음이 있는지 확인합니다.
+ 활성 HealthOmics 프라이빗 워크플로입니다. 배치 실행은 Ready2Run 워크플로에서 지원되지 않습니다.
+ HealthOmics 워크플로를 실행하고 Amazon S3 버킷에 액세스할 수 있는 권한이 있는 IAM 서비스 역할입니다. 자세한 내용은 [에 대한 서비스 역할 AWS HealthOmics](permissions-service.md)을 참조하세요.
+ 입력 데이터 및 출력 결과를 위한 Amazon S3 위치입니다.
+ 각 샘플 또는 실험 구성에 대한 실행별 파라미터입니다.
## 배치 작업에 대한 IAM 권한
IAM 자격 증명에는 배치 작업과 기본 개별 실행 작업 모두에 대한 권한이 있어야 합니다. 다음 예제 정책은 모든 배치 작업에 대한 권한을 부여합니다.
```
{
"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"
}
}
}
]
}
```
**참고**
**StartRunBatch** 에는 배치 리소스와 실행, 워크플로 및 실행 그룹 리소스에 `omics:StartRun` 대한 이중 인증`omics:StartRunBatch`이 필요합니다. 배치가 성공하려면 두 권한을 모두 부여해야 합니다.
전달된 IAM 서비스 역할`roleArn`(HealthOmics에서 실행을 실행하는 데 사용)에는 개별 **StartRun** 호출과 동일한 권한이 필요합니다. 자세한 내용은 [에 대한 서비스 역할 AWS HealthOmics](permissions-service.md)을 참조하세요.
### 태그 지정 및 태그 기반 액세스 제어
배치 실행은 두 가지 수준에서 태그를 지원합니다.
+ **배치 태그**(**StartRunBatch**요청의 태그) - 배치 리소스에 적용됩니다. 태그 기반 액세스 제어(TBAC)는 배치 태그에 대해 완전히 적용됩니다.
+ **실행 태그**(`runTags` `defaultRunSetting` 및 실행당 `runTags`) - 개별 실행 리소스에 적용됩니다. 이러한 태그는 파라미터와 동일한 우선 순위 규칙을 사용하여 병합됩니다.
태그 기반 액세스 제어 정책을 사용하는 경우 IAM 정책에 적절한 `aws:RequestTag` 및 `aws:TagKeys` 조건이 `omics:TagResource` 포함되어 있는지 확인합니다.
**예: 배치 생성을 비프로덕션 환경으로 제한**
다음 정책은 사용자가 배치 및 실행을 생성할 수 있도록 허용하지만를 사용하여 리소스에 태그를 지정하는 것을 거부합니다. `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"
}
}
}
]
}
```
이 정책을 사용하는 경우:
+ `tags: {"environment": "dev"}` 배치에서 → 허용됨
+ `tags: {"environment": "production"}` 배치에서 → 거부됨(403)
+ `runTags: {"environment": "production"}`의 `defaultRunSetting` → 비동기식 생성 중 개별 실행에 대해 거부됨
## 시작하기: 첫 번째 배치 제출
다음 예제에서는 두 번의 실행으로 구성된 작은 배치를 제출하고, 진행 상황을 확인하고, 결과를 검토하는 방법을 안내합니다.
**1단계: 배치 제출**
```
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"}
}
]
}'
```
응답은 모든 후속 작업에 사용하는 배치 ID를 반환합니다.
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"status": "CREATING"
}
```
**2단계: 배치 진행 상황 확인**
```
aws omics get-batch --batch-id {{7123456}}
```
→ `CREATING` → `PENDING` → `SUBMITTING` → `INPROGRESS`에서 `status` 필드 진행 상황을 확인합니다`PROCESSED`. `submissionSummary`는 성공적으로 제출된 실행 수와 실행 진행 상황을 `runSummary` 보여줍니다.
**3단계: 개별 실행 검토**
```
aws omics list-runs-in-batch --batch-id {{7123456}}
```
각 항목은 `runSettingId` (예: `sample-A`)를 HealthOmics에서 생성한에 매핑`runId`하므로 결과를 입력 샘플로 다시 추적할 수 있습니다.
**4단계: 실패한 제출 확인**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
실행을 제출하지 못한 경우 문제를 진단`submissionFailureMessage`하는 데 도움이 되는 `submissionFailureReason` 및가 응답에 포함됩니다.
## 배치 실행 시작
**StartRunBatch**를 사용하여 단일 요청으로 여러 실행을 제출합니다. 요청에는 다음이 포함됩니다.
+ `defaultRunSetting` - 배치의 모든 실행에 대한 공유 구성입니다.
+ `batchRunSettings` - 개별 실행 구성으로, 다음 중 하나로 제공됩니다.
+ `inlineSettings` - 요청 본문에 직접 제공되는 최대 100개의 실행별 구성 배열입니다.
+ `s3UriSettings` - 실행 구성이 포함된 JSON 파일을 가리키는 Amazon S3 URI입니다. 100회가 넘는 실행이 있는 배치에 필요하며 최대 100,000회 실행을 지원합니다.
다음 필드를 제공할 수도 있습니다.
+ `batchName` - 사람이 읽을 수 있는 배치의 선택적 이름입니다.
+ `requestId` - 중복 배치 제출을 방지하기 위한 멱등성 토큰입니다.
+ `tags` - 배치 리소스 자체와 연결할 태그입니다.
### 인라인 실행 구성으로 작은 배치 제출
를 사용하여 요청 본문에 직접 실행별 구성 배열을 제공합니다`inlineSettings`. 각 항목에는 고유한가 포함되어야 합니다`runSettingId`(필수). `runSettingId`는 결과를 상호 연관시키는 키입니다.를 호출하면 **ListRunsInBatch**각 항목이를 HealthOmics 생성 `runId` 및 `runSettingId`에 매핑합니다`runArn`.
인라인 구성에 최대 100개의 항목을 포함할 수 있습니다.
```
{
"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"}
}
]
}'
```
### S3에서 실행 구성을 사용하여 대용량 배치 제출
실행이 100회를 초과하는 배치의 경우 실행 구성을 Amazon S3의 JSON 파일에 저장하고를 사용하여 URI를 제공합니다`s3UriSettings`. JSON 파일에는 각각 고유한가 있는 실행별 설정 객체 배열이 포함되어야 합니다`runSettingId`. 파일은 최대 100,000개의 항목을 포함할 수 있습니다.
S3 파일 형식은 `inlineSettings` 배열과 동일합니다.
```
[
{
"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"
}
}
]
```
**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"}'
```
**중요**
에 지정된 IAM 서비스 역할에는에 지정된 Amazon S3 객체에 대한 읽기 액세스 권한이 `roleArn` 있어야 합니다`s3UriSettings`. HealthOmics는 동기 API 호출 중에 Amazon S3 파일에 대한 액세스를 검증하고 파일의 ETag를 기록합니다. 제출 후 파일이 수정되면 비동기 처리 중에 배치가 실패합니다.
### 응답
요청이 성공하면 배치 ID와 초기 상태가 반환됩니다.
```
{
"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"
}
}
```
동기 검증에 실패하면(예: 잘못된 워크플로 ID 또는 액세스할 수 없는 Amazon S3 URI) API는 실행이 제출되기 전에 오류를 반환합니다.
### 파라미터 참조
다음 표에는 실행당 설정할 수 있는 **StartRun** 필드와 배치 수준에서만 적용되는 필드가 나와 있습니다. 전체 필드 설명은 **StartRun** API 참조를 참조하세요.
| Field | 배치 수준(`defaultRunSetting`) | 실행당 구성 가능(`inlineSettings`) |
| --- | --- | --- |
| workflowId | 예 | 아니요 |
| workflowType | 예 | 아니요 |
| workflowVersionName | 예 | 아니요 |
| workflowOwnerId | 예 | 아니요 |
| roleArn | 예 | 아니요 |
| storageCapacity | 예 | 아니요 |
| storageType | 예 | 아니요 |
| runGroupId | 예 | 아니요 |
| logLevel | 예 | 아니요 |
| cacheBehavior | 예 | 아니요 |
| cacheId | 예 | 아니요 |
| retentionMode | 예 | 아니요 |
| name | 예 | 예 |
| outputUri | 예 | 예 |
| parameters | 예 | 예(병합됨) |
| priority | 예 | 예 |
| runTags | 예 | 예(병합됨) |
| outputBucketOwnerId | 예 | 예 |
**참고**
`runId` (개별 재실행의 경우) 필드는에 대한 입력으로 지원되지 않습니다**StartRunBatch**. 각 배치 제출은 항상 새 실행을 생성하고 각 실행은를 수신합니다`runId`. 개별 실행을 재시도하려면 [HealthOmics에서 실행 다시 실행](rerun-a-run.md) 섹션을 참조하세요.
### 파라미터 병합
의 파라미터`defaultRunSetting`는에 제공된 실행별 파라미터와 병합`inlineSettings`되거나 S3 URI를 통해 병합됩니다. 키가 겹치는 경우 실행별 값이 우선합니다.
**예:**
| 소스 | 파라미터 |
| --- | --- |
| defaultRunSetting | {"referenceUri": "s3://bucket/ref.fasta", "version": "v1"} |
| inlineSettings 항목 | {"inputUri": "s3://bucket/sample.fastq", "version": "v2"} |
| 병합된 결과 | {"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"} |
동일한 병합 동작이에 적용됩니다`runTags`. 실행별 구성에 지정된 태그는에서 동일한 키로 태그를 재정의`defaultRunSetting.runTags`하고 새 키가 추가됩니다.
**태그 병합 예제:**
| 소스 | Tags |
| --- | --- |
| defaultRunSetting.runTags | {"project": "cancer-research", "pipeline-version": "v2.1"} |
| inlineSettings[].runTags | {"patient-id": "patient001", "pipeline-version": "v3.0"} |
| 병합된 결과(실행에 적용됨) | {"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"} |
**참고**
배치 수준 태그(**StartRunBatch**요청 시)는 배치 리소스 자체에만 적용됩니다. 개별 실행에 의해 상속되지 않습니다. 실행 수준 태그는 `defaultRunSetting.runTags` 및 실행당를 통해 제어됩니다`runTags`.
### 점진적 제출
**StartRunBatch**는 공통 필드를 동기적으로 검증하고 배치 ID 및 상태와 함께 즉시 반환합니다`CREATING`. 배치의 실행은 처리량 할당량에 따라 제어된 속도로 점진적으로 비동기적으로 제출됩니다.
HealthOmics 할당량의 전체 목록은 섹션을 참조하세요[HealthOmics 서비스 할당량](service-quotas.md).
배치는 정상 처리 중에 다음 상태를 통해 전환됩니다.
1. `CREATING` - 배치가 생성 중입니다.
1. `PENDING` - 배치 생성, 구성 실행 검증 중.
1. `SUBMITTING` - 검증 완료, 개별 실행 제출 중.
1. `INPROGRESS` - 모든 실행 제출이 시도되고 실행이 실행 중입니다.
1. `PROCESSED` - 모든 실행이 터미널 상태에 도달했습니다.
**중요**
배치 실행 제출은 직접 **StartRun** API 직접 호출과 동일한 **StartRun** 처리량 할당량을 공유합니다. 대규모 배치가 처리되는 동안 **StartRun** 직접를 호출하는 경우 배치 제출과 직접 호출이 모두 동일한 용량으로 경쟁합니다. 이로 인해 배치 실행이 실패하거나`ThrottlingException`(속도 초과) 직접 **StartRun** 호출이 제한될 수 있습니다. **CancelRun** 및 에도 동일하게 적용됩니다. **DeleteRun** 이러한 할당량은 **DeleteRunBatch** 각각 **CancelRunBatch** 및와 처리량 할당량을 공유합니다.
## 배치 진행 상황 모니터링
### 배치 상태 가져오기
**GetBatch**를 사용하여 배치의 전체 상태 및 제출 진행 상황을 검색합니다.
```
aws omics get-batch --batch-id {{7123456}}
```
응답에는 다음이 포함됩니다.
+ `status` - 전체 배치 상태입니다.
+ `submissionSummary` - 시작, 취소 및 삭제 작업에 대한 성공 및 실패한 제출 수입니다.
+ `runSummary` - 각 실행 상태의 실행 수입니다. 가능한 값: `PENDING`, , `STARTING`, `RUNNING`, `STOPPING`, `COMPLETED``DELETED`, `CANCELLED`또는 `FAILED`
+ 수명 주기 이벤트의 타임스탬프 - `creationTime`, `submittedTime`, `processedTime`, `failedTime`.
**응답 예제:**
```
{
"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"
}
}
```
**참고**
실행 요약은 최종적으로 일관되며 실제 실행 상태보다 지연될 수 있습니다. 배치가 `PROCESSED` 상태에 도달하면 최종 수가 조정됩니다.
### 배치로 실행 나열
**ListRunsInBatch**를 사용하여 배치 내의 개별 실행에 대한 세부 정보를 검색합니다. 결과는 페이지 매김됩니다.
```
aws omics list-runs-in-batch --batch-id {{7123456}}
```
다음 쿼리 파라미터 중 하나를 사용하여 결과를 필터링할 수 있습니다. 호출당 하나의 필터만 지원됩니다.
| 필터 | 설명 |
| --- | --- |
| submissionStatus | 제출 상태를 기준으로 필터링: SUCCESS, FAILED, CANCEL\_SUCCESS, CANCEL\_FAILED, DELETE\_SUCCESS또는 DELETE\_FAILED. |
| runSettingId | 특정 실행 설정 ID에 대한 실행을 검색합니다. |
| runId | 특정 실행 ID에 대한 실행을 검색합니다. |
**예: 실패한 제출 나열**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
각 결과에는 다음이 포함됩니다.
+ `runSettingId` - 실행 구성에 대해 고객이 제공한 식별자입니다.
+ `runId` - HealthOmics에서 생성한 실행 식별자입니다(제출에 실패한 경우 비어 있음).
+ `runArn` - 실행의 전체 ARN입니다.
+ `submissionStatus` - 제출 결과(`SUCCESS`, `FAILED`, `CANCEL_SUCCESS`, `CANCEL_FAILED``DELETE_SUCCESS`, 또는 `DELETE_FAILED`).
+ `submissionFailureReason` 및 `submissionFailureMessage` - 제출 실패 시 세부 정보입니다.
**참고**
`runSettingId`는 실행 구성에서 제공한 고객 지정 식별자입니다. `runId`는 성공적으로 제출한 후 할당된 HealthOmics 생성 식별자입니다. 제출에 실패하면 `runId`가 비어 있습니다.
### 배치 나열
**ListBatch**를 사용하여 계정의 모든 배치 리소스를 검색합니다. 결과는 페이지 매김됩니다.
```
aws omics list-batch
```
다음 쿼리 파라미터를 사용하여 결과를 필터링할 수 있습니다.
| 필터 | 설명 |
| --- | --- |
| status | 배치 상태를 기준으로 필터링합니다. |
| name | 배치 이름을 기준으로 필터링합니다. |
| runGroupId | 실행 그룹 ID를 기준으로 필터링합니다. |
## 실패한 실행 처리
배치 처리에는 두 가지 고유한 유형의 실패가 있습니다. 차이점을 이해하는 것은 문제 해결에 매우 중요합니다.
### 배치 수준 실패
배치 수준 실패는 배치 자체가 실패했음을 의미합니다. 실행이 생성되지 않았습니다(또는 실패 전에 일부만 생성됨). 배치 상태는 입니다`FAILED`.
를 호출**GetBatch**하고 `failureReason` 필드를 확인합니다. 일반적인 실패 이유는 다음과 같습니다.
| 장애 범주 | `failureReason` 메시지 예 | 작업 |
| --- | --- | --- |
| 유효성 검사 오류 | "배치에 100,001회 실행이 있지만 100,000회 실행이 최대입니다.", "예상된 50개의 고유한 runSettingIds가 있지만 49개가 있었습니다", "실행 구성에서 잘못된 JSON 형식" | 구성을 수정하고 새 배치를 제출합니다. 이러한 오류는 재시도할 수 없습니다. |
| S3 구성 변경됨 | “예상 s3UriConfigs etag: “abc123”이지만: “def456”이었습니다. s3UriConfigs는 StartRunBatch를 호출한 후 변경되었습니다.” | 제출 후 S3 파일을 수정하지 마십시오. 현재 파일로 다시 제출합니다. |
| 일시적인 서비스 오류 | “서비스에 일시적인 오류가 발생했습니다. 배치를 다시 시도합니다.” | 동일한 배치를 다시 제출하여 재시도합니다. 멱등성requestId에 동일한를 사용합니다. |
**예: 검증으로 인한 배치 실패**
```
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"
}
```
### 실행 수준 실패
실행 수준 실패는 배치 자체가 성공했지만(상태는 `INPROGRESS` 또는 `PROCESSED`) 개별 실행이 제출되지 않았음을 의미합니다. 배치는 다른 실행을 계속 처리합니다. 첫 번째 실패 시 중지되지 않습니다.
**1: 제출 요약 확인**
```
aws omics get-batch --batch-id {{7123456}}
```
를 살펴봅니다`submissionSummary.failedStartSubmissionCount`. 이 값이 0보다 크면 제출 중에 일부 실행이 실패한 것입니다.
**2. 실패한 제출 나열**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
실패한 각 항목에는 다음이 포함됩니다.
+ `runSettingId` - 실패한 실행 구성입니다.
+ `submissionFailureReason` - 오류 범주입니다.
+ `submissionFailureMessage` - 자세한 오류 메시지입니다.
**3. 제출 실패 이유**
다음 표에는 개별 실행에서에 대해 가능한 값이 나열되어 `submissionFailureReason` 있습니다.
| `submissionFailureReason` | 의미 | 재시도 가능 여부 |
| --- | --- | --- |
| ValidationException | 실행 파라미터가 잘못되었습니다. 예를 들어 파라미터가 워크플로 정의, 잘못된 S3 URI 형식 또는 제약 조건 위반과 일치하지 않습니다. | 아니요 - 구성을 수정합니다. |
| AccessDeniedException | IAM 서비스 역할에는 필요한 리소스(S3 입력, KMS 키, CloudWatch Logs, ECR 이미지)에 액세스할 수 있는 권한이 없습니다. | 아니요 - 역할 정책을 업데이트합니다. |
| ResourceNotFoundException | 참조된 리소스(워크플로, 실행 그룹 또는 실행 캐시)가 존재하지 않거나 활성 상태가 아닙니다. | 아니요 - 리소스 IDs 확인합니다. |
| ServiceQuotaExceededException | 계정이 최대 활성 실행 수 또는 다른 서비스 할당량에 도달했습니다. | 실행이 완료될 때까지 기다리거나 할당량 증가를 요청합니다. |
| ConflictException | 중복 실행 생성 시도와 같이 충돌하는 작업이 진행 중입니다. | 일반적으로 자체적으로 확인됩니다. |
| ThrottlingException | API 속도 제한으로 인해 요청이 제한되었습니다. | 서비스는 자동으로 재시도합니다. 재시도 후에도 지속되면 동시 배치 제출을 줄입니다. |
| RequestTimeoutException | 처리 중에 요청 시간이 초과되었습니다. | 서비스는 자동으로 재시도합니다. 문제가 지속되면 다운스트림 문제를 확인합니다. |
| InternalServerException | 예기치 않은 서비스 오류가 발생했습니다. | 서비스는 자동으로 재시도합니다. 재시도 후에도 지속되면 Support에 문의하십시오 AWS . |
**참고**
HealthOmics 각 실행에 대해 임시 오류(`ThrottlingException`, `RequestTimeoutException`, `InternalServerException`)를 자동으로 재시도합니다. 실행은 모든 재시도가 소진된 후에`FAILED`만 로 표시됩니다. 재시도할 수 없는 오류(`ValidationException`, `AccessDeniedException`, `ResourceNotFoundException`)는 재시도 없이 즉시 실패합니다.
**4. 실패한 실행 다시 제출**
수정된 실행 구성만 포함하는 새 배치를 생성합니다. 동일한를 사용하고 실패한 `runSettingId` 항목만 `defaultRunSetting` 포함합니다. 실패한 실행에는 기본 제공 재시도 메커니즘이 없으므로 새 배치를 제출해야 합니다.
## 배치 취소
**CancelRunBatch**를 사용하여 진행 중인 배치를 취소합니다. 취소 작업:
+ 아직 not-yet-submitted 실행과 보류 중인 실행이 시작되지 않도록 방지
+ 이미 시작된 실행에 대한 **CancelRun** 요청을 제출합니다.
```
aws omics cancel-run-batch --batch-id {{7123456}}
```
**중요**
취소는 `PENDING`, `SUBMITTING`또는 `INPROGRESS` 상태의 배치에만 허용됩니다.
한 번에 배치당 하나의 취소 또는 삭제 작업만 허용됩니다.
취소 작업은 원자성이 없으며 부분적으로 성공할 수 있습니다. **GetBatch**를 사용하여 `failedCancelSubmissionCount`에서 `successfulCancelSubmissionCount` 및를 검토합니다`submissionSummary`.
## 배치 실행 삭제
**DeleteRunBatch**를 사용하여 배치 내의 개별 실행을 삭제합니다.
```
aws omics delete-run-batch --batch-id {{7123456}}
```
**중요**
삭제는 `PROCESSED` 또는 `CANCELLED` 상태의 배치에만 허용됩니다.
한 번에 배치당 하나의 취소 또는 삭제 작업만 허용됩니다.
삭제 작업은 비원자성이며 부분적으로 성공할 수 있습니다. **GetBatch**를 사용하여 `failedDeleteSubmissionCount`에서 `successfulDeleteSubmissionCount` 및를 검토합니다`submissionSummary`.
## 배치 메타데이터 삭제
**DeleteBatch**를 사용하여 배치 리소스 및 관련 메타데이터를 제거합니다. 이는와 별도의 작업입니다**DeleteRunBatch**.
```
aws omics delete-batch --batch-id {{7123456}}
```
**중요**
**DeleteBatch** 에서는 배치가 터미널 상태(`PROCESSED`, `CANCELLED`, 또는 `FAILED``RUNS_DELETED`)여야 합니다.
**DeleteBatch**는 개별 실행을 삭제하지 않습니다. 실행도 제거하려면 **DeleteRunBatch** 먼저를 사용합니다.
이 **DeleteBatch** 완료되면 배치 메타데이터에 더 이상 액세스할 수 없습니다. 삭제된 배치**CancelRunBatch**에서는 **GetBatch**, **DeleteRunBatch**, 또는 **ListRunsInBatch**를 호출할 수 없습니다.
## 배치에 대한 EventBridge 이벤트
HealthOmics는 배치 상태가 변경될 때마다 Amazon EventBridge로 이벤트를 전송합니다. 이러한 이벤트를 사용하여 워크플로를 자동화할 수 있습니다. 예를 들어 배치가 완료되거나 실패할 때 알림을 트리거하거나 모든 실행이 완료되면 다운스트림 파이프라인을 시작할 수 있습니다.
배치 이벤트는 다른 HealthOmics 이벤트와 동일한 이벤트 버스 및 소스를 사용합니다. 일반적인 설정 지침은 섹션을 참조하세요[에서 EventBridge 사용 AWS HealthOmics](eventbridge.md).
### 이벤트 세부 정보 유형
| 이벤트 이름 | 다음과 같은 경우 내보내집니다. |
| --- | --- |
| RunBatch 상태 변경 | 배치가 새 상태로 전환됨(CREATING, , PENDING, SUBMITTING, INPROGRESS, STOPPING, CANCELLED, PROCESSEDFAILED, RUNS\_DELETING, RUNS\_DELETED) |
### 이벤트 세부 정보 필드
배치 이벤트의 `detail` 객체에는 다음 필드가 포함됩니다.
| Field | Type | 설명 |
| --- | --- | --- |
| omicsVersion | 문자열 | 이벤트 스키마 버전(현재 1.0.0). |
| arn | 문자열 | 배치 ARN입니다. |
| batchId | 문자열 | 배치 식별자입니다. |
| status | 문자열 | 새 배치 상태입니다. |
| uuid | 문자열 | 배치 UUID입니다. |
| batchName | 문자열 | 배치 이름(제공된 경우). |
| totalRuns | 문자열 | 배치의 총 실행 수입니다. |
| failureReason | 문자열 | 실패 이유(상태가 인 경우에만 표시됨FAILED). |
| failureMessage | 문자열 | 세부 실패 메시지(상태가 인 경우에만 표시됨FAILED). |
| successfulStartSubmissionCount | 문자열 | 성공적으로 제출된 실행 수입니다. |
| failedStartSubmissionCount | 문자열 | 제출에 실패한 실행 수입니다. |
| pendingStartSubmissionCount | 문자열 | 아직 제출 보류 중인 실행 수입니다. |
| pendingRunCount | 문자열 | 보류 중인 상태의 실행 수입니다. |
| startingRunCount | 문자열 | 시작하는 실행 수입니다. |
| runningRunCount | 문자열 | 현재 실행 중인 실행 수입니다. |
| stoppingRunCount | 문자열 | 중지 중인 실행 수입니다. |
| completedRunCount | 문자열 | 완료된 실행 수입니다. |
| failedRunCount | 문자열 | 실패한 실행 수. |
| cancelledRunCount | 문자열 | 취소된 실행 수입니다. |
| deletedRunCount | 문자열 | 삭제된 실행 수입니다. |
| workflowId | 문자열 | 워크플로 식별자입니다. |
| workflowArn | 문자열 | 워크플로 ARN입니다. |
| workflowVersionArn | 문자열 | 워크플로 버전 ARN(해당하는 경우). |
| workflowOwnerId | 문자열 | 워크플로 소유자 계정 ID(공유 워크플로용). |
| runCache | 문자열 | 실행 캐시 ARN(해당하는 경우). |
| runCacheBehavior | 문자열 | 실행 캐시 동작(해당하는 경우). |
### 이벤트 예제
**예: 배치 완료 이벤트**
```
{
"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"
}
}
```
**예: 배치 실패 이벤트**
```
{
"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"
}
}
```
**예: 배치 완료를 위한 EventBridge 규칙**
배치가 터미널 상태에 도달하면 다음 이벤트 패턴이 일치합니다.
```
{
"source": ["aws.omics"],
"detail-type": ["RunBatch Status Change"],
"detail": {
"status": ["PROCESSED", "FAILED", "CANCELLED"]
}
}
```
## 제한 사항 및 고려 사항
+ **공유 처리량 할당량 **- 배치 작업은 개별 API 할당량과 동일한 계정당 할당량을 공유합니다.는 **StartRun** 서비스 할당량을 **StartRunBatch** 사용합니다. **CancelRun**는 할당량을 **CancelRunBatch** 소비하고 **DeleteRun**는 할당량을 **DeleteRunBatch** 소비합니다. 대용량 배치가 진행되는 동안에는 개별 실행 APIs를 호출하지 마십시오. 제출 실패가 발생할 수 있습니다.
+ **점진적 제출** - 배치의 실행은 처리량 할당량에 따라 점진적으로 비동기적으로 제출됩니다.
+ **비원자성 작업 -** **StartRunBatch**, 및 **CancelRunBatch**는 모두 부분적으로 성공할 **DeleteRunBatch** 수 있습니다. 항상 제출 요약을 확인하여 재시도가 필요한 실행을 식별합니다.
+ **최종 일관성** -의 실행 상태 수는 실제 실행 상태보다 지연될 **GetBatch** 수 있습니다. 배치가에 도달하면 최종 개수가 정확합니다`PROCESSED`.
+ **목록 호출당 단일 필터** - **ListRunsInBatch**는 API 호출당 하나의 필터만 **ListBatch** 지원합니다.
+ **재실행은 지원되지 않음** - `runId` (재실행) 필드는에서 지원되지 않습니다**StartRunBatch**. 각 배치 제출은 항상 새 실행을 생성합니다.
+ **Ready2Run 워크플로** - 배치 실행은 Ready2Run 워크플로에서 지원되지 않습니다.
+ **인라인 구성 제한** - 인라인 구성(`inlineSettings`)은 최대 100개의 항목을 지원합니다. 더 큰 배치의 경우를 사용합니다`s3UriSettings`. 이 제한은 조정할 수 없습니다.
+ **S3 구성 파일** - S3 구성 파일은 실행 설정 객체의 JSON 배열이어야 합니다. 최대 파일 크기는 6GB이며 최대 100,000개의 실행 구성을 지원합니다.
+ **S3 파일 불변성** - 배치를 제출한 후에는 S3 구성 파일을 수정하지 마십시오. HealthOmics는 제출 중에 파일의 개체 태그(ETag)를 검증하고 파일이 변경된 경우 배치에 실패합니다.