SDK Rust OUTSCALE

Le SDK Rust OUTSCALE permet d’interagir avec l’API OUTSCALE dans les environnements de développement Rust. Il utilise l’édition 2021 de Rust et apporte :

  • Un client API pensé pour Rust, généré à partir de la définition OpenAPI de 3DS OUTSCALE.

  • Un client HTTP construit à partir de reqwest avec backend TLS configurable (rustls-tls ou native-tls).

  • Des modèles fortement typés pour les ressources OUTSCALE.

Pour utiliser le SDK Rust OUTSCALE, assurez-vous d’avoir les éléments suivants :

  • Un compte OUTSCALE pour accéder à l’API OUTSCALE.

  • Des access keys valides. Pour en savoir plus, voir À propos des access keys.

  • Un accès réseau aux endpoints de l’API OUTSCALE pour les Régions souhaitées.

Installation

Avant de commencer : Assurez-vous qu’une toolchain Rust fonctionnelle (édition 2021 de Rust, stable) et Cargo sont installés sur votre machine.

Installez le SDK Rust OUTSCALE à partir de la crate Cargo en lançant la commande suivante dans votre terminal :

$ cargo add outscale_api

Vous pouvez aussi ajouter manuellement la crate à votre fichier Cargo.toml en suivant cette syntaxe :

[dependencies]
outscale_api = "1"

Configuration de l’accès à l’API

Le SDK Rust OUTSCALE est une bibliothèque Rust. Vous devez le configurer directement dans votre code lors de l’initialisation (par exemple, via une structure de configuration ou un builder). Pour configurer l’accès à l’API OUTSCALE, vous pouvez configurer un profil dans un fichier de configuration ou définir vos access keys directement dans les variables d’environnement.

Les variables d’environnement sont prioritaires sur le fichier de configuration. Si des access keys sont définies dans les variables d’environnement, les valeurs définies dans le fichier de configuration seront écrasées.

Configurer l’accès à l’API à l’aide du fichier de configuration

Vous pouvez définir autant de profils que nécessaire dans le fichier ~/.osc/config.json en utilisant la syntaxe suivante :

Exemple de fichier de configuration
{
  "default": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  },
  "profile_1": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  },
  "profile_2": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>",
    "region": "<REGION>"
  }
}

  • Ce fichier est partagé avec les autres SDK et CLI OUTSCALE, comme octl.

  • Si vous n’avez pas encore créé le fichier ~/.osc/config.json, vous devez le créer à cette étape.

Vous pouvez choisir lequel de ces profils sert de profil par défaut en définissant son nom dans les variables d’environnement à l’aide de la commande suivante :

$ export OSC_PROFILE=<PROFILE>            # par défaut : "default"

Configurer l’accès à l’API à l’aide des variables d’environnement

Vous pouvez définir vos access keys et votre Région directement dans les variables d’environnement à l’aide des commandes suivantes :

$ export OSC_ACCESS_KEY=<ACCESS_KEY>
$ export OSC_SECRET_KEY=<SECRET_KEY>
$ export OSC_REGION=<REGION>              # par défaut : eu-west-2

Initialisation

Vous pouvez mettre en place l’accès à l’API OUTSCALE avec le profil par défaut en utilisant la syntaxe suivante :

use outscale_api::apis::profile::Profile;
use outscale_api::apis::volume_api::read_volumes;
use outscale_api::models::ReadVolumesRequest;

fn main() {
    let config = Profile::default().and_then(|p| p.try_into()).unwrap();

    // Exemple: lister les volumes
    let request = ReadVolumesRequest::new();
    if let Err(error) = read_volumes(&config, Some(request)) {
        eprintln!("Error: {:?}", error);
        std::process::exit(1);
    }
    println!("OK");
}

Vous pouvez également mettre en place l’accès à l’API OUTSCALE avec un profil précédemment configuré en utilisant la syntaxe suivante :

use outscale_api::apis::profile::ProfileBuilder;
use outscale_api::apis::volume_api::read_volumes;
use outscale_api::models::ReadVolumesRequest;

fn main() {
    let config = ProfileBuilder::from_standard_configuration(None, "profile_name")
        .and_then(|pb| pb.build().try_into())
        .unwrap();

    // Exemple: lister les volumes
    let request = ReadVolumesRequest::new();
    if let Err(error) = read_volumes(&config, Some(request)) {
        eprintln!("Error: {:?}", error);
        std::process::exit(1);
    }
    println!("OK");
}

Sélectionner le backend TLS

Le SDK Rust OUTSCALE vous permet de configurer le backend TLS du client HTTP. Par défaut, le backend TLS est rustls-tls. Vous pouvez sélectionnner native-tls qui utilise OpenSSL. Dans ce cas, vous devez désactiver les fonctionnalités par défaut pour éviter de repasser à rustls-tls.

Pour ce faire, modifier la dépendance outscale-api dans votre fichier Cargo.toml en suivant cette syntaxe :

[dependencies]
outscale_api = { version = "1", default-features = false, features = ["native-tls"] }

Travailler avec des runtimes asynchrones

Les appels du SDK sont synchrones et bloquent le thread appelant jusqu’à leur achèvement. Les appels ne doivent pas être effectués directement depuis un runtime asynchrone, car cela provoquerait une panique lorque le SDK tente de bloquer le thread. Pour éviter cela, encapsulez les appels dans tokio::task::spawn_blocking, comme dans l’exemple suivant :

use outscale_api::apis::profile::Profile;
use outscale_api::apis::vm_api::read_vms;
use outscale_api::models::ReadVmsRequest;

let config = Profile::default().and_then(|p| p.try_into()).unwrap();

let res = tokio::task::spawn_blocking(move || {
    read_vms(&config, Some(ReadVmsRequest::new()))
}).await.unwrap();

Exemples

Le répertoire d’exemples du Dépôt GitHub du SDK Rust OUTSCALE contient plusieurs exemples d’utilisation. Ces exemples vous montreront comment :

  • Mettre en place l’authentification.

  • Appeler les endpoints courants de l’API OUTSCALE.

  • Analyser les réponses et exploiter les modèles générés.

Pour accéder aux exemples sur votre machine, clonez le Dépôt GitHub du SDK Rust OUTSCALE, puis naviguez vers le répertoire osc-sdk-rust nouvellement créé, à l’aide des commandes suivantes :

$ git clone https://github.com/outscale/osc-sdk-rust.git
$ cd osc-sdk-rust

Pour lancer les exemples, vous devez d’abord définir vos access keys pour eu-west-2 dans les variables d’environnement, à l’aide des commandes suivantes :

$ export OSC_ACCESS_KEY=<ACCESS_KEY>
$ export OSC_SECRET_KEY=<SECRET_KEY>

Vous pouvez ensuite lancer l’exemple de votre choix (config_file, keypair, region, ou volume), à l’aide de la commande suivante :

$ cargo run --example <example-name>

Lire toutes les keypairs

L’exemple suivant permet de lire toutes les keypairs et renvoie le nombre total de keypairs existantes.

use outscale_api::apis::keypair_api::read_keypairs;
use outscale_api::apis::profile::Profile;
use outscale_api::models::ReadKeypairsRequest;

fn main() {
    let config = Profile::default().and_then(|p| p.try_into()).unwrap();

    print!("Reading all keypairs... ");
    let request = ReadKeypairsRequest::new();
    let response = match read_keypairs(&config, Some(request)) {
        Err(error) => {
            println!("Error: {:?}", error);
            return;
        }
        Ok(resp) => resp,
    };
    if let Some(keypairs) = response.keypairs {
        println!("OK -> there are {} keypairs", keypairs.len());
    }
}

Créer un volume

L’exemple suivant permet de créer un volume Performance de 10 Gio dans la Sous-région eu-west-2a et renvoie son ID.

use outscale_api::apis::profile::Profile;
use outscale_api::apis::volume_api::create_volume;
use outscale_api::models::CreateVolumeRequest;

fn main() {
    let config = Profile::default().and_then(|p| p.try_into()).unwrap();

    print!("Creating new volume... ");
    let mut request = CreateVolumeRequest::new("eu-west-2a".to_string());
    request.volume_type = Some("gp2".to_string());
    request.size = Some(10);
    let response = match create_volume(&config, Some(request)) {
        Err(error) => {
            eprintln!("Error: {:?}", error);
            std::process::exit(1);
        }
        Ok(resp) => resp,
    };
    let volume_id = response.volume.unwrap().volume_id.unwrap();
    println!("OK -> created volume id {}", volume_id);
}

Pages connexes

Exporter en PDF