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á.

O lote é executado em HealthOmics

AWS HealthOmics 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 diferentes entradas e parâmetros específicos da execução. 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 tanto para a operação em lote quanto 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 pelo HealthOmics para executar as execuções) exige as mesmas permissões que 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

O lote executa tags de suporte em dois níveis:

Se você usa políticas de controle de acesso baseadas em tags, certifique-se de que sua política de IAM omics:TagResource inclua as aws:TagKeys condições aws:RequestTag apropriadas.

Exemplo: Restringir a criação de lotes a ambientes que não são 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 essa política:

Primeiros passos: 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 revisão 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 um 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 andamento do lote

aws omics get-batch --batch-id 7123456

Veja o progresso do status campo de CREATING → PENDING → SUBMITTING → INPROGRESS →PROCESSED. submissionSummaryMostra quantas execuções foram enviadas com sucesso e runSummary mostra o progresso da execução.

Etapa 3: Revise 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: verificar 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 variedade de configurações específicas de execução diretamente no corpo da solicitação usando. inlineSettings Cada entrada deve incluir um único runSettingId (obrigatório). Essa runSettingId é a chave para correlacionar os resultados — quando você ligaListRunsInBatch, cada entrada mapeia você runSettingId para o HealthOmics-generated runId e. runArn

Você pode incluir até 100 entradas com configurações embutidas.

{
  "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 da execução, cada um com um único. runSettingId O arquivo pode conter até 100.000 entradas.

O formato de arquivo do 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 um ID de 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 do Amazon S3 inacessível), 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 da 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 de defaultRunSetting.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 um ID e status do lote. CREATING As execuções em lote são enviadas de forma gradual e assíncrona em 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

Obter status do lote

Use GetBatch para recuperar o status geral e o andamento 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 em sua conta. Os resultados são paginados.

aws omics list-batch

Você pode filtrar os resultados usando os seguintes parâmetros de consulta:

Habilitar métricas de execução

Execute um relatório de métricas quase em tempo real sobre a utilização de recursos para as execuções em um lote. Para ativar as métricas de execução, a função de serviço que você usa para o lote deve ter a cloudwatch:PutMetricData permissão. Para obter mais informações, consulte Execute métricas para fluxos de trabalho privados.

Adicione a permissão a seguir à função de serviço que você usa para o lote.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

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

OlhasubmissionSummary.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 corridas 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 embutido 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 do lote

Use DeleteBatch para remover o recurso de 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 for concluído ou falhar, 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 concluído em lote

{
  "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 de falha em lote

{
  "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 evento a seguir coincide 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