Create a volume

This call creates a new volume. Volumes authorize the Platform to access and query objects on a specified cloud storage (Amazon Web Services or Google Cloud Storage) on your behalf.

Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage. These tutorials also detail how to configure your bucket.

Request

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

Example request

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

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

# send POST request to SB API
new_volume = api.volumes.create_s3_volume(
    name='my_s3_volume',
    bucket='input_files',
    access_key_id='AKIAIOSFODNN7EXAMPLE',
    secret_access_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    access_mode=VolumeAccessMode.READ_ONLY,
    properties={
        'sse_algorithm': 'aws:kms',
        'sse_aws_kms_key_id': 'test_kms_key_id'
    }
)

print(new_volume.name, new_volume.id)
from sevenbridges import Api, VolumeAccessMode

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

# send POST request to SB API
new_volume = api.volumes.create_google_volume(
    name='my_gcs_volume',
    bucket='output_files',
    client_email='[email protected]',
    private_key='-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEAsXj4E7svaB4s'
                'zcOrAcraSbsGnNuTU1b/4llyspDa0lltZIKL\nfl6s3QoqbjUWqAZXkJexKus'
                '55g49ULD8BGKH2r4EF+XyKcpoon4uIFcbmYcmsUXM\nJ3ujgyL5DbWnQZ6Grq'
                'gFNRFVVz/PuvTZOd6KFCrjbbtCxfKoXQrmCwFC/4NlFR3v\n1kavU81w201Mi'
                'ed3e+pxjfiQKAJOoy5I7kfuH20xfzHXWR2YHdQGbzOUZyPgmzZ6\nH6Ry39b7'
                'bgLVbyk3++e13KrsTEf58rRzUHLzlcUDcGyf8iTO2vA2qzcbrbovwqJr\n7H4'
                'ZfFllDMYQ/ISj4cmi+sz/hR43LUK86emrXwIDAQABAoIBADBr2fvAMbINsZm+'
                '\njjTh/ObrAWXgvvSZIx3F2/Z+cUW9Ioyu1ZJ3/uncMTF6iKD1ggSwbqVQIq7'
                'zKaWP\ndGNZ4sk62PEQSx8924iiNsGaIqyj5FmvuoD3SeiorR0hd+3+a67Rpw'
                'IQpaE1ht7y\nmSYh4riX7w9sbU6G44rnQ1azVG1UHvk5ieOD4OPvJopuc6D6o'
                'w1oJOnHE0k8v3HY\n1FpLdWCL6nSERqXOI5w+tllG4NMUmTZ2jhaBSEM4PIJV'
                'O+24TM3XFCcvhZ7ipPMF\nP5B8hV4hDA4Av1Ei7iuRZlJsH4sRrtHJE3/FZLg'
                'qHRRvt/7w4c1xnwirNghtTNMb\nXVoaS/ECgYEA15vL3l22mIoePlcCxIgVCA'
                'xhKm6TVQZsAE2EaeVsJKDl0AgCtn/1\nThMIPPGkO8jmjqHGgA+FhjoUQuCCd'
                'IuON00mUpmUxZlwI5+uknuK597/zAjd6W8s\n7p9apvBUDfod0hwF9Jfw+aUt'
                'Zm6EAUNR1Odbb+bpXp1luwfcesHe4QcCgYEA0rg8\nZBBwh2DetU6wWh2JIej'
                'BH5SfRUqtEwo5WiEZhrEQLazcpX4w5uvESnT+xd7qx3yC\n/vyzqmy+YwP92Q'
                'l0vZApdQoyKGHVntY/o3HYxZD3x+7BKThUs747WjdSo8SwBkSr\nxEzLBgTqq'
                'cho6UXvYTTEAg11F5yNYzbvVf4vROkCgYEAh6XtTamIB9Bd1rrHcv5q\nvPWM'
                '7DVFXGj96fLbLAS7VRAlhgyEKG2417YBqNYejb6Hz5TYXhll2F0SAkFd0hU7'
                '\nFG/lfHJDt04hz0fXfTFc4yTZqnSpqQPZMQfw8LajK2gA+v/Gf2xYn7fcKGW'
                '/h0vj\nYB9u16hfirdcGZ+Ih3MR1mECgYEAnq1b1KJIirlYm8FYrVOGe4FxRF'
                '2/ngdA05Ck\nZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzD'
                'ZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvA'
                'LJlQZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8p'
                'ZqvAL+CxZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9'
                'Vl8pZqvAL+MjZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzD'
                'ZYl9Vl8pZqvALSi0sVSXpA=\n-----END RSA PRIVATE KEY-----',
    access_mode=VolumeAccessMode.READ_WRITE,
    description='New google volume'
)

print(new_volume.name, new_volume.id)

Header Fields

Key

Description of value

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-type
required

application/json

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

Description

name
required

String

The name of the volume. It must be unique from all other volumes for this user.

access_mode

String

Signifies whether this volume should be used for read-write ("RW") or read-only ("RO") operations.

The access mode is consulted independently of the credentials granted to Seven Bridges when the volume was created, so it is possible to use a read-write credentials to register both read-write and read-only volumes using it.

default: "RW"

description

String

An optional description of this volume.

service
required

Object

This object should contain the information about the cloud service that this volume represents.

See the service object section below for an explanation of its structure.

AWS service object

Key

Data type of value

Description of value

type

string

The type of cloud service which is "s3" for Amazon Web Services.

prefix

String

A service-specific prefix to prepend to all objects created in this volume. If the service supports folders, and this prefix includes them, the API will attempt to create any missing folders when it outputs a file.

default: ""

bucket
required

String

The name of the AWS S3 bucket you wish to register as a volume.

endpoint

default: https://s3.amazonaws.com

String

Cloud provider API endpoint to use when accessing this bucket.

For a list of AWS-supported endpoints, see AWS Regions and Endpoints.

credentials    

Object

Contains credentials for the underlying cloud provider.

access_key_id

required

String

AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.

secret_access_key

String

AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.

properties

Object

Contains the properties of a specific service.

These values set the defaults for operations performed with this volume. Individual operations can override these defaults by providing a custom properties object.

sse_algorithm

String

S3 server-side encryption to use when exporting to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)

Supported values:

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

default: AES256

sse_aws_kms_key_id

String

Provide your AWS KMS ID here if you specify aws:kms as your sse_algorithm. Learn more about AWS KMS.

aws_canned_acl

S3 canned ACL to apply on the object during export.

Supported values:

default: null

GCP service object

Key

Data type

Description

type

string

The type of cloud service which is "gcs" for Google Cloud Storage.

prefix

string

A service-specific prefix to prepend to all objects created in this volume. If the service supports folders, and this prefix includes them, the API will attempt to create any missing folders when it outputs a file.

default: ""

bucket

string

The name of the GCS bucket you wish to register as a volume.

root_url

string

Cloud provider API endpoint for accessing this bucket.

credentials

object

For Google Cloud Storage, the credentials are:

client_email

string

The client email address for the Google Cloud service account to use for operations on this bucket. This can be found in the JSON containing your service account credentials.

private_key

string

Google Cloud Platform private key.

properties

object

Contains the properties of a specific service.

These values set the defaults for operations performed with this volume. Individual operations can override these defaults by providing a custom properties object.

Example request body

{
  "name": "my_s3_volume",
  "service": {
    "type": "s3",
    "bucket": "input_files",
    "prefix": "",
    "credentials": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    },
    "properties": {
     "sse_algorithm": "aws:kms",
     "sse_aws_kms_key_id":"test_kms_key_id"
    }
  },
  "access_mode": "RO"
}
{
  "name": "my_gcs_volume",
  "description": "New google volume",
  "service": {
    "type": "gcs",
    "bucket": "output_files",
    "prefix": "output",
    "credentials": {
      "client_email": "[email protected]",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEAsXj4E7svaB4szcOrAcraSbsGnNuTU1b/4llyspDa0lltZIKL\nfl5s3QoqbjUWqAZXkJexKus55g49ULD8BGKH2r4EF+XyKcpoon4uIFcbmYcmsUXM\nJ3ujgyL5DbWnQZ6GrqgFNRFVVz/PuvTZOd6KFCrjbbtCxfKoXQrmCwFC/4NlFR3v\n1kavU81w201Mied3e+pxjfiQKAJOoy5I7kfuH20xfzHXWR2YHdQGbzOUZyPgmzZ6\nH6Ry39b7bgLVbyk3++e13KrsTEf58rRzUHLzlcUDcGyf8iTO2vA2qzcbrbovwqJr\n7H4ZfFllDMYQ/ISj4cmi+sz/hR43LUK86emrXwIDAQABAoIBADBr2fvAMbINsZm+\njjTh/ObrAWXgvvSZIx3F2/Z+cUW9Ioyu1ZJ3/uncMTF6iKD1ggSwbqVQIq7zKaWP\ndGNZ4sk62PEQSx8924iiNsGaIqyj5FmvuoD3SeiorR0hd+3+a67RpwIQpaE1ht7y\nmSYh4riX7w9sbU6G44rnQ1azVG1UHvk5ieOD4OPvJopuc6D6ow1oJOnHE0k8v3HY\n1FpLdWCL6nSERqXOI5w+tllG4NMUmTZ2jhaBSEM4PIJVO+24TM3XFCcvhZ7ipPMF\nP5B8hV4hDA4Av1Ei7iuRZlJsH4sRrtHJE3/FZLgqHRRvt/7w4c1xnwirNghtTNMb\nXVoaS/ECgYEA15vL3l22mIoePlcCxIgVCAxhKm6TVQZsAE2EaeVsJKDl0AgCtn/1\nThMIPPGkO8jmjqHGgA+FhjoUQuCCdIuON00mUpmUxZlwI5+uknuK597/zAjd6W8s\n7p9apvBUDfod0hwF9Jfw+aUtZm6EAUNR1Odbb+bpXp1luwfcesHe4QcCgYEA0rg8\nZBBwh2DetU6wWh2JIejBH5SfRUqtEwo5WiEZhrEQLazcpX4w5uvESnT+xd7qx3yC\n/vyzqmy+YwP92Ql0vZApdQoyKGHVntY/o3HYxZD3x+7BKThUs747WjdSo8SwBkSr\nxEzLBgTqqcho6UXvYTTEAg11F5yNYzbvVf4vROkCgYEAh6XtTamIB9Bd1rrHcv5q\nvPWM7DVFXGj96fLbLAS7VRAlhgyEKG2417YBqNYejb6Hz5TYXhll2F0SAkFd0hU7\nFG/lfHJDt04hz0fXfTFc4yTZqnSpqQPZMQfw8LajK2gA+v/Gf2xYn7fcKGW/h0vj\nYB9u16hfirdcGZ+Ih3MR1mECgYEAnq1b1KJIirlYm8FYrVOGe4FxRF2/ngdA05Ck\nZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvALJlQZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+CxZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+MjZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvALSi0sVSXpA=\n-----END RSA PRIVATE KEY-----"
    }
  },
  "access_mode": "RW"
}

Response

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

Example response body

{
  "href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my_volume",
  "id": "rfranklin/my_volume",
  "name": "my_volume",
      "access_mode": "RO",
    "service": {
        "type": "S3",
        "bucket": "sb-demo-markot-ro",
        "prefix": "input-files",
        "endpoint": "s3.amazonaws.com",
        "credentials": {
            "access_key_id": "AKIAI32ALEL3XDGMNQ2Q"
        },
        "properties": {
            "sse_algorithm": "aws:kms",
                    "sse_aws_kms_key_id": "test_kms_key_id"
        }
    },
    "created_on": "2017-07-21T08:23:39Z",
    "modified_on": "2017-07-21T08:23:39Z",
    "active": true
}

👍

Note that you cannot view volumes that you have created via the visual interface. However, you can see all your volumes by making the call to list volumes.