配置重试政策

Rust 版 Cloud 客户端库可以自动重试因暂时性错误而失败的操作。本文档介绍了如何在客户端上配置默认重试政策、设置尝试次数和时间限制,以及替换单个请求的重试政策。

准备工作

本文档中的示例使用 Secret Manager,但这些概念同样适用于其他 Google Cloud 服务。

在运行本文档中的代码之前,请按照使用 Secret Manager 创建和访问 Secret 中的说明启用 Secret Manager API 并配置身份验证。

依赖项

将所需的 crate 添加到 Cargo.toml 文件中:

cargo add google-cloud-secretmanager-v1 google-cloud-gax anyhow

配置默认重试政策

此示例使用 Aip194Strict 政策,该政策实现了 AIP-194 中有关重试 Google API 请求的准则。

如需将 Aip194Strict 配置为客户端的默认重试政策,请完成以下步骤:

  1. 在客户端初始化期间设置重试政策:

    let client = SecretManagerService::builder()
        .with_retry_policy(Aip194Strict)
        .build()
        .await?;

  2. 使用配置的客户端发送请求:

    let mut list = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .by_item();
    while let Some(secret) = list.next().await {
        let secret = secret?;
        println!("  secret={}", secret.name);
    }

默认重试政策的完整代码

以下示例将 Aip194Strict 应用于 Secret Manager 客户端:

use google_cloud_gax::paginator::ItemPaginator as _;
use google_cloud_gax::retry_policy::Aip194Strict;
use google_cloud_secretmanager_v1::client::SecretManagerService;

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

    let mut list = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .by_item();
    while let Some(secret) = list.next().await {
        let secret = secret?;
        println!("  secret={}", secret.name);
    }

    Ok(())
}

配置具有限制的默认重试政策

默认情况下,Aip194Strict 不会限制尝试次数或重试所花费的总时间。如需在客户端上配置尝试次数和时间限制,请将 RetryPolicyExt 特征纳入范围,并完成以下步骤:

  1. 在客户端构建器上使用 with_attempt_limit 和 with_time_limit 配置重试政策:

    let client = SecretManagerService::builder()
        .with_retry_policy(
            Aip194Strict
                .with_attempt_limit(5)
                .with_time_limit(Duration::from_secs(15)),
        )
        .build()
        .await?;

  2. 使用配置的客户端发送请求:

    let mut list = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .by_item();
    while let Some(secret) = list.next().await {
        let secret = secret?;
        println!("  secret={}", secret.name);
    }

具有限制的重试政策的完整代码

以下示例应用了具有自定义尝试次数和时间限制的 Aip194Strict:

use google_cloud_gax::paginator::ItemPaginator as _;
use google_cloud_gax::retry_policy::Aip194Strict;
use google_cloud_gax::retry_policy::RetryPolicyExt;
use google_cloud_secretmanager_v1::client::SecretManagerService;
use std::time::Duration;

pub async fn sample(project_id: &str) -> anyhow::Result<()> {
    let client = SecretManagerService::builder()
        .with_retry_policy(
            Aip194Strict
                .with_attempt_limit(5)
                .with_time_limit(Duration::from_secs(15)),
        )
        .build()
        .await?;

    let mut list = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .by_item();
    while let Some(secret) = list.next().await {
        let secret = secret?;
        println!("  secret={}", secret.name);
    }

    Ok(())
}

替换单个请求的重试政策

如果您知道重试特定操作对应用来说是安全的,则可以替换单个请求的重试政策。例如,删除 Secret 最多只能成功一次,即使客户端库默认将删除操作视为非幂等操作也是如此。

将 RequestOptionsBuilder、RetryPolicyExt 和 AlwaysRetry 引入作用域,然后在请求构建器上调用 with_retry_policy:

client
    .delete_secret()
    .set_name(format!("projects/{project_id}/secrets/{secret_id}"))
    .with_retry_policy(
        AlwaysRetry
            .with_attempt_limit(5)
            .with_time_limit(Duration::from_secs(15)),
    )
    .send()
    .await?;

针对每个请求的重试政策的完整代码

以下示例会替换单个 delete_secret 请求的重试政策、尝试次数限制和时间限制:

use google_cloud_gax::options::RequestOptionsBuilder;
use google_cloud_gax::retry_policy::AlwaysRetry;
use google_cloud_gax::retry_policy::RetryPolicyExt;
use google_cloud_secretmanager_v1::client::SecretManagerService;
use std::time::Duration;

pub async fn sample(
    client: &SecretManagerService,
    project_id: &str,
    secret_id: &str,
) -> anyhow::Result<()> {
    client
        .delete_secret()
        .set_name(format!("projects/{project_id}/secrets/{secret_id}"))
        .with_retry_policy(
            AlwaysRetry
                .with_attempt_limit(5)
                .with_time_limit(Duration::from_secs(15)),
        )
        .send()
        .await?;

    Ok(())
}