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:

Conceitos de execução em lote

Pré-requisitos

Antes de iniciar uma execução em lote, verifique se você tem:

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

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.

Marcação e controle de acesso baseado em tags

As execuções em lote suportam tags em dois níveis:

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:

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. submissionSummaryMostra 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-generatedrunId, 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:

Você também pode fornecer os seguintes campos:

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ê ligaListRunsInBatch, 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"}'

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.

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:

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 dedefaultRunSetting.runTags, e novas chaves são adicionadas.

Exemplo de mesclagem de tags:

Submissão gradual

StartRunBatchvalida 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, consulteHealthOmics cotas de serviço.

O lote passa pelos seguintes estados durante o processamento normal:

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:

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

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.

Exemplo: Listar envios com falha

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

Cada resultado inclui:

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:

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:

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 ouPROCESSED), 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 parasubmissionSummary.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:

3. Motivos da falha no envio

A tabela a seguir lista os valores possíveis para submissionFailureReason execuções individuais:

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:

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

Excluindo execuções em lote

Use DeleteRunBatch para excluir as execuções individuais em um lote.

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

Excluindo metadados em lote

Use DeleteBatch para remover o recurso em lote e seus metadados associados. Esta é uma operação separada daDeleteRunBatch.

aws omics delete-batch --batch-id 7123456

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, consulteUsando EventBridge com AWS HealthOmics.

Tipo de detalhe do evento

Campos de detalhes do evento

O detail objeto em um evento em lote inclui os seguintes campos:

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