Abfrage-Richtlinien konfigurieren

Die Cloud-Clientbibliotheken für Rust bieten Hilfsfunktionen zum Überwachen des Fortschritts von Vorgängen mit langer Ausführungszeit (Long-Running Operations, LROs). Diese Hilfsprogramme verwenden Richtlinien, um die Abfragehäufigkeit zu konfigurieren und zu bestimmen, welche Abfragefehler vorübergehend sind und sicher wiederholt werden können und welche nicht wiederherstellbar sind.

Zwei Richtlinien steuern das Verhalten von LRO-Abfrageschleifen:

  • Die Polling-Backoff-Richtlinie steuert, wie lange die Schleife wartet, bevor der Status eines laufenden LRO abgefragt wird.
  • Die Richtlinie für Abfragefehler steuert, wie ein Abfragefehler behandelt wird. Einige Abruffehler sind nicht behebbar. Das bedeutet, dass der Vorgang beendet wurde oder der Aufrufer nicht die Berechtigung hat, den Status zu prüfen. Andere Abfragefehler sind vorübergehend und weisen auf ein temporäres Netzwerk- oder Dienstproblem hin.

Sie können jede Richtlinie unabhängig festlegen, entweder für alle LROs, die auf einem Client gestartet wurden, oder für eine einzelne Anfrage.

Hinweis

In diesem Dokument wird die Konfiguration von Abfragerichtlinien anhand von Cloud Storage veranschaulicht. Die gleichen Konzepte gelten jedoch für alle Google Cloud -Dienste, die LROs verwenden.

Bevor Sie den Code in diesem Dokument ausführen, müssen die folgenden Voraussetzungen erfüllt sein:

  • Folgen Sie der Anleitung unter Erste Schritte mit Rust, um Ihre Entwicklungsumgebung einzurichten.
  • Folgen Sie der Anleitung unter Cloud Storage mit Rust verwenden, um ein Google Cloud -Projekt mit aktivierter Abrechnung einzurichten, die Cloud Storage API zu aktivieren und Anmeldedaten zu konfigurieren.
  • Erstellen Sie einen Cloud Storage-Bucket mit aktiviertem hierarchischen Namespace, erstellen Sie einen Quellordner, der umbenannt werden soll, und weisen Sie Ihrem Hauptkonto eine IAM-Rolle (Identity and Access Management) mit der Berechtigung zum Verwalten von Ordnern zu, z. B. Storage-Administrator (roles/storage.admin).

Abhängigkeiten

Fügen Sie der Datei Cargo.toml die erforderlichen Crates hinzu:

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

Abfragehäufigkeit für alle Anfragen auf einem Client konfigurieren

Wenn Sie für die meisten Anfragen auf einem Client dieselbe Backoff-Richtlinie für Abfragen verwenden, konfigurieren Sie die Richtlinie im Client-Builder. Im folgenden Beispiel wird ein exponentielles Backoff für Abfragen für alle LROs konfiguriert, die von einem StorageControl-Client gestartet wurden:

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

Sofern Sie die Richtlinie nicht für eine einzelne Anfrage überschreiben, gilt diese Konfiguration für jeden vom Client gestarteten LRO. In diesem Beispiel wartet die Clientbibliothek nach der ersten Abfrage 250 ms und nach der zweiten 500 ms. Die Verzögerung verdoppelt sich dann auf 1 s, 2 s, 4 s und 8 s, bevor sie für alle nachfolgenden Abfragen auf 10 s begrenzt wird.

Abfragehäufigkeit für eine bestimmte Anfrage konfigurieren

Sie können die Abfragehäufigkeit auch für einen einzelnen Request Builder konfigurieren. Dadurch wird jede Backoff-Richtlinie für Abfragen auf Clientebene überschrieben. Fügen Sie RequestOptionsBuilder hinzu und rufen Sie with_polling_backoff_policy im Request Builder auf:

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

Richtlinien für Abruffehler für alle Anfragen auf einem Client konfigurieren

Wenn Sie steuern möchten, bei welchen Abruffehlern die Schleife wiederholt wird und wann der Abruf beendet wird, übergeben Sie einen Typ, der das PollingErrorPolicy-Merkmal implementiert, z. B. Aip194Strict.

Die Richtlinie für Abfragefehler gilt nur für Fehler während der LRO-Warteschleife. Um vorübergehende Fehler beim Senden der ersten Anfrage, die den LRO startet, zu beheben, konfigurieren Sie auch eine Standardrichtlinie für Wiederholungsversuche auf dem 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(())
}

Richtlinien für Abruffehler für eine bestimmte Anfrage konfigurieren

Wenn Sie die Richtlinie für Abfragefehler für eine einzelne Anfrage überschreiben möchten, rufen Sie RequestOptionsBuilder auf und rufen Sie with_polling_error_policy im Request Builder auf:

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