Start an export job

📘

When exporting a file from the Platform to an attached volume, export is possible only to a volume that is in the same location (cloud provider and region) as the project from which the file is being exported.

This call lets you queue a job to export a file from a project on the Platform into a volume. The file selected for export must not be a public file or an alias. Aliases are objects stored in your cloud storage bucket which have been made available on the Platform. The volume you are exporting to must be configured for read-write access. To do this, set the access_mode parameter to RW when creating or modifying a volume.

Essentially, the call writes to your cloud storage bucket via the volume. If this call is successful, the original project file will become an alias to the newly exported object on the volume. The source file will be deleted from the Platform and, if no more copies of this file exist, it will no longer count towards your total storage price on the Platform. In summary, once you export a file from the Platform to a volume, it is no longer part of the storage on the Platform and cannot be exported again.

If you want to export multiple files, the recommended way is to do it in bulk considering the API rate limit (learn more).

Learn more about using the Volumes API for Amazon S3.

Request

https://api.sbgenomics.com/v2/storage/exports
https://eu-api.sbgenomics.com/v2/storage/exports

Example request (normal)

POST /v2/storage/exports HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/json
curl --data '@export.json' -X POST -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" -H "Content-Type: application/json" 'https://api.sbgenomics.com/v2/storage/exports'
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

# send POST request to SB API
export = api.exports.submit_export(
    file='58bf04c81c94ccab8329da13',
    volume='rfranklin/output',
    location='output.vcf'
)

print(export.id, export.state)

Header Fields

Key

Description of value

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-type
required

application/json

Query parameters

Key

Data type of value

Description

copy_only

Boolean

If true, file will be copied to a volume but source file will remain on the Platform.

Request body

In the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table.

Key

Data type of value

Description of value

source
required

Object

This object should describe the source from which the file should be exported.

file
required

String

The ID of the file for export.

destination
required

Object

This object should describe the destination to which the file will be exported.

volume
required

String

The ID of the volume to which the file will be exported.

location
required

String

Volume-specific location to which the file will be exported. This location should be recognizable to the underlying cloud service as a valid key or path to a new file.

Please note that if this volume has been configured with a prefix parameter, the value of prefix will be prepended to location before attempting to create the file on the volume.

properties

Object

Service-specific properties of the export.

These values override the defaults from the volume.

sse_algorithm

String

S3 server-side encryption to use when exporting to this bucket.

Supported values:

  • AES256 (SSE-S3 encryption)
  • 'aws:kms`
  • null (no server-side encryption).

default: AES256

sse_aws_kms_key_id

applies to type: s3

String

If AWS KMS encryption is used, this should be set to the required KMS key. If not set and aws:kms is set as sse_algorithm, default KMS key is used.

aws_canned_acl

String

S3 canned ACL to apply on the object on during export.

Supported values:

default: null

overwrite

Boolean

If true and a file exists in the given location on the volume (respecting volume prefix if given), the API will attempt to delete the existing file on the volume before exporting.

default: false

Example request body (normal)

{
  "destination":{ 
    "volume":"rfranklin/output",
    "location":"output.vcf"
 },
  "source":{
      "file":"58bf04c81c94ccab8329da13"
  },
  "overwrite":false
}

Example request

This request exports a copy of the file to your cloud storage bucket without deleting the source file from the Platform. Note that this version of the request uses the Advance Access copy_only parameter described above.
POST /v2/storage/exports?copy_only=true HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
from sevenbridges import Api

# set advance_access flag because of parameter 'copy_only' from below
api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74',
          advance_access=True)

# send POST request to SB API
new_export = api.exports.submit_export(
    file='58bf04c81c94ccab8329da13',
    volume='rfranklin/output',
    location='output.vcf',
    copy_only=True
)

print(new_export.id, new_export.state)

Example request body

{
  "destination":{ 
    "volume":"rfranklin/output",
    "location":"output.vcf"
 },
  "source":{
      "file":"58bf04c81c94ccab8329da13"
  },
  "overwrite":false
}

Response

See a list of Seven Bridges Platform-specific response codes that may be contained in the body of the response.

Response body

The response object contains information about the status of the export job. The information is structured using the following key-value pairs:

Key

Data type of value

Description of value

id

String

ID of this export job

state

String

The state of this export job. Possible values are:

  • PENDING: the export is queued
  • RUNNING: the export is running
  • COMPLETED: the export has completed successfully
  • FAILED: the export has failed

source

Object

Export source, as passed when this job was started.

destination

Object

Export destination, as passed when this job was started.

result

Object

File object that was exported.

error

Object

In case of error in the export job, standard API error is returned here.

Example response body

{
  "href": "https://api.sbgenomics.com/v2/storage/exports/2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn",
  "id": "2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn",
  "state": "PENDING",
  "source": {
    "file": "58bf04c81c94ccab8329da13"
  },
  "destination": {
    "volume": "rfranklin/output",
    "location": "output.vcf"
  },
  "started_on": "2016-06-15T19:17:39Z",
  "properties": {
    "sse_algorithm": "AES256"
  },
  "overwrite": false
}