Mettre à jour une ressource à l'aide d'un masque de champ

Lorsque vous mettez à jour une ressource dans Google Cloud, vous souhaitez souvent modifier des champs spécifiques sans remplacer l'intégralité de la ressource. Les bibliothèques clientes Cloud pour Rust sont compatibles avec les masques de champ. Vous pouvez ainsi spécifier les champs qu'une opération de mise à jour modifie et laisser tous les autres champs inchangés.

Avant de commencer

Ce document utilise l'API Secret Manager, mais les mêmes concepts s'appliquent aux autres services Google Cloud .

Avant d'exécuter le code de ce document, assurez-vous de remplir les conditions préalables suivantes :

Dépendances

La caisse google-cloud-wkt fournit des types bien connus pour les API Google Cloud, y compris FieldMask. Ajoutez google-cloud-secretmanager-v1, google-cloud-wkt, anyhow et tokio à votre fichier Cargo.toml :

cargo add google-cloud-secretmanager-v1 google-cloud-wkt anyhow
cargo add tokio --features macros,rt-multi-thread

Fonctionnement des masques de champ

Un FieldMask contient un ensemble de chemins de champ symboliques qui identifient les champs qu'une opération de mise à jour modifie ou qu'une opération de lecture renvoie.

Lors d'une opération de mise à jour, le service ne modifie que les champs listés dans le masque et ignore les valeurs des champs non listés dans le message de requête. Si vous omettez le masque de champ dans une requête de mise à jour, l'opération s'applique à tous les champs modifiables.

Pour rétablir la valeur par défaut d'un champ spécifique, incluez le chemin d'accès au champ dans le masque et laissez ce champ à sa valeur par défaut dans la structure de la ressource.

Mettre à jour les champs d'une ressource

Pour créer un secret et mettre à jour de manière sélective ses champs labels et annotations à l'aide d'un FieldMask, procédez comme suit :

  1. Initialisez un client SecretManagerService et créez un secret avec des valeurs labels et annotations vides :

    let client = SecretManagerService::builder().build().await?;
    
    let secret = client
        .create_secret()
        .set_parent(format!("projects/{project_id}"))
        .set_secret_id("your-secret")
        .set_secret(
            Secret::new().set_replication(Replication::new().set_automatic(Automatic::new())),
        )
        .send()
        .await?;
    println!("CREATE = {secret:?}");

  2. Envoyez une requête update_secret qui définit labels, annotations, l'etag actuel pour empêcher l'écrasement des mises à jour simultanées, et un masque de mise à jour couvrant "annotations" et "labels" :

    let tag = |mut labels: HashMap<_, _>, msg: &str| {
        labels.insert("updated".to_string(), msg.to_string());
        labels
    };
    
    let update = client
        .update_secret()
        .set_secret(
            Secret::new()
                .set_name(&secret.name)
                .set_etag(secret.etag)
                .set_labels(tag(secret.labels, "your-label"))
                .set_annotations(tag(secret.annotations, "your-annotations")),
        )
        .set_update_mask(FieldMask::default().set_paths(["annotations", "labels"]))
        .send()
        .await?;
    println!("UPDATE = {update:?}");

    L'appel set_update_mask spécifie les chemins d'accès exacts des champs à modifier :

    .set_update_mask(FieldMask::default().set_paths(["annotations", "labels"]))

Le résultat confirme que l'opération a mis à jour les deux champs :

labels: {"updated": "your-label"},
...
annotations: {"updated": "your-annotations"},

Compléter le code

La fonction suivante combine la création de secret et la mise à jour du masque de champ :

use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::replication::Automatic;
use google_cloud_secretmanager_v1::model::{Replication, Secret};
use google_cloud_wkt::FieldMask;
use std::collections::HashMap;

pub async fn sample(project_id: &str) -> anyhow::Result<()> {
    let client = SecretManagerService::builder().build().await?;

    let secret = client
        .create_secret()
        .set_parent(format!("projects/{project_id}"))
        .set_secret_id("your-secret")
        .set_secret(
            Secret::new().set_replication(Replication::new().set_automatic(Automatic::new())),
        )
        .send()
        .await?;
    println!("CREATE = {secret:?}");

    let tag = |mut labels: HashMap<_, _>, msg: &str| {
        labels.insert("updated".to_string(), msg.to_string());
        labels
    };

    let update = client
        .update_secret()
        .set_secret(
            Secret::new()
                .set_name(&secret.name)
                .set_etag(secret.etag)
                .set_labels(tag(secret.labels, "your-label"))
                .set_annotations(tag(secret.annotations, "your-annotations")),
        )
        .set_update_mask(FieldMask::default().set_paths(["annotations", "labels"]))
        .send()
        .await?;
    println!("UPDATE = {update:?}");

    Ok(())
}

Effectuer un nettoyage

Pour éviter que des frais ne soient facturés sur votre compte Google Cloud et pour éviter les erreurs ALREADY_EXISTS lors des exécutions ultérieures, supprimez le secret your-secret lorsque vous avez terminé.