Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configurer les règles d'interrogation

Découvrez comment configurer des règles d'interrogation pour les opérations de longue durée. Les Google Cloud bibliothèques clientes pour Rust fournissent des fonctions d'assistance pour simplifier la surveillance de la progression des opérations de longue durée (LRO). Ces outils d'assistance utilisent des règles pour configurer la fréquence d'interrogation et déterminer quelles erreurs d'interrogation sont transitoires (et peuvent être retentées en toute sécurité) et lesquelles sont irrécupérables.

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

La règle d'intervalle exponentiel entre les tentatives d'interrogation contrôle le temps d'attente des boucles avant d'interroger l'état d'une LRO toujours en cours.
La règle d'erreur d'interrogation contrôle ce qu'il faut faire en cas d'erreur d'interrogation. Certaines erreurs d'interrogation sont irrécupérables et indiquent que l'opération a été abandonnée ou que l'appelant n'est pas autorisé à vérifier l'état de la LRO. D'autres erreurs d'interrogation sont transitoires et indiquent un problème temporaire dans le réseau client ou le service.

Vous pouvez définir chacune de ces règles indépendamment. De plus, vous pouvez appliquer une règle à toutes les LRO démarrées sur un client ou modifier la règle pour une seule requête.

Prérequis

Ce guide utilise le service Cloud Storage pour que les extraits de code soient concrets, mais les mêmes concepts s'appliquent à tout autre service utilisant des LRO.

Avant d'utiliser ce guide, suivez la procédure Utiliser Cloud Storage avec Rust pour activer et authentifier l'API Cloud Storage.

Pour obtenir des instructions de configuration complètes pour les bibliothèques Rust, consultez la page Configurer votre environnement de développement.

Dépendances

Ajoutez les dépendances suivantes à votre fichier Cargo.toml :

cargo add google-cloud-storage google-cloud-lro

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

Si vous prévoyez d'utiliser la même règle d'intervalle exponentiel entre les tentatives d'interrogation pour la plupart des requêtes avec le même client, envisagez de définir la règle comme option client. Cet exemple de code configure la fréquence d'interrogation pour toutes les requêtes adressées au service Cloud Storage.

pub async fn client_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    // Use a type that implements the `PollingBackoffPolicy` trait, in this case
    // `ExponentialBackoffBuilder`.
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use google_cloud_lro::Poller;
    use std::time::Duration;

    let client = StorageControl::builder()
        // Initialize the policy with a chosen delay duration.
        .with_polling_backoff_policy(
            ExponentialBackoffBuilder::new()
                .with_initial_delay(Duration::from_millis(250))
                .with_maximum_delay(Duration::from_secs(10))
                .build()?,
        )
        .build()
        .await?;

    // Initiate an LRO using polling.
    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 par un paramètre par requête, elle reste en vigueur pour toute opération de longue durée lancée par le client.

Par exemple, l'appel suivant utilisera cette règle :

    let mut operation = client
        .rename_folder()
        /* more stuff */
        .send()
        .await?;

Dans cet exemple d'appel, la bibliothèque cliente attend 250 ms après la première tentative d'interrogation, puis 500 ms pour la deuxième tentative. Les tentatives suivantes attendent 1 s, 2 s, 4 s et 8 s, puis toutes les tentatives suivantes attendent 10 s.

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

Vous pouvez configurer la fréquence d'interrogation pour une requête individuelle, ce qui remplace toute règle définie au niveau du client. Exemple :

pub async fn rpc_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    // Use a type that implements the `PollingBackoffPolicy` trait, in this case
    // `ExponentialBackoffBuilder`.
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use std::time::Duration;

    // To configure the request, bring the RequestOptionsBuilder trait into
    // scope.
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

    let client = StorageControl::builder().build().await?;
    // Create the request builder.
    let response = client
        .rename_folder()
        // Configure the polling backoff policy.
        .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)
        // Issue the polling request as normal.
        .poller()
        .until_done()
        .await?;

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

    Ok(())
}

Configurer les erreurs d'interrogation pouvant être retentées pour toutes les requêtes d'un client

Pour configurer les erreurs pouvant être retentées, utilisez un type qui implémente le trait PollingErrorPolicy. Les bibliothèques clientes fournissent plusieurs règles. Aip194Strict est un choix prudent. Si vous prévoyez d'utiliser la même règle d'interrogation pour la plupart des requêtes avec le même client, envisagez de définir la règle comme option client.

Cet exemple de code configure les erreurs d'interrogation pouvant être retentées pour toutes les requêtes adressées au service Cloud Storage :

pub async fn client_error_policy(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    // Use a type that implements the `PollingErrorPolicy` trait, in this case
    // `Aip194Strict`.
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_lro::Poller;
    use std::time::Duration;

    // Add the polling policy that you want to use for all long-running
    // operations.
    let client = StorageControl::builder()
        .with_polling_error_policy(
            Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .build()
        .await?;

    // Initiate an LRO using polling.
    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(())
}

Bien que la règle d'erreur d'interrogation gère les erreurs pendant la boucle d'attente de la LRO, vous pouvez également ajouter une règle de nouvelle tentative standard pour gérer les erreurs transitoires qui peuvent se produire lors de l'envoi initial de la requête pour démarrer la LRO :

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

Sauf si vous remplacez la règle par un paramètre par requête, elle reste en vigueur pour toute opération de longue durée lancée par le client. Par exemple, si vous effectuez l'appel suivant :

    let mut operation = client
        .rename_folder()
        /* more stuff */
        .send()
        .await?;

Remarque : La bibliothèque cliente ne traite que UNAVAILABLE (voir AIP-194) comme une erreur pouvant être retentée et arrête l'interrogation après 100 tentatives ou 300 secondes, selon la première de ces deux limites.

Configurer les erreurs d'interrogation pouvant être retentées pour une requête spécifique

Vous pouvez configurer les erreurs d'interrogation pouvant être retentées pour une requête spécifique en utilisant un type qui implémente le trait PollingErrorPolicy et en intégrant le trait RequestOptionsBuilder dans le champ d'application.

Cet exemple de code configure les erreurs d'interrogation pouvant être retentées pour une requête spécifique adressée au service Cloud Storage.

pub async fn rpc_error_policy(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    // Use a type that implements the `PollingErrorPolicy` trait, in this case
    // `Aip194Strict`.
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    // Bring `RequestOptionsBuilder` into scope.
    use google_cloud_gax::options::RequestOptionsBuilder;
    use std::time::Duration;
    use google_cloud_lro::Poller;

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

    // Create the request builder.
    let response = client
        .rename_folder()
        // Configure the polling error policy.
        .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)
        // Initialize the request.
        .poller()
        .until_done()
        .await?;

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

    Ok(())
}

Vous pouvez également envisager d'ajouter une règle de nouvelle tentative, au cas où la requête initiale de démarrage de la LRO échouerait :

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

Configurer les règles d'interrogation Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.