기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

HealthOmics에서 배치 실행

AWS HealthOmics 배치 실행을 사용하면 단일 API 요청으로 여러 실행을 제출할 수 있습니다. 배치의 각 실행은 공통 기본 구성을 공유하지만 입력과 실행별 파라미터가 다를 수 있습니다. 배치 실행은 제출 오버헤드를 줄이고 대규모 워크플로 처리를 위한 수명 주기 관리를 간소화합니다.

배치 실행을 통해 다음을 수행할 수 있습니다.

배치 실행 개념

사전 조건

배치 실행을 시작하기 전에 다음이 있는지 확인합니다.

배치 작업에 대한 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"
        }
      }
    }
  ]
}

전달된 IAM 서비스 역할roleArn(HealthOmics에서 실행을 실행하는 데 사용)에는 개별 StartRun 호출과 동일한 권한이 필요합니다. 자세한 내용은 에 대한 서비스 역할 AWS HealthOmics을 참조하세요.

태그 지정 및 태그 기반 액세스 제어

배치 실행은 두 가지 수준에서 태그를 지원합니다.

태그 기반 액세스 제어 정책을 사용하는 경우 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"
        }
      }
    }
  ]
}

이 정책을 사용하는 경우:

시작하기: 첫 번째 배치 제출

다음 예제에서는 두 번의 실행으로 구성된 작은 배치를 제출하고, 진행 상황을 확인하고, 결과를 검토하는 방법을 안내합니다.

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를 사용하여 단일 요청으로 여러 실행을 제출합니다. 요청에는 다음이 포함됩니다.

다음 필드를 제공할 수도 있습니다.

인라인 실행 구성으로 작은 배치 제출

를 사용하여 요청 본문에 직접 실행별 구성 배열을 제공합니다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"}'

응답

요청이 성공하면 배치 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 참조를 참조하세요.

파라미터 병합

의 파라미터defaultRunSetting는에 제공된 실행별 파라미터와 병합inlineSettings되거나 S3 URI를 통해 병합됩니다. 키가 겹치는 경우 실행별 값이 우선합니다.

예:

동일한 병합 동작이에 적용됩니다runTags. 실행별 구성에 지정된 태그는에서 동일한 키로 태그를 재정의defaultRunSetting.runTags하고 새 키가 추가됩니다.

태그 병합 예제:

점진적 제출

StartRunBatch는 공통 필드를 동기적으로 검증하고 배치 ID 및 상태와 함께 즉시 반환합니다CREATING. 배치의 실행은 처리량 할당량에 따라 제어된 속도로 점진적으로 비동기적으로 제출됩니다.

HealthOmics 할당량의 전체 목록은 섹션을 참조하세요HealthOmics 서비스 할당량.

배치는 정상 처리 중에 다음 상태를 통해 전환됩니다.

배치 진행 상황 모니터링

배치 상태 가져오기

GetBatch를 사용하여 배치의 전체 상태 및 제출 진행 상황을 검색합니다.

aws omics get-batch --batch-id 7123456

응답에는 다음이 포함됩니다.

응답 예제:

{
  "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"
  }
}

배치로 실행 나열

ListRunsInBatch를 사용하여 배치 내의 개별 실행에 대한 세부 정보를 검색합니다. 결과는 페이지 매김됩니다.

aws omics list-runs-in-batch --batch-id 7123456

다음 쿼리 파라미터 중 하나를 사용하여 결과를 필터링할 수 있습니다. 호출당 하나의 필터만 지원됩니다.

예: 실패한 제출 나열

aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED

각 결과에는 다음이 포함됩니다.

배치 나열

ListBatch를 사용하여 계정의 모든 배치 리소스를 검색합니다. 결과는 페이지 매김됩니다.

aws omics list-batch

다음 쿼리 파라미터를 사용하여 결과를 필터링할 수 있습니다.

실패한 실행 처리

배치 처리에는 두 가지 고유한 유형의 실패가 있습니다. 차이점을 이해하는 것은 문제 해결에 매우 중요합니다.

배치 수준 실패

배치 수준 실패는 배치 자체가 실패했음을 의미합니다. 실행이 생성되지 않았습니다(또는 실패 전에 일부만 생성됨). 배치 상태는 입니다FAILED.

를 호출GetBatch하고 failureReason 필드를 확인합니다. 일반적인 실패 이유는 다음과 같습니다.

예: 검증으로 인한 배치 실패

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

실패한 각 항목에는 다음이 포함됩니다.

3. 제출 실패 이유

다음 표에는 개별 실행에서에 대해 가능한 값이 나열되어 submissionFailureReason 있습니다.

4. 실패한 실행 다시 제출

수정된 실행 구성만 포함하는 새 배치를 생성합니다. 동일한를 사용하고 실패한 runSettingId 항목만 defaultRunSetting 포함합니다. 실패한 실행에는 기본 제공 재시도 메커니즘이 없으므로 새 배치를 제출해야 합니다.

배치 취소

CancelRunBatch를 사용하여 진행 중인 배치를 취소합니다. 취소 작업:

aws omics cancel-run-batch --batch-id 7123456

배치 실행 삭제

DeleteRunBatch를 사용하여 배치 내의 개별 실행을 삭제합니다.

aws omics delete-run-batch --batch-id 7123456

배치 메타데이터 삭제

DeleteBatch를 사용하여 배치 리소스 및 관련 메타데이터를 제거합니다. 이는와 별도의 작업입니다DeleteRunBatch.

aws omics delete-batch --batch-id 7123456

배치에 대한 EventBridge 이벤트

HealthOmics는 배치 상태가 변경될 때마다 Amazon EventBridge로 이벤트를 전송합니다. 이러한 이벤트를 사용하여 워크플로를 자동화할 수 있습니다. 예를 들어 배치가 완료되거나 실패할 때 알림을 트리거하거나 모든 실행이 완료되면 다운스트림 파이프라인을 시작할 수 있습니다.

배치 이벤트는 다른 HealthOmics 이벤트와 동일한 이벤트 버스 및 소스를 사용합니다. 일반적인 설정 지침은 섹션을 참조하세요에서 EventBridge 사용 AWS HealthOmics.

이벤트 세부 정보 유형

이벤트 세부 정보 필드

배치 이벤트의 detail 객체에는 다음 필드가 포함됩니다.

이벤트 예제

예: 배치 완료 이벤트

{
  "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"]
  }
}

제한 사항 및 고려 사항