翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# HealthOmics でのバッチ実行
<a name="workflows-batch"></a>

AWS HealthOmics バッチ実行では、1 つの API リクエストで複数の実行を送信できます。バッチ内の各実行は共通の基本設定を共有しますが、異なる入力と実行固有のパラメータを持つことができます。バッチ実行は送信オーバーヘッドを削減し、大規模なワークフロー処理のライフサイクル管理を簡素化します。

バッチ実行では、次のことができます。
+ 1 回の**StartRunBatch**呼び出しで最大 100,000 回の実行を送信し、共有設定を 1 回定義してすべての実行に適用します。
+ 名前、出力 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)

## バッチ実行の概念
<a name="batch-concepts"></a>
+ **バッチ** — 共通の設定を共有するワークフロー実行のコレクション。独自の Amazon リソースネーム (ARN) とライフサイクルステータスを持つ単一のリソースとして管理されます。
+ **デフォルトの実行設定** (`defaultRunSetting`) — ワークフロー ID、IAM ロール、出力 URI、一般的なパラメータなど、バッチ内のすべての実行で共有されるワークフローパラメータ。
+ **実行固有の設定** (`inlineSettings` または `s3UriSettings`) — デフォルトの実行設定で上書きまたはマージする実行ごとの設定。各エントリには一意の を含める必要があります`runSettingId`。
+ **実行設定 ID** (`runSettingId`) — バッチ内の各実行設定に必要な、お客様が用意した一意の識別子。送信後、 を使用して各 **ListRunsInBatch**を HealthOmics が生成した `runSettingId`にマッピングし`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` — 実行の削除に失敗しました。

## 前提条件
<a name="batch-prerequisites"></a>

バッチ実行を開始する前に、以下を確認してください。
+ アクティブな HealthOmics プライベートワークフロー。バッチ実行は、Ready2Run ワークフローではサポートされていません。
+ HealthOmics ワークフローを実行し、Amazon S3 バケットにアクセスするアクセス許可を持つ IAM サービスロール。詳細については、「[のサービスロール AWS HealthOmics](permissions-service.md)」を参照してください。
+ 入力データと出力結果の Amazon S3 の場所。
+ 各サンプルまたは実験設定の実行固有のパラメータ。

## バッチオペレーションの IAM アクセス許可
<a name="batch-iam-permissions"></a>

IAM ID には、バッチオペレーションと基盤となる個々の実行オペレーションの両方に対するアクセス許可が必要です。次のポリシー例では、すべてのバッチオペレーションのアクセス許可を付与します。

```
{
  "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:StartRunBatch`と実行、ワークフロー、実行グループリソース`omics:StartRun`の 2 つの認可が必要です。バッチを成功させるには、両方のアクセス許可を付与する必要があります。

渡された IAM サービスロール `roleArn` (HealthOmics が実行を実行するために使用する) には、個々の**StartRun**呼び出しと同じアクセス許可が必要です。詳細については、「[のサービスロール AWS HealthOmics](permissions-service.md)」を参照してください。

### タグ付けとタグベースのアクセスコントロール
<a name="batch-tagging"></a>

バッチ実行は、次の 2 つのレベルでタグをサポートします。
+ **バッチタグ** (**StartRunBatch**リクエストのタグ) — バッチリソースに適用されます。タグベースのアクセスコントロール (TBAC) は、バッチタグに対して完全に適用されます。
+ **実行タグ** (`runTags` `defaultRunSetting`および実行ごとの `runTags`) — 個々の実行リソースに適用されます。これらのタグは、パラメータと同じ優先順位ルールを使用してマージされます。

タグベースのアクセスコントロールポリシーを使用する場合は、IAM ポリシー`omics:TagResource`に適切な `aws:RequestTag`および `aws:TagKeys`条件が含まれていることを確認してください。

**例: バッチ作成を非本番環境に制限する**

次のポリシーでは、ユーザーはバッチを作成して実行できますが、 を使用したリソースのタグ付けは拒否されます`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` → 非同期作成中の個々の実行に対して拒否

## 開始方法: 最初のバッチを送信する
<a name="batch-getting-started"></a>

次の例では、2 つの実行の小さなバッチの送信、進行状況の確認、結果の確認について説明します。

**ステップ 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}}
```

`status` フィールドの進行状況を → `CREATING` → `PENDING` → `SUBMITTING` → `INPROGRESS` → から監視します`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`と がレスポンスに含まれます。

## バッチ実行の開始
<a name="batch-starting"></a>

を使用して**StartRunBatch**、1 つのリクエストで複数の実行を送信します。リクエストには以下が含まれます。
+ `defaultRunSetting` — バッチ内のすべての実行の共有設定。
+ `batchRunSettings` — 次のいずれかとして提供される個々の実行設定。
  + `inlineSettings` — リクエスト本文に直接提供される最大 100 個の実行固有の設定の配列。
  + `s3UriSettings` — 実行設定を含む JSON ファイルを指す Amazon S3 URI。100 回を超える実行のバッチに必要で、最大 100,000 回の実行をサポートします。

次のフィールドを指定することもできます。
+ `batchName` — バッチのオプションの人間が読み取れる名前。
+ `requestId` — 重複するバッチ送信を防ぐためのべき等性トークン。
+ `tags` — バッチリソース自体に関連付けるタグ。

### インライン実行設定を使用して小さなバッチを送信する
<a name="batch-inline-settings"></a>

を使用して、実行固有の設定の配列をリクエスト本文に直接指定します`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 で実行設定を使用して大きなバッチを送信する
<a name="batch-s3-settings"></a>

実行数が 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 を記録します。送信後にファイルが変更されると、バッチは非同期処理中に失敗します。

### [応答]
<a name="batch-response"></a>

リクエストが成功すると、バッチ 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 は実行が送信される前にエラーを返します。

### パラメータリファレンス
<a name="batch-parameter-reference"></a>

次の表は、実行ごとに設定できる**StartRun**フィールドと、バッチレベルでのみ適用されるフィールドを示しています。フィールドの詳細については、 **StartRun** API リファレンスを参照してください。


| フィールド | バッチレベル (`defaultRunSetting`) | 実行ごとの設定可能 (`inlineSettings`) | 
| --- | --- | --- | 
| workflowId | はい | いいえ | 
| workflowType | はい | いいえ | 
| workflowVersionName | はい | いいえ | 
| workflowOwnerId | はい | いいえ | 
| roleArn | はい | いいえ | 
| storageCapacity | はい | いいえ | 
| storageType | はい | いいえ | 
| runGroupId | はい | いいえ | 
| logLevel | はい | いいえ | 
| cacheBehavior | はい | いいえ | 
| cacheId | はい | いいえ | 
| retentionMode | はい | いいえ | 
| networkingMode | はい | いいえ | 
| configurationName | はい | いいえ | 
| name | はい | はい | 
| outputUri | はい | はい | 
| parameters | はい | はい (マージ) | 
| priority | はい  | はい | 
| runTags | はい | はい (マージ) | 
| outputBucketOwnerId | はい  | はい | 

**注記**  
`runId` (個々の再実行の場合) フィールドは、 への入力としてサポートされていません**StartRunBatch**。各バッチ送信は常に新しい実行を作成し、各実行は を受け取ります`runId`。個々の実行を再試行するには[HealthOmics で実行を再実行する](rerun-a-run.md)、「」を参照してください。

### パラメータのマージ
<a name="batch-parameter-merging"></a>

のパラメータ`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`、新しいキーが追加されます。

**タグマージの例:**


| ソース | タグ | 
| --- | --- | 
| 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`。

### 段階的な送信
<a name="batch-gradual-submission"></a>

**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**および と共有されます。

## バッチの進行状況のモニタリング
<a name="batch-monitoring"></a>

### バッチステータスの取得
<a name="batch-get-status"></a>

を使用して**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`ステータスに達すると、最終カウントが調整されます。

### バッチで実行を一覧表示する
<a name="batch-list-runs"></a>

を使用して**ListRunsInBatch**、バッチ内の個々の実行の詳細情報を取得します。結果はページ分割されます。

```
aws omics list-runs-in-batch --batch-id {{7123456}}
```

次のいずれかのクエリパラメータを使用して結果をフィルタリングできます。呼び出しごとにサポートされるフィルターは 1 つだけです。


| フィルター | 説明 | 
| --- | --- | 
| 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`は空です。

### バッチを一覧表示する
<a name="batch-list-batches"></a>

**ListBatch** を使用して、アカウント内のすべてのバッチリソースを取得します。結果はページ分割されます。

```
aws omics list-batch
```

次のクエリパラメータを使用して結果をフィルタリングできます。


| フィルター | 説明 | 
| --- | --- | 
| status | バッチステータスでフィルタリングします。 | 
| name | バッチ名でフィルタリングします。 | 
| runGroupId | 実行グループ ID でフィルタリングします。 | 

## 失敗した実行の処理
<a name="batch-handling-failures"></a>

バッチ処理には 2 つの異なるタイプの障害があります。違いを理解することは、トラブルシューティングに不可欠です。

### バッチレベルの障害
<a name="batch-level-failures"></a>

バッチレベルの失敗は、バッチ自体が失敗したことを意味します。実行は作成されていません (または、失敗前に作成されたものもあります）。バッチステータスは です`FAILED`。

を呼び出し**GetBatch**て `failureReason`フィールドを確認します。一般的な障害の理由は次のとおりです。


| 障害カテゴリ | `failureReason` メッセージの例 | アクション | 
| --- | --- | --- | 
| 検証エラー | 「バッチの実行数は 100001 回ですが、最大実行数は 100000 回です」、「予想される一意の runSettingIds は 50 回ですが、49 回でした」、「実行設定で無効な JSON 形式」 | 設定を修正し、新しいバッチを送信します。これらのエラーは再試行できません。 | 
| S3 設定の変更 | 「想定された s3UriConfigs のタグ: 「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"
}
```

### 実行レベルの障害
<a name="batch-run-level-failures"></a>

実行レベルの失敗は、バッチ自体が成功した (ステータスは `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 | 予期しないサービスエラーが発生しました。 | サービスは自動的に再試行されます。再試行後も持続する場合は、 サポートにお問い合わせください AWS 。 | 

**注記**  
HealthOmics は、実行ごとに一時的なエラー (`ThrottlingException`、`RequestTimeoutException`、`InternalServerException`) を自動的に再試行します。実行は、すべての再試行回数が終了した後に`FAILED`のみ としてマークされます。再試行不可能なエラー (`ValidationException`、`AccessDeniedException`、`ResourceNotFoundException`) は、再試行せずにすぐに失敗します。

**4。失敗した実行を再送信する**

修正された実行設定のみを含む新しいバッチを作成します。同じ を使用し`defaultRunSetting`、失敗した`runSettingId`エントリのみを含めます。失敗した実行の再試行メカニズムは組み込まれていないため、新しいバッチを送信する必要があります。

## バッチのキャンセル
<a name="batch-canceling"></a>

**CancelRunBatch** を使用して、進行中のバッチをキャンセルします。キャンセルオペレーション:
+ not-yet-submittedと保留中の実行の開始を防止します
+ すでに開始されている実行の**CancelRun**リクエストを送信します。

```
aws omics cancel-run-batch --batch-id {{7123456}}
```

**重要**  
キャンセルは、`PENDING`、、`SUBMITTING`または `INPROGRESS`状態のバッチでのみ許可されます。
バッチごとに 1 つのキャンセルまたは削除オペレーションのみが許可されます。
キャンセルオペレーションは非アトミックであり、部分的に成功する可能性があります。を使用して**GetBatch**、 `failedCancelSubmissionCount` で `successfulCancelSubmissionCount`と を確認します`submissionSummary`。

## バッチ実行の削除
<a name="batch-deleting-runs"></a>

**DeleteRunBatch** バッチ内の個々の実行を削除するには、 を使用します。

```
aws omics delete-run-batch --batch-id {{7123456}}
```

**重要**  
削除は、 `PROCESSED`または `CANCELLED`状態のバッチでのみ許可されます。
バッチごとに 1 つのキャンセルまたは削除オペレーションのみが許可されます。
削除オペレーションは非アトミックであり、部分的に成功する可能性があります。を使用して**GetBatch**、 `failedDeleteSubmissionCount`で `successfulDeleteSubmissionCount`と を確認します`submissionSummary`。

## バッチメタデータの削除
<a name="batch-deleting-metadata"></a>

**DeleteBatch** を使用して、バッチリソースとそれに関連するメタデータを削除します。これは とは別のオペレーションです**DeleteRunBatch**。

```
aws omics delete-batch --batch-id {{7123456}}
```

**重要**  
**DeleteBatch** では、バッチは終了状態 (`PROCESSED`、`FAILED`、`CANCELLED`、または ) である必要があります`RUNS_DELETED`。
**DeleteBatch** は個々の実行を削除しません。実行も削除する場合は、**DeleteRunBatch**最初に を使用します。
**DeleteBatch** が完了すると、バッチメタデータにアクセスできなくなります。削除されたバッチ**CancelRunBatch**では**ListRunsInBatch**、**GetBatch**、**DeleteRunBatch**、、または を呼び出すことはできません。

## バッチの EventBridge イベント
<a name="batch-eventbridge"></a>

HealthOmics は、バッチがステータスを変更するたびにイベントを Amazon EventBridge に送信します。これらのイベントを使用してワークフローを自動化できます。例えば、バッチが完了または失敗したときに通知をトリガーしたり、すべての実行が終了したときにダウンストリームパイプラインを開始したりできます。

バッチイベントは、他の HealthOmics イベントと同じイベントバスとソースを使用します。一般的なセットアップ手順については、「」を参照してください[での EventBridge の使用 AWS HealthOmics](eventbridge.md)。

### イベントの詳細タイプ
<a name="batch-event-detail-type"></a>


| イベント名 | 次の場合に発行されます。 | 
| --- | --- | 
| RunBatch ステータスの変更 | バッチが新しいステータス (CREATING、PENDING、、SUBMITTING、INPROGRESS、、STOPPING、、、RUNS\_DELETING、RUNS\_DELETED) CANCELLED PROCESSED FAILEDに移行します。 | 

### イベント詳細フィールド
<a name="batch-event-detail-fields"></a>

バッチイベントの `detail` オブジェクトには、次のフィールドが含まれます。


| フィールド | タイプ | 説明 | 
| --- | --- | --- | 
| omicsVersion | 文字列 | イベントスキーマバージョン (現在は 1.0.0)。 | 
| arn | String | バッチ ARN。 | 
| batchId | String | バッチ識別子。 | 
| status | String | 新しいバッチステータス。 | 
| uuid | String | バッチ UUID。 | 
| batchName | String | バッチ名 (指定されている場合）。 | 
| totalRuns | String | バッチ内の実行の合計数。 | 
| failureReason | String | 失敗の理由 (ステータスが の場合にのみ表示されますFAILED)。 | 
| failureMessage | String | 詳細な失敗メッセージ (ステータスが の場合にのみ表示されますFAILED)。 | 
| successfulStartSubmissionCount | String | 正常に送信された実行の数。 | 
| failedStartSubmissionCount | String | 送信に失敗した実行の数。 | 
| pendingStartSubmissionCount | String | まだ送信保留中の実行数。 | 
| pendingRunCount | String | 保留中状態の実行の数。 | 
| startingRunCount | String | 開始する実行の数。 | 
| runningRunCount | String | 現在実行中の実行数。 | 
| stoppingRunCount | String | 停止中の実行の数。 | 
| completedRunCount | String | 完了した実行の数。 | 
| failedRunCount | String | 失敗した実行の数。 | 
| cancelledRunCount | String | キャンセルされた実行の数。 | 
| deletedRunCount | String | 削除された実行の数。 | 
| workflowId | String | ワークフロー識別子。 | 
| workflowArn | String | ワークフロー ARN。 | 
| workflowVersionArn | String | ワークフローバージョン ARN (該当する場合）。 | 
| workflowOwnerId | String | ワークフロー所有者アカウント ID (共有ワークフローの場合）。 | 
| runCache | String | 実行キャッシュ ARN (該当する場合）。 | 
| runCacheBehavior | String | キャッシュ実行動作 (該当する場合）。 | 

### イベント例
<a name="batch-event-examples"></a>

**例: バッチ完了イベント**

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

## 制約事項と考慮事項
<a name="batch-limitations"></a>
+ **共有スループットクォータ** — バッチオペレーションは、個々の API のクォータと同じアカウントごとのクォータを共有します。 は**StartRun**サービスクォータを**StartRunBatch**消費します。 **CancelRun** はクォータを**CancelRunBatch**消費し、 **DeleteRun** はクォータ**DeleteRunBatch**を消費します。大きなバッチの進行中に個々の実行 APIs を呼び出すことは避けてください。送信が失敗する可能性があります。
+ **段階的な送信** — バッチ内の実行は、スループットクォータに従って段階的かつ非同期的に送信されます。
+ **非アトミックオペレーション** — **StartRunBatch**、**CancelRunBatch**、および はすべて部分的に成功**DeleteRunBatch**できます。送信の概要を必ずチェックして、再試行が必要な実行を特定します。
+ **結果整合性** — での実行実行ステータスの数は、実際の実行ステータスよりも遅れる**GetBatch**可能性があります。バッチが に達すると、最終カウントが正確になります`PROCESSED`。
+ **リスト呼び出しごとに 1 つのフィルター** — **ListRunsInBatch**および は、API 呼び出しごとに 1 つのフィルターのみ**ListBatch**をサポートします。
+ **再実行はサポートされていません** — `runId` (再実行) フィールドは ではサポートされていません**StartRunBatch**。バッチ送信ごとに、常に新しい実行が作成されます。
+ **Ready2Run ワークフロー** — バッチ実行は Ready2Run ワークフローではサポートされていません。
+ **インライン設定の制限** — インライン設定 (`inlineSettings`) は最大 100 エントリをサポートします。大きなバッチの場合は、 を使用します`s3UriSettings`。この制限は調整できません。
+ **S3 設定ファイル** — S3 設定ファイルは、実行設定オブジェクトの JSON 配列である必要があります。最大ファイルサイズは 6 GB で、最大 100,000 個の実行設定をサポートします。
+ **S3 ファイルのイミュータビリティ** — バッチの送信後に S3 設定ファイルを変更しないでください。HealthOmics は、送信中にファイルのエンティティタグ (ETag) を検証し、ファイルが変更されるとバッチに失敗します。