Configurer des règles d'interrogation

Les bibliothèques clientes Cloud pour Rust fournissent des fonctions d'assistance pour surveiller la progression des opérations de longue durée (LRO). Ces outils d'aide utilisent des règles pour configurer la fréquence d'interrogation et déterminer quelles erreurs d'interrogation sont temporaires et peuvent être relancées en toute sécurité, et lesquelles sont irrécupérables.

Deux règles contrôlent le comportement des boucles d'interrogation LRO :

  • La stratégie d'intervalle d'interrogation contrôle la durée d'attente de la boucle avant d'interroger l'état d'une LRO en cours.
  • La règle d'erreur d'interrogation contrôle la manière de gérer une erreur d'interrogation. Certaines erreurs d'interrogation sont irrécupérables, ce qui indique que l'opération s'est arrêtée ou que l'appelant n'est pas autorisé à vérifier son état. D'autres erreurs d'interrogation sont temporaires et indiquent un problème temporaire de réseau ou de service.

Vous pouvez définir chaque règle indépendamment, soit pour toutes les LRO démarrées sur un client, soit pour une requête individuelle.

Avant de commencer

Ce document utilise Cloud Storage pour illustrer la configuration de la règle d'interrogation, mais les mêmes concepts s'appliquent à tout service Google Cloud qui utilise des LRO.

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

  • Suivez les instructions de la page Premiers pas avec Rust pour configurer votre environnement de développement.
  • Suivez les instructions de la page Utiliser Cloud Storage avec Rust pour configurer un projet Google Cloud avec la facturation activée, activer l'API Cloud Storage et configurer les identifiants.
  • Créez un bucket Cloud Storage avec l'espace de noms hiérarchique activé, puis créez un dossier source à renommer. Attribuez à votre compte principal un rôle IAM (Identity and Access Management) avec l'autorisation de gérer les dossiers, par exemple Administrateur de l'espace de stockage (roles/storage.admin).

Dépendances

Ajoutez les crates requises à votre fichier Cargo.toml :

cargo add google-cloud-storage google-cloud-lro google-cloud-gax anyhow

Configurer la fréquence d'interrogation pour toutes les requêtes sur un client

Si vous utilisez la même règle d'intervalle d'interrogation pour la plupart des requêtes sur un client, configurez-la sur le compilateur de client. L'exemple suivant configure l'intervalle exponentiel entre les interrogations pour toutes les LRO démarrées par un client StorageControl :

pub async fn client_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use google_cloud_lro::Poller;
    use std::time::Duration;

    let client = StorageControl::builder()
        .with_polling_backoff_policy(
            ExponentialBackoffBuilder::new()
                .with_initial_delay(Duration::from_millis(250))
                .with_maximum_delay(Duration::from_secs(10))
                .build()?,
        )
        .build()
        .await?;

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

Sauf si vous remplacez la règle sur une requête individuelle, cette configuration s'applique à chaque LRO démarrée par le client. Dans cet exemple, la bibliothèque cliente attend 250 ms après la première interrogation et 500 ms après la seconde. Le délai double ensuite pour passer à 1 s, 2 s, 4 s et 8 s, avant d'être limité à 10 s pour toutes les interrogations ultérieures.

Configurer la fréquence d'interrogation pour une requête spécifique

Vous pouvez également configurer la fréquence d'interrogation sur un générateur de requêtes individuel, ce qui remplace toute règle d'intervalle d'interrogation au niveau du client. Intégrez RequestOptionsBuilder au champ d'application et appelez with_polling_backoff_policy sur le compilateur de requêtes :

pub async fn rpc_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use std::time::Duration;
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

    let client = StorageControl::builder().build().await?;

    let response = client
        .rename_folder()
        .with_polling_backoff_policy(
            ExponentialBackoffBuilder::new()
                .with_initial_delay(Duration::from_millis(250))
                .with_maximum_delay(Duration::from_secs(10))
                .build()?,
        )
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

Configurer des règles d'erreur d'interrogation pour toutes les requêtes sur un client

Pour contrôler les erreurs d'interrogation que la boucle réessaie et quand l'interrogation s'arrête, transmettez un type qui implémente la caractéristique PollingErrorPolicy, telle que Aip194Strict.

La règle d'erreur d'interrogation ne régit les erreurs que pendant la boucle d'attente de l'opération de longue durée. Pour gérer les erreurs temporaires lors de l'envoi de la requête initiale qui démarre l'opération de longue durée, configurez également une règle de nouvelle tentative standard sur le client :

pub async fn client_errors(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_gax::retry_policy;
    use google_cloud_gax::retry_policy::RetryPolicyExt;
    use std::time::Duration;
    use google_cloud_lro::Poller;

    let builder = StorageControl::builder().with_polling_error_policy(
        Aip194Strict
            .with_attempt_limit(100)
            .with_time_limit(Duration::from_secs(300)),
    );

    let client = builder
        .with_retry_policy(
            retry_policy::Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .build()
        .await?;

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

Configurer des règles d'erreur d'interrogation pour une requête spécifique

Pour ignorer la règle d'erreur d'interrogation pour une seule requête, intégrez RequestOptionsBuilder au champ d'application et appelez with_polling_error_policy sur le générateur de requêtes :

pub async fn rpc_errors(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_gax::retry_policy;
    use google_cloud_gax::retry_policy::RetryPolicyExt;
    use std::time::Duration;
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

    let client = StorageControl::builder()
        .with_retry_policy(
            retry_policy::Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .build()
        .await?;

    let response = client
        .rename_folder()
        .with_polling_error_policy(
            Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}