Amazon Omics

You can create a run cache to save the task outputs from completed tasks in a run for a private workflow. Subsequent runs use the task outputs from the cache, rather than computing the task outputs again. You specify an Amazon S3 location where HealthOmics saves the cached data. This data must be immediately accessible (not in an archived state).

For more information, see Creating a run cache in the AWS HealthOmics User Guide.

See also: AWS API Documentation

Request Syntax

client.create_run_cache(
    cacheBehavior='CACHE_ON_FAILURE'|'CACHE_ALWAYS',
    cacheS3Location='string',
    description='string',
    name='string',
    requestId='string',
    tags={
        'string': 'string'
    },
    cacheBucketOwnerId='string'
)

type cacheBehavior:

string

param cacheBehavior:

Default cache behavior for runs that use this cache. Supported values are:

CACHE_ON_FAILURE: Caches task outputs from completed tasks for runs that fail. This setting is useful if you're debugging a workflow that fails after several tasks completed successfully. The subsequent run uses the cache outputs for previously-completed tasks if the task definition, inputs, and container in ECR are identical to the prior run.

CACHE_ALWAYS: Caches task outputs from completed tasks for all runs. This setting is useful in development mode, but do not use it in a production setting.

If you don't specify a value, the default behavior is CACHE_ON_FAILURE. When you start a run that uses this cache, you can override the default cache behavior.

For more information, see Run cache behavior in the AWS HealthOmics User Guide.

type cacheS3Location:

string

param cacheS3Location:

[REQUIRED]

Specify the S3 location for storing the cached task outputs. This data must be immediately accessible (not in an archived state).

type description:

string

param description:

Enter a description of the run cache.

type name:

string

param name:

Enter a user-friendly name for the run cache.

type requestId:

string

param requestId:

[REQUIRED]

A unique request token, to ensure idempotency. If you don't specify a token, HealthOmics automatically generates a universally unique identifier (UUID) for the request.

This field is autopopulated if not provided.

type tags:

dict

param tags:

Specify one or more tags to associate with this run cache.

• (string) --

  • (string) --

type cacheBucketOwnerId:

string

param cacheBucketOwnerId:

The AWS account ID of the expected owner of the S3 bucket for the run cache. If not provided, your account ID is set as the owner of the bucket.

rtype:

dict

returns:

Response Syntax

{
    'arn': 'string',
    'id': 'string',
    'status': 'ACTIVE'|'DELETED'|'FAILED',
    'tags': {
        'string': 'string'
    }
}

Response Structure

• (dict) --

  • arn (string) --

    Unique resource identifier for the run cache.

  • id (string) --

    Identifier for the run cache.

  • status (string) --

    Run cache status.

  • tags (dict) --

    The tags associated with this run cache.

    • (string) --

      • (string) --

Retrieve the details for the specified run cache.

For more information, see Call caching for HealthOmics runs in the AWS HealthOmics User Guide.

See also: AWS API Documentation

Request Syntax

client.get_run_cache(
    id='string'
)

type id:

string

param id:

[REQUIRED]

The identifier of the run cache to retrieve.

rtype:

dict

returns:

Response Syntax

{
    'arn': 'string',
    'cacheBehavior': 'CACHE_ON_FAILURE'|'CACHE_ALWAYS',
    'cacheBucketOwnerId': 'string',
    'cacheS3Uri': 'string',
    'creationTime': datetime(2015, 1, 1),
    'description': 'string',
    'id': 'string',
    'name': 'string',
    'status': 'ACTIVE'|'DELETED'|'FAILED',
    'tags': {
        'string': 'string'
    }
}

Response Structure

• (dict) --

  • arn (string) --

    Unique resource identifier for the run cache.

  • cacheBehavior (string) --

    The default cache behavior for runs using this cache.

  • cacheBucketOwnerId (string) --

    The identifier of the bucket owner.

  • cacheS3Uri (string) --

    The S3 URI where the cache data is stored.

  • creationTime (datetime) --

    Creation time of the run cache (an ISO 8601 formatted string).

  • description (string) --

    The run cache description.

  • id (string) --

    The run cache ID.

  • name (string) --

    The run cache name.

  • status (string) --

    The run cache status.

  • tags (dict) --

    The tags associated with the run cache.

    • (string) --

      • (string) --

Delete a run cache. This action removes the cache metadata stored in the service account, but doesn't delete the data in Amazon S3. You can access the cache data in Amazon S3, for inspection or to troubleshoot issues. You can remove old cache data using standard S3 Delete operations.

For more information, see Deleting a run cache in the AWS HealthOmics User Guide.

See also: AWS API Documentation

Request Syntax

client.delete_run_cache(
    id='string'
)

type id:

string

param id:

[REQUIRED]

Run cache identifier for the cache you want to delete.

returns:

None

Retrieves a list of your run caches.

See also: AWS API Documentation

Request Syntax

client.list_run_caches(
    maxResults=123,
    startingToken='string'
)

type maxResults:

integer

param maxResults:

The maximum number of results to return.

type startingToken:

string

param startingToken:

Optional pagination token returned from a prior call to the ListRunCaches API operation.

rtype:

dict

returns:

Response Syntax

{
    'items': [
        {
            'arn': 'string',
            'cacheBehavior': 'CACHE_ON_FAILURE'|'CACHE_ALWAYS',
            'cacheS3Uri': 'string',
            'creationTime': datetime(2015, 1, 1),
            'id': 'string',
            'name': 'string',
            'status': 'ACTIVE'|'DELETED'|'FAILED'
        },
    ],
    'nextToken': 'string'
}

Response Structure

• (dict) --

  • items (list) --

    Details about each run cache in the response.

    • (dict) --

      List entry for one run cache.

      • arn (string) --

        Unique resource identifier for the run cache.

      • cacheBehavior (string) --

        Default cache behavior for the run cache.

      • cacheS3Uri (string) --

        The S3 uri for the run cache data.

      • creationTime (datetime) --

        The time that this run cache was created (an ISO 8601 formatted string).

      • id (string) --

        The identifier for this run cache.

      • name (string) --

        The name of the run cache.

      • status (string) --

        The run cache status.

  • nextToken (string) --

    Pagination token to retrieve additional run caches. If the response does not have a ``nextToken``value, you have reached to the end of the list.

Update a run cache.

See also: AWS API Documentation

Request Syntax

client.update_run_cache(
    cacheBehavior='CACHE_ON_FAILURE'|'CACHE_ALWAYS',
    description='string',
    id='string',
    name='string'
)

type cacheBehavior:

string

param cacheBehavior:

Update the default run cache behavior.

type description:

string

param description:

Update the run cache description.

type id:

string

param id:

[REQUIRED]

The identifier of the run cache you want to update.

type name:

string

param name:

Update the name of the run cache.

returns:

None

{'cacheBehavior': 'CACHE_ON_FAILURE | CACHE_ALWAYS',
 'cacheId': 'string',
 'engineVersion': 'string'}

Gets information about a workflow run.

If a workflow is shared with you, you cannot export information about the run.

HealthOmics stores a fixed number of runs that are available to the console and API. If GetRun doesn't return the requested run, you can find run logs for all runs in the CloudWatch logs. For more information about viewing the run logs, see CloudWatch logs in the AWS HealthOmics User Guide.

See also: AWS API Documentation

Request Syntax

client.get_run(
    id='string',
    export=[
        'DEFINITION',
    ]
)

type id:

string

param id:

[REQUIRED]

The run's ID.

type export:

list

param export:

The run's export format.

• (string) --

rtype:

dict

returns:

Response Syntax

{
    'arn': 'string',
    'id': 'string',
    'cacheId': 'string',
    'cacheBehavior': 'CACHE_ON_FAILURE'|'CACHE_ALWAYS',
    'engineVersion': 'string',
    'status': 'PENDING'|'STARTING'|'RUNNING'|'STOPPING'|'COMPLETED'|'DELETED'|'CANCELLED'|'FAILED',
    'workflowId': 'string',
    'workflowType': 'PRIVATE'|'READY2RUN',
    'runId': 'string',
    'roleArn': 'string',
    'name': 'string',
    'runGroupId': 'string',
    'priority': 123,
    'definition': 'string',
    'digest': 'string',
    'parameters': {...}|[...]|123|123.4|'string'|True|None,
    'storageCapacity': 123,
    'outputUri': 'string',
    'logLevel': 'OFF'|'FATAL'|'ERROR'|'ALL',
    'resourceDigests': {
        'string': 'string'
    },
    'startedBy': 'string',
    'creationTime': datetime(2015, 1, 1),
    'startTime': datetime(2015, 1, 1),
    'stopTime': datetime(2015, 1, 1),
    'statusMessage': 'string',
    'tags': {
        'string': 'string'
    },
    'accelerators': 'GPU',
    'retentionMode': 'RETAIN'|'REMOVE',
    'failureReason': 'string',
    'logLocation': {
        'engineLogStream': 'string',
        'runLogStream': 'string'
    },
    'uuid': 'string',
    'runOutputUri': 'string',
    'storageType': 'STATIC'|'DYNAMIC',
    'workflowOwnerId': 'string'
}

Response Structure

• (dict) --

  • arn (string) --

    The run's ARN.

  • id (string) --

    The run's ID.

  • cacheId (string) --

    The run cache associated with the run.

  • cacheBehavior (string) --

    The run cache behavior for the run.

  • engineVersion (string) --

    The workflow engine version.

  • status (string) --

    The run's status.

  • workflowId (string) --

    The run's workflow ID.

  • workflowType (string) --

    The run's workflow type.

  • runId (string) --

    The run's ID.

  • roleArn (string) --

    The run's service role ARN.

  • name (string) --

    The run's name.

  • runGroupId (string) --

    The run's group ID.

  • priority (integer) --

    The run's priority.

  • definition (string) --

    The run's definition.

  • digest (string) --

    The run's digest.

  • parameters (:ref:`document<document>`) --

    The run's parameters.

  • storageCapacity (integer) --

    The run's storage capacity in gibibytes. For dynamic storage, after the run has completed, this value is the maximum amount of storage used during the run.

  • outputUri (string) --

    The run's output URI.

  • logLevel (string) --

    The run's log level.

  • resourceDigests (dict) --

    The run's resource digests.

    • (string) --

      • (string) --

  • startedBy (string) --

    Who started the run.

  • creationTime (datetime) --

    When the run was created.

  • startTime (datetime) --

    When the run started.

  • stopTime (datetime) --

    The run's stop time.

  • statusMessage (string) --

    The run's status message.

  • tags (dict) --

    The run's tags.

    • (string) --

      • (string) --

  • accelerators (string) --

    The computational accelerator used to run the workflow.

  • retentionMode (string) --

    The run's retention mode.

  • failureReason (string) --

    The reason a run has failed.

  • logLocation (dict) --

    The location of the run log.

    • engineLogStream (string) --

      The log stream ARN for the engine log.

    • runLogStream (string) --

      The log stream ARN for the run log.

  • uuid (string) --

    The universally unique identifier for a run.

  • runOutputUri (string) --

    The destination for workflow outputs.

  • storageType (string) --

    The run's storage type.

  • workflowOwnerId (string) --

    The ID of the workflow owner.

{'cacheHit': 'boolean', 'cacheS3Uri': 'string'}

Gets information about a workflow run task.

See also: AWS API Documentation

Request Syntax

client.get_run_task(
    id='string',
    taskId='string'
)

type id:

string

param id:

[REQUIRED]

The workflow run ID.

type taskId:

string

param taskId:

[REQUIRED]

The task's ID.

rtype:

dict

returns:

Response Syntax

{
    'taskId': 'string',
    'status': 'PENDING'|'STARTING'|'RUNNING'|'STOPPING'|'COMPLETED'|'CANCELLED'|'FAILED',
    'name': 'string',
    'cpus': 123,
    'cacheHit': True|False,
    'cacheS3Uri': 'string',
    'memory': 123,
    'creationTime': datetime(2015, 1, 1),
    'startTime': datetime(2015, 1, 1),
    'stopTime': datetime(2015, 1, 1),
    'statusMessage': 'string',
    'logStream': 'string',
    'gpus': 123,
    'instanceType': 'string',
    'failureReason': 'string'
}

Response Structure

• (dict) --

  • taskId (string) --

    The task's ID.

  • status (string) --

    The task's status.

  • name (string) --

    The task's name.

  • cpus (integer) --

    The task's CPU usage.

  • cacheHit (boolean) --

    Set to true if AWS HealthOmics found a matching entry in the run cache for this task.

  • cacheS3Uri (string) --

    The S3 URI of the cache location.

  • memory (integer) --

    The task's memory use in gigabytes.

  • creationTime (datetime) --

    When the task was created.

  • startTime (datetime) --

    The task's start time.

  • stopTime (datetime) --

    The task's stop time.

  • statusMessage (string) --

    The task's status message.

  • logStream (string) --

    The task's log stream.

  • gpus (integer) --

    The number of Graphics Processing Units (GPU) specified in the task.

  • instanceType (string) --

    The instance type for a task.

  • failureReason (string) --

    The reason a task has failed.

{'items': {'cacheHit': 'boolean', 'cacheS3Uri': 'string'}}

Retrieves a list of tasks for a run.

See also: AWS API Documentation

Request Syntax

client.list_run_tasks(
    id='string',
    status='PENDING'|'STARTING'|'RUNNING'|'STOPPING'|'COMPLETED'|'CANCELLED'|'FAILED',
    startingToken='string',
    maxResults=123
)

type id:

string

param id:

[REQUIRED]

The run's ID.

type status:

string

param status:

Filter the list by status.

type startingToken:

string

param startingToken:

Specify the pagination token from a previous request to retrieve the next page of results.

type maxResults:

integer

param maxResults:

The maximum number of run tasks to return in one page of results.

rtype:

dict

returns:

Response Syntax

{
    'items': [
        {
            'taskId': 'string',
            'status': 'PENDING'|'STARTING'|'RUNNING'|'STOPPING'|'COMPLETED'|'CANCELLED'|'FAILED',
            'name': 'string',
            'cpus': 123,
            'cacheHit': True|False,
            'cacheS3Uri': 'string',
            'memory': 123,
            'creationTime': datetime(2015, 1, 1),
            'startTime': datetime(2015, 1, 1),
            'stopTime': datetime(2015, 1, 1),
            'gpus': 123,
            'instanceType': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

• (dict) --

  • items (list) --

    A list of tasks.

    • (dict) --

      A workflow run task.

      • taskId (string) --

        The task's ID.

      • status (string) --

        The task's status.

      • name (string) --

        The task's name.

      • cpus (integer) --

        The task's CPU count.

      • cacheHit (boolean) --

        Set to true if AWS HealthOmics found a matching entry in the run cache for this task.

      • cacheS3Uri (string) --

        The S3 URI of the cache location.

      • memory (integer) --

        The task's memory use in gigabyes.

      • creationTime (datetime) --

        When the task was created.

      • startTime (datetime) --

        When the task started.

      • stopTime (datetime) --

        When the task stopped.

      • gpus (integer) --

        The number of Graphics Processing Units (GPU) specified for the task.

      • instanceType (string) --

        The instance type for a task.

  • nextToken (string) --

    A pagination token that's included if more results are available.

{'cacheBehavior': 'CACHE_ON_FAILURE | CACHE_ALWAYS', 'cacheId': 'string'}

Starts a workflow run. To duplicate a run, specify the run's ID and a role ARN. The remaining parameters are copied from the previous run.

StartRun will not support re-run for a workflow that is shared with you.

HealthOmics stores a fixed number of runs that are available to the console and API. By default, HealthOmics doesn't any remove any runs. If HealthOmics reaches the maximum number of runs, you must manually remove runs. To have older runs removed automatically, set the retention mode to REMOVE.

By default, the run uses STATIC storage. For STATIC storage, set the storageCapacity field. You can set the storage type to DYNAMIC. You do not set storageCapacity, because HealthOmics dynamically scales the storage up or down as required. For more information about static and dynamic storage, see Running workflows in the AWS HealthOmics User Guide.

See also: AWS API Documentation

Request Syntax

client.start_run(
    workflowId='string',
    workflowType='PRIVATE'|'READY2RUN',
    runId='string',
    roleArn='string',
    name='string',
    cacheId='string',
    cacheBehavior='CACHE_ON_FAILURE'|'CACHE_ALWAYS',
    runGroupId='string',
    priority=123,
    parameters={...}|[...]|123|123.4|'string'|True|None,
    storageCapacity=123,
    outputUri='string',
    logLevel='OFF'|'FATAL'|'ERROR'|'ALL',
    tags={
        'string': 'string'
    },
    requestId='string',
    retentionMode='RETAIN'|'REMOVE',
    storageType='STATIC'|'DYNAMIC',
    workflowOwnerId='string'
)

type workflowId:

string

param workflowId:

The run's workflow ID.

type workflowType:

string

param workflowType:

The run's workflow type.

type runId:

string

param runId:

The ID of a run to duplicate.

type roleArn:

string

param roleArn:

[REQUIRED]

A service role for the run.

type name:

string

param name:

A name for the run.

type cacheId:

string

param cacheId:

Identifier of the cache associated with this run. If you don't specify a cache ID, no task outputs are cached for this run.

type cacheBehavior:

string

param cacheBehavior:

The cache behavior for the run. You specify this value if you want to override the default behavior for the cache. You had set the default value when you created the cache. For more information, see Run cache behavior in the AWS HealthOmics User Guide.

type runGroupId:

string

param runGroupId:

The run's group ID.

type priority:

integer

param priority:

A priority for the run.

type parameters:

:ref:`document<document>`

param parameters:

Parameters for the run.

type storageCapacity:

integer

param storageCapacity:

A storage capacity for the run in gibibytes. This field is not required if the storage type is dynamic (the system ignores any value that you enter).

type outputUri:

string

param outputUri:

An output URI for the run.

type logLevel:

string

param logLevel:

A log level for the run.

type tags:

dict

param tags:

Tags for the run.

• (string) --

  • (string) --

type requestId:

string

param requestId:

[REQUIRED]

To ensure that requests don't run multiple times, specify a unique ID for each request.

This field is autopopulated if not provided.

type retentionMode:

string

param retentionMode:

The retention mode for the run. The default value is RETAIN.

HealthOmics stores a fixed number of runs that are available to the console and API. In the default mode (RETAIN), you need to remove runs manually when the number of run exceeds the maximum. If you set the retention mode to REMOVE, HealthOmics automatically removes runs (that have mode set to REMOVE) when the number of run exceeds the maximum. All run logs are available in CloudWatch logs, if you need information about a run that is no longer available to the API.

For more information about retention mode, see Specifying run retention mode in the AWS HealthOmics User Guide.

type storageType:

string

param storageType:

The run's storage type. By default, the run uses STATIC storage type, which allocates a fixed amount of storage. If you set the storage type to DYNAMIC, HealthOmics dynamically scales the storage up or down, based on file system utilization.

type workflowOwnerId:

string

param workflowOwnerId:

The ID of the workflow owner.

rtype:

dict

returns:

Response Syntax

{
    'arn': 'string',
    'id': 'string',
    'status': 'PENDING'|'STARTING'|'RUNNING'|'STOPPING'|'COMPLETED'|'DELETED'|'CANCELLED'|'FAILED',
    'tags': {
        'string': 'string'
    },
    'uuid': 'string',
    'runOutputUri': 'string'
}

Response Structure

• (dict) --

  • arn (string) --

    Unique resource identifier for the run.

  • id (string) --

    The run's ID.

  • status (string) --

    The run's status.

  • tags (dict) --

    The run's tags.

    • (string) --

      • (string) --

  • uuid (string) --

    The universally unique identifier for a run.

  • runOutputUri (string) --

    The destination for workflow outputs.