Connection to EDP hosts
connection.Rmd
TL;DR
Save into the ~/.qb/edp.json files, different EDP
configuration profiles.
The default profile is used automatically in functions
if no connection are specified in arguments.
{
"default": {
"secret": "API_TOKEN",
"host": "https://api.solvebio.com"
},
"demo-corp": {
"secret": "API_TOKEN_2",
"host": "https://demo-corp.api.solvebio.com"
}
}
# by default all functions will use the default profile set in the default config file
library(quartzbio.edp, quiet = TRUE)
User()
#> Loading required package: RcppSimdJson
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> Connected to https://vsim-dev.api.edp.aws.quartz.bio with user "Karl Forner" using an API Token
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
vlst <- Vaults()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v2/vaults...
vlst[[1]]
#> Vault "vsim-dev:dandan-test" ("", general, Rwa), @ "Dandan Xu", updated at:2023-02-13T19:13:48.825Z
flds <- Folders()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v2/objects...
flds[[1]]
#> folder "vsim-dev:Public Data Dev:/ClinGen" (application/vnd.solvebio.folder) nb:0 user:David Caplan accessed:2023-02-15T20:07:39.539Z
fis <- Files()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v2/objects...
fis[[1]]
#> file "vsim-dev:Public Data Dev:/ClinGen/ClinGen-1-0-0-2015-06-02-Genes-1098056416333778650-20230215200640.json.gz" (gzip) nb:562 user:David Caplan accessed:2023-02-15T20:07:46.945Z
das <-Datasets()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v2/objects...
das[[1]]
#> dataset "vsim-dev:Public Data Dev:/ClinGen/Genes" (application/vnd.solvebio.dataset) nb:562 user:David Caplan accessed:2023-04-18T22:23:03Z
Introduction
There are several methods to be connected to a EDP instance.
using explicit connection
using environment variables
using profiles
using autoconnect()
key: designates an API key (deprecated and will not be supported anymore in the future)
token: designates an API token
secret: can be a key or a token but token connections based are highly recommended
Connection from Profiles
Different EDP environment profiles config can be stored in the default config location of your home directory: ~/.qb/edp.json At least a single default profile should be defined as examplified above.
- the default profile witl set the default connection, if no explicit connection was specified using the environment variables.
# use the default profile
User()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
# use explicitely the default profile
conn <- connect_with_profile()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> Connected to https://vsim-dev.api.edp.aws.quartz.bio with user "Karl Forner" using an API Token
User(conn)
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
# use profile named demo-corp defined in the default config file without
# changing the current connection
conn <- connect_with_profile('demo-corp')
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> Connected to https://demo-corp.api.solvebio.com with user "Karl Forner" using an API Token
User(conn)
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> EDP user "Karl Forner"(karl.forner.prod.admin) role:member
Vaults(conn = conn)
#> GET https://demo-corp.api.solvebio.com/v2/vaults...
#> List of 3 Vaults
#> id name full_path user_name vault_type created_at
#> 1 5527 GWAS demo-corp:GWAS Joseph Henry general 2022-07-11T20:17:24.029Z
#> 2 2956 public solvebio:public SolveBio Staff general 2017-07-28T18:13:37.596Z
#> 3 6489 user-4739 demo-corp:user-4739 Karl Forner user 2023-05-30T09:50:56.085Z
# still using the default profile
# because no explicit profile connection is given in argument
vaults_df <- as.data.frame(Vaults())
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v2/vaults...
dplyr::sample_n(vaults_df[, c(4,5:8)], 4)
#> created_at default_storage_class
#> 1 2023-01-27T16:17:17.108Z NULL
#> 2 2022-11-02T23:38:43.735Z NULL
#> 3 2022-10-31T21:20:03.587Z NULL
#> 4 2023-05-18T23:36:53.859Z NULL
#> description
#> 1 This is your personal vault. The contents of your personal vault are private and cannot be accessed by others. To share items in your personal vault, please copy or move them to a shared vault.
#> 2 NULL
#> 3 NULL
#> 4 Used primarily for Repare NGS data extraction annotation
#> full_path has_children
#> 1 vsim-dev:user-51 TRUE
#> 2 quartzbio:Public TRUE
#> 3 vsim-dev:vSIM SAMPNAME TRUE
#> 4 vsim-dev:Repare TRUE
Connection From System Environment variables
If no default profile or config are available, the
environment variables EDP_PROFILE and
EDP_CONFIG are explored to obtain the profile
name.
This way several config files, containing different profiles can be used
by switching only environment variables.
Setting EDP_PROFILE to ‘default’ and EDP_CONFIG to ‘~/.qb/edp.json’ is equivalent to use the default package settings.
A good practice is to have profiles defined in the EDP_CONFIG file and to set the EDP_PROFILE environment variable at the beginning of your scripts. The remaining connections will automatically use it.
# set the demo-corp connection as the default for future connections
Sys.getenv('EDP_PROFILE')
#> [1] ""
Sys.setenv(EDP_PROFILE = 'demo-corp')
User()
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> Connected to https://demo-corp.api.solvebio.com with user "Karl Forner" using an API Token
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> EDP user "Karl Forner"(karl.forner.prod.admin) role:member
Explicit connection
secret and host can be set explicitely. read_connection returns connection infos for a given config.
conn <- read_connection_profile('default')
secret <- conn$secret
host <- conn$host
conn <- connect(secret, host)
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> Connected to https://vsim-dev.api.edp.aws.quartz.bio with user "Karl Forner" using an API Token
User(conn)
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
autoconnect()
autoconnect() function tries to connect using the environment variables EDP_PROFILE and EDP_CONFIG at first and then the default profile in the default config file.
# auto connect use the EDP profile to set the current connection
Sys.setenv(EDP_PROFILE = 'demo-corp')
conn <- autoconnect()
User(conn = conn)
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> EDP user "Karl Forner"(karl.forner.prod.admin) role:member
User()
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> EDP user "Karl Forner"(karl.forner.prod.admin) role:member
# unset the EDP_PROFILE environment variable
# autoconnect() use the default settings.
Sys.unsetenv('EDP_PROFILE') # unset current profile environment variables
set_connection(NULL) # unset current connection
conn <- autoconnect()
# Will used the default profile
User(conn=conn)
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
User()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> Connected to https://vsim-dev.api.edp.aws.quartz.bio with user "Karl Forner" using an API Token
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
Advanced Usage
set_connection() and get_connection()
So far connection objects (i.e list) were passed as arguments to
functions such as User() or Vaults().
Still theses functions can use a current connection.
By default, if no connection argument is given to these function(). The
current connection will be set to the default connection.
get_connection() returns the current connection. If none are yet available and auto=TRUE, it will use autoconnect() to obtain it and sets as the current one.
set_connection(): explicitely sets the current connection
# explicitely set the connection with a profile
set_connection( connect_with_profile('demo-corp'))
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> Connected to https://demo-corp.api.solvebio.com with user "Karl Forner" using an API Token
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> Connected to https://demo-corp.api.solvebio.com with user "Karl Forner" using an API Token
# remove the current connection
set_connection(NULL)
# the firt call to User() sets the current default connection to the default connection
# both calls will use the current connection
User()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> Connected to https://vsim-dev.api.edp.aws.quartz.bio with user "Karl Forner" using an API Token
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
User(conn = get_connection())
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
# the current connection remains the 'default'
# connecting with a profile did not change it
conn_corp <- connect_with_profile('demo-corp')
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> Connected to https://demo-corp.api.solvebio.com with user "Karl Forner" using an API Token
User(conn_corp)
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> EDP user "Karl Forner"(karl.forner.prod.admin) role:member
User()
#> GET https://vsim-dev.api.edp.aws.quartz.bio/v1/user...
#> EDP user "Karl Forner"(karl.forner.test.admin) role:member
# the current connection will be the 'demo-corp' one
# after unsetting the previous connection and profile environment variables
Sys.setenv(EDP_PROFILE = 'demo-corp')
set_connection(NULL)
User()
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> Connected to https://demo-corp.api.solvebio.com with user "Karl Forner" using an API Token
#> GET https://demo-corp.api.solvebio.com/v1/user...
#> EDP user "Karl Forner"(karl.forner.prod.admin) role:member