Start an export job

📘
When exporting a file from the CGC 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 CGC 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 CGC. 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 CGC and, if no more copies of this file exist, it will no longer count towards your total storage price on the CGC. In summary, once you export a file from the CGC to a volume, it is no longer part of the storage on the CGC and cannot be exported again.

Learn more about using the Volumes API for Amazon S3 and Google Cloud Storage.

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

Request

Header Fields

Key	Description of value
`X-SBG-Auth-Token` required	Your CGC 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); 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: any one of S3 canned ACLs; `null` (do not apply canned ACLs). 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 (normal)

POST /v2/storage/exports HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74
Content-Type: application/json

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

Example request (Advance Access - copy file only)

POST /v2/storage/exports?copy_only=true HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

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

Response

See a list of CGC-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 by the call to Start an export job.
`destination`	Object	Export destination, as passed when this job was started by the call to Start an export job.
`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://cgc-api.sbgenomics.com/v2/storage/exports/Yrand0mERJY4F3grand0mzh5UuTdw2Ap",
  "id": "Yrand0mERJY4F3grand0mzh5UuTdw2Ap",
  "state": "PENDING",
  "source": {
    "file": "567890abc9b0307bc0414164"
  },
  "destination": {
    "volume": "rfranklin/output",
    "location": "output.vcf"
  },
  "started_on": "2016-06-15T19:17:39Z",
  "properties": {
    "sse_algorithm": "AES256"
  },
  "overwrite": false
}