Configurazione delle policy di polling

Le librerie client di Cloud per Rust forniscono funzioni helper per monitorare l'avanzamento delle operazioni a lunga esecuzione (LRO). Questi helper utilizzano le policy per configurare la frequenza di polling e determinare quali errori di polling sono temporanei e possono essere riprovati in sicurezza e quali non sono recuperabili.

Due policy controllano il comportamento dei loop di polling LRO:

  • La policy di backoff del polling controlla il tempo di attesa del loop prima di eseguire il polling dello stato di un'operazione LRO in corso.
  • La policy sugli errori di polling controlla come gestire un errore di polling. Alcuni errori di polling non sono recuperabili, il che indica che l'operazione è stata interrotta o che il chiamante non dispone dell'autorizzazione per controllarne lo stato. Altri errori di polling sono temporanei e indicano un problema di rete o di servizio temporaneo.

Puoi impostare ogni policy in modo indipendente, per tutte le LRO avviate su un client o per una singola richiesta.

Prima di iniziare

Questo documento utilizza Cloud Storage per illustrare la configurazione della policy di polling, anche se gli stessi concetti si applicano a qualsiasi servizio Google Cloud che utilizza le LRO.

Prima di eseguire il codice in questo documento, completa i seguenti prerequisiti:

  • Segui Inizia a utilizzare Rust per configurare l'ambiente di sviluppo.
  • Segui Utilizzo di Cloud Storage con Rust per configurare un progetto Google Cloud con la fatturazione abilitata, abilitare l'API Cloud Storage e configurare le credenziali.
  • Crea un bucket Cloud Storage con lo spazio dei nomi gerarchico abilitato, crea una cartella di origine da rinominare e concedi alla tua entità un ruolo Identity and Access Management (IAM) con l'autorizzazione per gestire le cartelle, ad esempio Storage Admin (roles/storage.admin).

Dipendenze

Aggiungi i crate richiesti al file Cargo.toml:

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

Configura la frequenza di polling per tutte le richieste su un client

Se utilizzi la stessa policy di backoff del polling per la maggior parte delle richieste su un client, configura la policy sul client builder. L'esempio seguente configura il backoff di polling esponenziale per tutte le LRO avviate da 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(())
}

A meno che non esegui l'override della policy su una singola richiesta, questa configurazione si applica a ogni LRO avviata dal client. In questo esempio, la libreria client attende 250 ms dopo il primo sondaggio e 500 ms dopo il secondo. Il ritardo raddoppia poi a 1 s, 2 s, 4 s e 8 s prima di raggiungere il limite massimo di 10 s per tutti i sondaggi successivi.

Configura la frequenza di polling per una richiesta specifica

Puoi anche configurare la frequenza di polling su un singolo generatore di richieste, che sostituisce qualsiasi policy di backoff di polling a livello di client. Inserisci RequestOptionsBuilder nell'ambito e chiama with_polling_backoff_policy sul generatore di richieste:

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(())
}

Configura le policy di errore di polling per tutte le richieste su un client

Per controllare quali errori di polling vengono ritentati dal loop e quando il polling si interrompe, passa un tipo che implementa il tratto PollingErrorPolicy, ad esempio Aip194Strict.

La policy sugli errori di polling regola gli errori solo durante il loop di attesa dell'LRO. Per gestire gli errori temporanei durante l'invio della richiesta iniziale che avvia l'LRO, configura anche una policy di ripetizione standard sul 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(())
}

Configura le policy di errore di polling per una richiesta specifica

Per eseguire l'override della policy di errore di polling per una singola richiesta, porta RequestOptionsBuilder nell'ambito e chiama with_polling_error_policy sul generatore di richieste:

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(())
}