As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Batch é executado em HealthOmics
AWS HealthOmics as execuções em lote permitem que você envie várias execuções em uma única solicitação de API. Cada execução no lote compartilha uma configuração básica comum, mas pode ter entradas e parâmetros específicos de execução diferentes. As execuções em lote reduzem a sobrecarga de envio e simplificam o gerenciamento do ciclo de vida para processamento de fluxo de trabalho em grande escala.
Com execuções em lote, você pode:
+ Envie até 100.000 execuções em uma única **StartRunBatch** chamada, com uma configuração compartilhada definida uma vez e aplicada em todas as execuções.
+ Aplique substituições de parâmetros por execução para amostras individuais, incluindo nome, URI de saída, parâmetros, prioridade e tags.
+ Acompanhe o status geral do lote e o progresso do envio de execuções individuais por meio de **GetBatch** **ListRunsInBatch** e.
+ Cancele todas as execuções em um lote usando**CancelRunBatch**.
+ Exclua todas as execuções em um lote usando**DeleteRunBatch**.
+ Exclua metadados em lote com**DeleteBatch**.
**Topics**
+ [Conceitos de execução em lote](#batch-concepts)
+ [Pré-requisitos](#batch-prerequisites)
+ [Permissões do IAM para operações em lote](#batch-iam-permissions)
+ [Começando: envie seu primeiro lote](#batch-getting-started)
+ [Iniciando uma execução em lote](#batch-starting)
+ [Monitorando o progresso do lote](#batch-monitoring)
+ [Tratamento de execuções com falha](#batch-handling-failures)
+ [Cancelamento de um lote](#batch-canceling)
+ [Excluindo execuções em lote](#batch-deleting-runs)
+ [Excluindo metadados em lote](#batch-deleting-metadata)
+ [EventBridge eventos para lotes](#batch-eventbridge)
+ [Limitações e considerações](#batch-limitations)
## Conceitos de execução em lote
+ **Batch** — Uma coleção de execuções de fluxo de trabalho que compartilham uma configuração comum, gerenciada como um único recurso com seu próprio Amazon Resource Name (ARN) e status do ciclo de vida.
+ **Configuração de execução padrão** (`defaultRunSetting`) — Parâmetros do fluxo de trabalho compartilhados entre todas as execuções no lote, como ID do fluxo de trabalho, função do IAM, URI de saída e parâmetros comuns.
+ **Run-specific configuração** (`inlineSettings`ou`s3UriSettings`) — Per-run configurações que substituem ou se mesclam com a configuração de execução padrão. Cada entrada deve incluir uma única`runSettingId`.
+ **ID da configuração de execução** (`runSettingId`) — Um identificador exclusivo obrigatório fornecido pelo cliente para cada configuração de execução em um lote. Após o envio, use **ListRunsInBatch** para `runSettingId` mapear cada um para o HealthOmics-generated `runId`, permitindo rastrear qual execução foi criada a partir de qual configuração de entrada.
+ **Status do lote** — O estado geral da operação em lote. Possíveis valores:
+ `CREATING`— O lote está sendo criado.
+ `PENDING`— O lote foi criado; as configurações de execução estão sendo validadas de forma assíncrona.
+ `SUBMITTING`— Validação concluída; execuções individuais estão sendo enviadas.
+ `INPROGRESS`— Todas as submissões de corridas foram tentadas; as execuções estão sendo executadas.
+ `STOPPING`— Uma solicitação de cancelamento foi recebida; as execuções estão sendo interrompidas.
+ `CANCELLED`— O lote foi cancelado.
+ `PROCESSED`— Todas as execuções atingiram um estado terminal (concluídas, com falha ou canceladas).
+ `FAILED`— O lote em si falhou antes que as execuções pudessem ser criadas. Para mais detalhes, consulte [Batch-level fracassos](#batch-level-failures).
+ `RUNS_DELETING`— As execuções no lote estão sendo excluídas.
+ `RUNS_DELETED`— Todas as execuções no lote foram excluídas.
+ **Status** do envio — O resultado do envio de uma execução individual dentro do lote. Possíveis valores:
+ `SUCCESS`— A execução foi enviada com sucesso.
+ `FAILED`— Falha no envio da execução (por exemplo, devido a um erro de validação).
+ `CANCEL_SUCCESS`— A execução foi cancelada com sucesso.
+ `CANCEL_FAILED`— Falha no cancelamento da execução.
+ `DELETE_SUCCESS`— A execução foi excluída com sucesso.
+ `DELETE_FAILED`— Falha na exclusão da execução.
## Pré-requisitos
Antes de iniciar uma execução em lote, verifique se você tem:
+ Um fluxo de trabalho HealthOmics privado ativo. As execuções em lote não são compatíveis com os fluxos de trabalho do Ready2Run.
+ Uma função de serviço do IAM com permissões para executar HealthOmics fluxos de trabalho e acessar seus buckets do Amazon S3. Para obter detalhes, consulte [Funções de serviço para AWS HealthOmics](permissions-service.md).
+ Localizações do Amazon S3 para dados de entrada e resultados de saída.
+ Run-specific parâmetros para cada amostra ou configuração experimental.
## Permissões do IAM para operações em lote
Sua identidade do IAM deve ter permissões para a operação em lote e para a operação de execução individual subjacente. O exemplo de política a seguir concede permissões para todas as operações em lote:
```
{
"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"
}
}
}
]
}
```
**nota**
**StartRunBatch**requer autorização dupla: `omics:StartRunBatch` no recurso em lote e `omics:StartRun` nos recursos de execução, fluxo de trabalho e grupo de execução. Ambas as permissões devem ser concedidas para que o lote seja bem-sucedido.
A função de serviço do IAM transmitida `roleArn` (usada por HealthOmics para executar as execuções) exige as mesmas permissões que exige para **StartRun** chamadas individuais. Para obter detalhes, consulte [Funções de serviço para AWS HealthOmics](permissions-service.md).
### Marcação e controle de acesso baseado em tags
As execuções em lote suportam tags em dois níveis:
+ **Tags de lote** (tags na **StartRunBatch** solicitação) — aplicadas ao recurso de lote. Tag-based o controle de acesso (TBAC) é totalmente aplicado para etiquetas de lote.
+ **Tags de execução** (`runTags`em `defaultRunSetting` e por execução`runTags`) — aplicadas a recursos de execução individuais. Essas tags são mescladas usando as mesmas regras de precedência dos parâmetros.
Se você usa políticas de controle de acesso baseadas em tags, certifique-se de que sua política do IAM `omics:TagResource` inclua as `aws:TagKeys` condições `aws:RequestTag` apropriadas.
**Exemplo: restringir a criação de lotes a ambientes que não sejam de produção**
A política a seguir permite que os usuários criem lotes e execuções, mas nega a marcação de qualquer recurso com: `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"
}
}
}
]
}
```
Com esta política:
+ `tags: {"environment": "dev"}`no lote → Permitido
+ `tags: {"environment": "production"}`no lote → Negado (403)
+ `runTags: {"environment": "production"}`em `defaultRunSetting` → Negado para execuções individuais durante a criação assíncrona
## Começando: envie seu primeiro lote
O exemplo a seguir mostra o envio de um pequeno lote de duas execuções, a verificação do progresso e a análise dos resultados.
**Etapa 1: Enviar o lote**
```
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"}
}
]
}'
```
A resposta retorna uma ID de lote que você usa para todas as operações subsequentes:
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"status": "CREATING"
}
```
**Etapa 2: verificar o progresso do lote**
```
aws omics get-batch --batch-id {{7123456}}
```
Veja o progresso do `status` campo em `CREATING` → `PENDING` → `SUBMITTING` → `INPROGRESS` →`PROCESSED`. `submissionSummary`Mostra quantas execuções foram enviadas com sucesso e `runSummary` mostra o progresso da execução.
**Etapa 3: Analise as execuções individuais**
```
aws omics list-runs-in-batch --batch-id {{7123456}}
```
Cada entrada mapeia seu `runSettingId` (por exemplo,`sample-A`) para o HealthOmics-generated`runId`, para que você possa rastrear os resultados até suas amostras de entrada.
**Etapa 4: Verifique se há falhas nos envios**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
Se alguma execução falhar no envio, a resposta incluirá `submissionFailureReason` e ajudará você `submissionFailureMessage` a diagnosticar o problema.
## Iniciando uma execução em lote
Use **StartRunBatch** para enviar várias execuções com uma única solicitação. A solicitação inclui:
+ `defaultRunSetting`— Configuração compartilhada para todas as execuções no lote.
+ `batchRunSettings`— As configurações de execução individuais, fornecidas como uma das seguintes:
+ `inlineSettings`— Uma matriz de até 100 configurações específicas de execução fornecidas diretamente no corpo da solicitação.
+ `s3UriSettings`— Um URI do Amazon S3 apontando para um arquivo JSON contendo as configurações de execução. Necessário para lotes com mais de 100 execuções e suporta até 100.000 execuções.
Você também pode fornecer os seguintes campos:
+ `batchName`— Um nome opcional legível por humanos para o lote.
+ `requestId`— Um token de idempotência para evitar envios duplicados em lotes.
+ `tags`— Tags para associar ao próprio recurso em lote.
### Envie pequenos lotes com configurações de execução em linha
Forneça uma matriz de configurações específicas de execução diretamente no corpo da solicitação usando. `inlineSettings` Cada entrada deve incluir uma única `runSettingId` (obrigatória). Essa `runSettingId` é a chave para correlacionar os resultados — quando você liga**ListRunsInBatch**, cada entrada mapeia você `runSettingId` para HealthOmics-generated `runId` e. `runArn`
Você pode incluir até 100 entradas com configurações em linha.
```
{
"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"}
}
]
}'
```
### Envie grandes lotes com configurações de execução no S3
Para lotes com mais de 100 execuções, armazene suas configurações de execução em um arquivo JSON no Amazon S3 e forneça o URI usando. `s3UriSettings` O arquivo JSON deve conter uma matriz de objetos de configuração específicos de execução, cada um com um exclusivo. `runSettingId` O arquivo pode conter até 100.000 entradas.
O formato de arquivo S3 é o mesmo da `inlineSettings` matriz:
```
[
{
"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"
}
}
]
```
**Solicitação de 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"}'
```
**Importante**
A função de serviço do IAM especificada em `roleArn` deve ter acesso de leitura ao objeto Amazon S3 especificado em. `s3UriSettings` HealthOmics valida o acesso ao arquivo Amazon S3 durante a chamada síncrona da API e registra a ETag do arquivo. Se o arquivo for modificado após o envio, o lote falhará durante o processamento assíncrono.
### Resposta
Uma solicitação bem-sucedida retorna a ID do lote e o status inicial:
```
{
"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"
}
}
```
Se a validação síncrona falhar (por exemplo, um ID de fluxo de trabalho inválido ou um URI inacessível do Amazon S3), a API retornará um erro antes que qualquer execução seja enviada.
### Referência a parâmetros
A tabela a seguir mostra quais **StartRun** campos podem ser definidos por execução e quais se aplicam somente no nível do lote. Para obter descrições completas dos campos, consulte a referência **StartRun** da API.
| Campo | Batch-level (`defaultRunSetting`) | Per-run configurável () `inlineSettings` |
| --- | --- | --- |
| workflowId | Sim | Não |
| workflowType | Sim | Não |
| workflowVersionName | Sim | Não |
| workflowOwnerId | Sim | Não |
| roleArn | Sim | Não |
| storageCapacity | Sim | Não |
| storageType | Sim | Não |
| runGroupId | Sim | Não |
| logLevel | Sim | Não |
| cacheBehavior | Sim | Não |
| cacheId | Sim | Não |
| retentionMode | Sim | Não |
| networkingMode | Sim | Não |
| configurationName | Sim | Não |
| name | Sim | Sim |
| outputUri | Sim | Sim |
| parameters | Sim | Sim (mesclado) |
| priority | Sim | Sim |
| runTags | Sim | Sim (mesclado) |
| outputBucketOwnerId | Sim | Sim |
**nota**
O campo `runId` (para repetições individuais) não é suportado como entrada para**StartRunBatch**. Cada envio em lote sempre cria novas execuções, e cada execução receberá uma`runId`. Consulte [Execute novamente uma corrida em HealthOmics](rerun-a-run.md) para tentar novamente execuções individuais.
### Fusão de parâmetros
Os parâmetros de `defaultRunSetting` são mesclados com os parâmetros específicos de execução fornecidos em `inlineSettings` ou por meio de um URI do S3. Run-specific os valores têm precedência quando as chaves se sobrepõem.
**Exemplo:**
| Fonte | Parâmetros |
| --- | --- |
| defaultRunSetting | {"referenceUri": "s3://bucket/ref.fasta", "version": "v1"} |
| inlineSettingsentrada | {"inputUri": "s3://bucket/sample.fastq", "version": "v2"} |
| Resultado mesclado | {"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"} |
O mesmo comportamento de mesclagem se aplica a. `runTags` As tags especificadas na configuração por execução substituem as tags com a mesma chave de`defaultRunSetting.runTags`, e novas chaves são adicionadas.
**Exemplo de mesclagem de tags:**
| Fonte | Tags |
| --- | --- |
| defaultRunSetting.runTags | {"project": "cancer-research", "pipeline-version": "v2.1"} |
| inlineSettings[].runTags | {"patient-id": "patient001", "pipeline-version": "v3.0"} |
| Resultado mesclado (aplicado à execução) | {"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"} |
**nota**
Batch-level as tags (na **StartRunBatch** solicitação) são aplicadas somente ao próprio recurso em lote. Eles não são herdados por corridas individuais. Run-level as tags são controladas por `defaultRunSetting.runTags` e por execução`runTags`.
### Submissão gradual
**StartRunBatch**valida campos comuns de forma síncrona e retorna imediatamente com a ID e o status do lote. `CREATING` As execuções em um lote são enviadas de forma gradual e assíncrona a uma taxa controlada de acordo com suas cotas de produtividade.
Para ver a lista completa de HealthOmics cotas, consulte[HealthOmics cotas de serviço](service-quotas.md).
O lote passa pelos seguintes estados durante o processamento normal:
1. `CREATING`— O lote está sendo criado.
1. `PENDING`— Batch criado, configurações de execução sendo validadas.
1. `SUBMITTING`— Validação concluída, execuções individuais sendo enviadas.
1. `INPROGRESS`— Tentativa de envio de todas as execuções, as execuções estão sendo executadas.
1. `PROCESSED`— Todas as corridas atingiram um estado terminal.
**Importante**
O envio de execuções em lote compartilha a mesma cota de taxa de **StartRun** transferência das chamadas diretas de **StartRun** API. Se você ligar **StartRun** diretamente enquanto um lote grande está sendo processado, tanto os envios em lote quanto suas chamadas diretas competem pela mesma capacidade. Isso pode fazer com que as execuções em lote falhem com `ThrottlingException` (taxa excedida) ou que suas **StartRun** chamadas diretas sejam limitadas. O mesmo se aplica a **CancelRun** e **DeleteRun** — eles compartilham cotas de taxa de transferência com **CancelRunBatch** e **DeleteRunBatch** respectivamente.
## Monitorando o progresso do lote
### Obtenha o status do lote
Use **GetBatch** para recuperar o status geral e o progresso do envio de um lote.
```
aws omics get-batch --batch-id {{7123456}}
```
A resposta inclui:
+ `status`— Estado geral do lote.
+ `submissionSummary`— Contagens de envios bem-sucedidos e fracassados para operações de início, cancelamento e exclusão.
+ `runSummary`— Contagens de execuções em cada estado de execução. Valores possíveis:`PENDING`, `STARTING``RUNNING`,`STOPPING`,`COMPLETED`,`DELETED`,`CANCELLED`, ou `FAILED`
+ Registros de data e hora para eventos do ciclo de vida —,,,. `creationTime` `submittedTime` `processedTime` `failedTime`
**Exemplo de resposta:**
```
{
"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"
}
}
```
**nota**
Eventualmente, os resumos de execução são consistentes e podem ficar aquém dos estados reais de execução. As contagens finais são reconciliadas quando o lote atinge `PROCESSED` o status.
### A lista é executada em um lote
Use **ListRunsInBatch** para recuperar informações detalhadas de execuções individuais em um lote. Os resultados são paginados.
```
aws omics list-runs-in-batch --batch-id {{7123456}}
```
Você pode filtrar os resultados usando um dos seguintes parâmetros de consulta. Somente um filtro por chamada é suportado.
| Filtro | Description |
| --- | --- |
| submissionStatus | Filtrar por status de envio: SUCCESSFAILED,CANCEL\_SUCCESS,CANCEL\_FAILED,DELETE\_SUCCESS,, ouDELETE\_FAILED. |
| runSettingId | Recupere a execução de um ID de configuração de execução específico. |
| runId | Recupere a execução para um ID de execução específico. |
**Exemplo: Listar envios com falha**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
Cada resultado inclui:
+ `runSettingId`— O identificador fornecido pelo cliente para a configuração de execução.
+ `runId`— O identificador de HealthOmics-generated execução (vazio se o envio falhar).
+ `runArn`— O ARN completo da corrida.
+ `submissionStatus`— O resultado do envio (`SUCCESS``FAILED`,`CANCEL_SUCCESS`,`CANCEL_FAILED`,`DELETE_SUCCESS`, ou`DELETE_FAILED`).
+ `submissionFailureReason`e `submissionFailureMessage` — Detalhes se o envio falhar.
**nota**
`runSettingId`é o identificador especificado pelo cliente que você forneceu na configuração de execução. `runId`é o HealthOmics-generated identificador atribuído após o envio bem-sucedido. Se o envio falhar, `runId` está vazio.
### Listar lotes
Use **ListBatch** para recuperar todos os recursos em lote na sua conta. Os resultados são paginados.
```
aws omics list-batch
```
Você pode filtrar os resultados usando os seguintes parâmetros de consulta:
| Filtro | Description |
| --- | --- |
| status | Filtrar por status do lote. |
| name | Filtrar pelo nome do lote. |
| runGroupId | Filtrar por ID do grupo de execução. |
## Tratamento de execuções com falha
Há dois tipos distintos de falhas no processamento em lote. Entender a diferença é fundamental para a solução de problemas.
### Batch-level fracassos
Uma falha no nível do lote significa que o lote em si falhou — nenhuma execução foi criada (ou somente algumas foram criadas antes da falha). O status do lote é`FAILED`.
Ligue **GetBatch** e verifique o `failureReason` campo. Os motivos comuns de falha incluem:
| Categoria de falha | `failureReason`Mensagem de exemplo | Ação |
| --- | --- | --- |
| Erro de validação | “O lote tem 10.0001 execuções, mas 100000 execuções é o máximo. “, “Esperava 50 execuções únicas, SettingIds mas havia 49", “Formato JSON inválido nas configurações de execução” | Corrija a configuração e envie um novo lote. Esses erros não podem ser repetidos. |
| Configuração do S3 alterada | “Esperava s3 UriConfigs etag:\\" abc123\\”, mas era:\\ "def456\\”. O s3 mudou desde a chamada” UriConfigs StartRunBatch | Não modifique o arquivo S3 após o envio. Reenvie com o arquivo atual. |
| Erro de serviço transitório | “Houve um erro transitório no serviço. Repita o lote.” | Tente novamente enviando o mesmo lote novamente. Use o mesmo requestId para idempotência. |
**Exemplo: Falha no lote devido à validação**
```
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"
}
```
### Run-level fracassos
Uma falha no nível de execução significa que o lote em si foi bem-sucedido (o status é `INPROGRESS` ou`PROCESSED`), mas as execuções individuais falharam no envio. O lote continua processando outras execuções — ele não para na primeira falha.
**1. Confira o resumo da submissão**
```
aws omics get-batch --batch-id {{7123456}}
```
Olha para`submissionSummary.failedStartSubmissionCount`. Se for maior que zero, algumas execuções falharam durante o envio.
**2. Listar envios falhados**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
Cada entrada com falha inclui:
+ `runSettingId`— Qual configuração de execução falhou.
+ `submissionFailureReason`— A categoria de erro.
+ `submissionFailureMessage`— Uma mensagem de erro detalhada.
**3. Motivos da falha no envio**
A tabela a seguir lista os valores possíveis para `submissionFailureReason` execuções individuais:
| `submissionFailureReason` | Significado | Pode ser tentado novamente? |
| --- | --- | --- |
| ValidationException | Os parâmetros de execução são inválidos — por exemplo, os parâmetros não correspondem à definição do fluxo de trabalho, ao formato de URI do S3 inválido ou às violações de restrições. | Não — corrija a configuração. |
| AccessDeniedException | A função de serviço do IAM não tem permissões para acessar os recursos necessários (entradas do S3, chaves KMS, CloudWatch registros, imagens ECR). | Não — atualize a política de funções. |
| ResourceNotFoundException | Um recurso referenciado (fluxo de trabalho, grupo de execução ou cache de execução) não existe ou não está em um estado ativo. | Não — verifique os IDs dos recursos. |
| ServiceQuotaExceededException | A conta atingiu o número máximo de execuções ativas ou outra cota de serviço. | Aguarde a conclusão das execuções ou solicite um aumento de cota. |
| ConflictException | Uma operação conflitante está em andamento — por exemplo, uma tentativa de criação de execução duplicada. | Normalmente, resolve sozinho. |
| ThrottlingException | A solicitação foi limitada devido aos limites de taxa da API. | O serviço é repetido automaticamente. Se persistir após novas tentativas, reduza os envios simultâneos em lote. |
| RequestTimeoutException | O tempo limite da solicitação foi atingido durante o processamento. | O serviço é repetido automaticamente. Se persistir, verifique se há problemas posteriores. |
| InternalServerException | Ocorreu um erro de serviço inesperado. | O serviço é repetido automaticamente. Se persistir após novas tentativas, entre em contato com o Support AWS . |
**nota**
HealthOmics repete automaticamente os erros transitórios (`ThrottlingException`,`RequestTimeoutException`,`InternalServerException`) para cada execução. Uma corrida é marcada como `FAILED` somente após o esgotamento de todas as tentativas. Non-retryable erros (`ValidationException`,`AccessDeniedException`,`ResourceNotFoundException`) falham imediatamente sem novas tentativas.
**4. Reenviar execuções com falha**
Crie um novo lote contendo somente as configurações de execução corrigidas. Use o mesmo `defaultRunSetting` e inclua somente as `runSettingId` entradas que falharam. Não há mecanismo de repetição integrado para execuções com falha — você deve enviar um novo lote.
## Cancelamento de um lote
Use **CancelRunBatch** para cancelar um lote em andamento. A operação de cancelamento:
+ Impede o início de execuções ainda não enviadas e pendentes
+ Envia **CancelRun** solicitações para execuções que já foram iniciadas.
```
aws omics cancel-run-batch --batch-id {{7123456}}
```
**Importante**
O cancelamento só é permitido em lotes em `PENDING``SUBMITTING`, ou `INPROGRESS` estado.
Somente uma operação de cancelamento ou exclusão por lote é permitida por vez.
As operações de cancelamento não são atômicas e podem ser parcialmente bem-sucedidas. Use **GetBatch** para revisar `successfulCancelSubmissionCount` e `failedCancelSubmissionCount` no`submissionSummary`.
## Excluindo execuções em lote
Use **DeleteRunBatch** para excluir as execuções individuais em um lote.
```
aws omics delete-run-batch --batch-id {{7123456}}
```
**Importante**
A exclusão só é permitida em lotes em `PROCESSED` ou `CANCELLED` estado.
Somente uma operação de cancelamento ou exclusão por lote é permitida por vez.
As operações de exclusão não são atômicas e podem ser parcialmente bem-sucedidas. Use **GetBatch** para revisar `successfulDeleteSubmissionCount` e `failedDeleteSubmissionCount` no`submissionSummary`.
## Excluindo metadados em lote
Use **DeleteBatch** para remover o recurso em lote e seus metadados associados. Esta é uma operação separada da**DeleteRunBatch**.
```
aws omics delete-batch --batch-id {{7123456}}
```
**Importante**
**DeleteBatch**exige que o lote esteja em um estado terminal (`PROCESSED``FAILED`,`CANCELLED`, ou`RUNS_DELETED`).
**DeleteBatch**não exclui as execuções individuais. Use **DeleteRunBatch** primeiro se quiser remover as tiragens também.
Depois de **DeleteBatch** concluídos, os metadados do lote não estarão mais acessíveis. Você não pode ligar para **GetBatch****ListRunsInBatch**,**DeleteRunBatch**, ou **CancelRunBatch** em um lote excluído.
## EventBridge eventos para lotes
HealthOmics envia eventos para a Amazon EventBridge sempre que um lote muda de status. Você pode usar esses eventos para automatizar fluxos de trabalho, por exemplo, para acionar uma notificação quando um lote é concluído ou falhado, ou para iniciar um pipeline downstream quando todas as execuções terminarem.
Os eventos em lote usam o mesmo barramento de eventos e a mesma fonte de outros HealthOmics eventos. Para obter instruções gerais de configuração, consulte[Usando EventBridge com AWS HealthOmics](eventbridge.md).
### Tipo de detalhe do evento
| Nome do evento | Emitido quando |
| --- | --- |
| RunBatch Alteração de status | O lote faz a transição para um novo status (CREATING,PENDING,SUBMITTING,INPROGRESS,STOPPING,CANCELLED,PROCESSED, FAILEDRUNS\_DELETING,RUNS\_DELETED) |
### Campos de detalhes do evento
O `detail` objeto em um evento em lote inclui os seguintes campos:
| Campo | Tipo | Description |
| --- | --- | --- |
| omicsVersion | String | Versão do esquema de eventos (atualmente 1.0.0). |
| arn | String | O ARN do lote. |
| batchId | String | O identificador do lote. |
| status | String | O novo status do lote. |
| uuid | String | O UUID do lote. |
| batchName | String | O nome do lote (se fornecido). |
| totalRuns | String | Número total de execuções no lote. |
| failureReason | String | Motivo da falha (presente somente quando o status éFAILED). |
| failureMessage | String | Mensagem de falha detalhada (presente somente quando o status éFAILED). |
| successfulStartSubmissionCount | String | Número de execuções enviadas com sucesso. |
| failedStartSubmissionCount | String | Número de execuções que falharam no envio. |
| pendingStartSubmissionCount | String | Número de ensaios ainda pendentes de envio. |
| pendingRunCount | String | Número de execuções em estado pendente. |
| startingRunCount | String | Número de corridas iniciadas. |
| runningRunCount | String | Número de execuções em execução no momento. |
| stoppingRunCount | String | Número de corridas que estão sendo interrompidas. |
| completedRunCount | String | Número de execuções concluídas. |
| failedRunCount | String | Número de execuções com falha. |
| cancelledRunCount | String | Número de execuções canceladas. |
| deletedRunCount | String | Número de execuções excluídas. |
| workflowId | String | O identificador do fluxo de trabalho. |
| workflowArn | String | O ARN do fluxo de trabalho. |
| workflowVersionArn | String | O ARN da versão do fluxo de trabalho (se aplicável). |
| workflowOwnerId | String | O ID da conta do proprietário do fluxo de trabalho (para fluxos de trabalho compartilhados). |
| runCache | String | O ARN do cache de execução (se aplicável). |
| runCacheBehavior | String | O comportamento do cache de execução (se aplicável). |
### Exemplos de evento
**Exemplo: evento Batch concluído**
```
{
"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"
}
}
```
**Exemplo: evento Batch failed**
```
{
"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"
}
}
```
**Exemplo: EventBridge regra para conclusão de lotes**
O padrão de eventos a seguir corresponde quando qualquer lote atinge um estado terminal:
```
{
"source": ["aws.omics"],
"detail-type": ["RunBatch Status Change"],
"detail": {
"status": ["PROCESSED", "FAILED", "CANCELLED"]
}
}
```
## Limitações e considerações
+ **Cotas de taxa de transferência compartilhadas** — As operações em lote compartilham as mesmas cotas por conta que suas contrapartes individuais de API. **StartRunBatch**consome cotas **StartRun** de serviço. **CancelRunBatch**consome **CancelRun** cotas e **DeleteRunBatch** consome **DeleteRun** cotas. Evite chamar APIs de execução individuais enquanto um lote grande estiver em andamento, pois isso pode causar falhas no envio.
+ **Envio gradual** — As execuções em um lote são enviadas de forma gradual e assíncrona, de acordo com suas cotas de produtividade.
+ **Non-atomic operações** —**StartRunBatch**,**CancelRunBatch**, e todas **DeleteRunBatch** podem ser parcialmente bem-sucedidas. Sempre verifique os resumos de envio para identificar as execuções que precisam ser repetidas.
+ **Consistência eventual** — As contagens do status de execução da execução em **GetBatch** maio ficam aquém dos estados reais de execução. As contagens finais são precisas quando o lote chega`PROCESSED`.
+ **Filtro único por chamada de lista** — **ListRunsInBatch** e **ListBatch** suporta apenas um filtro por chamada de API.
+ **Re-run não suportado** — O campo `runId` (executar novamente) não é suportado no**StartRunBatch**. Cada envio em lote sempre cria novas execuções.
+ Fluxos de trabalho do **Ready2Run — As execuções em lote não são compatíveis com os fluxos** de trabalho do Ready2Run.
+ **Limite de configuração** em linha — As configurações em linha (`inlineSettings`) suportam até 100 entradas. Para lotes maiores, use`s3UriSettings`. Este limite não é ajustável.
+ Arquivo de **configuração do S3 — O arquivo** de configuração do S3 deve ser uma matriz JSON de objetos de configuração de execução. O tamanho máximo do arquivo é de 6 GB, suportando até 100.000 configurações de execução.
+ **Imutabilidade do arquivo S3** — Não modifique o arquivo de configuração do S3 depois de enviar o lote. HealthOmics valida a tag de entidade do arquivo (ETag) durante o envio e falha no lote se o arquivo tiver sido alterado.