폴링 정책 구성

장기 실행 작업의 폴링 정책을 구성하는 방법을 알아봅니다. Rust용 Google Cloud 클라이언트 라이브러리는 장기 실행 작업 (LRO)의 진행 상황 모니터링을 간소화하는 도우미 함수를 제공합니다. 이러한 도우미는 정책을 사용하여 폴링 빈도를 구성하고 일시적 (안전하게 재시도할 수 있음)인 폴링 오류와 복구 불가능한 폴링 오류를 결정합니다.

두 가지 정책이 LRO 루프의 동작을 제어합니다.

• 폴링 백오프 정책 은 아직 진행 중인 LRO의 상태를 폴링하기 전에 루프가 대기하는 시간을 제어합니다.
• 폴링 오류 정책 은 폴링 오류 발생 시 수행할 작업을 제어합니다. 일부 폴링 오류는 복구 불가능하며 작업이 중단되었거나 호출자에게 LRO의 상태를 확인할 권한이 없음을 나타냅니다. 다른 폴링 오류는 일시적이며 클라이언트 네트워크 또는 서비스의 일시적인 문제를 나타냅니다.

이러한 각 정책을 독립적으로 설정할 수 있습니다. 또한 클라이언트에서 시작된 모든 LRO에 정책을 적용하거나 단일 요청의 정책을 변경할 수 있습니다.

기본 요건

이 가이드에서는 Cloud Storage 서비스를 사용하여 코드 스니펫을 구체적으로 유지하지만 동일한 개념이 LRO를 사용하는 다른 서비스에도 적용됩니다.

이 가이드를 사용하기 전에 Rust와 함께 Cloud Storage 사용에 따라 Cloud Storage API를 사용 설정하고 인증하세요.

Rust 라이브러리의 전체 설정 안내는 개발 환경 설정을 참고하세요.

종속 항목

Cargo.toml 파일에 다음 종속 항목을 추가합니다.

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

클라이언트의 모든 요청에 대한 폴링 빈도 구성

동일한 클라이언트의 대부분의 요청에 동일한 폴링 백오프 정책을 사용하려는 경우 정책을 클라이언트 옵션으로 설정하는 것이 좋습니다. 이 코드 샘플은 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(())
}

요청별 설정으로 정책을 재정의하지 않는 한 클라이언트에서 시작된 모든 장기 실행 작업에 정책이 적용됩니다.

예를 들어 다음 호출은 이 정책을 사용합니다.

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

이 예시 호출에서 클라이언트 라이브러리는 첫 번째 폴링 시도 후 250ms, 두 번째 시도 후 500ms를 기다립니다. 후속 시도는 1초, 2초, 4초, 8초를 기다린 후 모든 추가 시도는 10초를 기다립니다.

특정 요청의 폴링 빈도 구성

클라이언트 수준에서 설정된 정책을 재정의하는 개별 요청의 폴링 빈도를 구성할 수 있습니다. 예를 들면 다음과 같습니다.

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

클라이언트의 모든 요청에 대해 재시도 가능한 폴링 오류 구성

재시도 가능한 오류를 구성하려면 PollingErrorPolicy 트레이트를 구현하는 유형을 사용합니다. 클라이언트 라이브러리는 여러 정책을 제공합니다. 보수적인 선택은 Aip194Strict입니다. 동일한 클라이언트의 대부분의 요청에 동일한 폴링 정책을 사용하려는 경우 정책을 클라이언트 옵션으로 설정하는 것이 좋습니다.

이 코드 샘플은 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(())
}

폴링 오류 정책은 LRO 대기 루프 중에 오류를 처리하지만 표준 재시도 정책을 추가하여 LRO를 시작하기 위해 요청을 처음 보낼 때 발생할 수 있는 일시적인 오류를 처리할 수도 있습니다.

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

요청별 설정으로 정책을 재정의하지 않는 한 클라이언트에서 시작된 모든 장기 실행 작업에 정책이 적용됩니다. 예를 들어 다음 호출을 하는 경우:

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

AIP-194

특정 요청에 대해 재시도 가능한 폴링 오류 구성

PollingErrorPolicy 트레이트를 구현하는 유형을 사용하고 RequestOptionsBuilder 트레이트를 범위로 가져와 특정 요청에 대해 재시도 가능한 폴링 오류를 구성할 수 있습니다.

이 코드 샘플은 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(())
}

LRO를 시작하기 위한 초기 요청이 실패하는 경우 재시도 정책을 추가하는 것도 고려해 볼 수 있습니다.

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