장기 실행 작업 다루기

API는 완료하는 데 상당한 시간이 걸리는 메서드를 노출할 수 있습니다. 작업이 실행되는 동안 차단하는 대신 프로미스를 반환하고 사용자가 상태를 확인할 수 있도록 할 수 있습니다.

Rust용 클라이언트 라이브러리는 이러한 장기 실행 작업 (LRO)을 처리하는 도우미를 제공합니다. Google Cloud 이 가이드에서는 LRO를 시작하고 완료될 때까지 기다리는 방법을 보여줍니다.

기본 요건

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

이 가이드를 따르기 전에 다음을 수행해야 합니다.

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

종속 항목

Cargo.toml 파일에서종속 항목을 선언합니다. Google Cloud 

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

또한 여러 tokio 기능이 필요합니다.

cargo add tokio --features full,macros

장기 실행 작업 시작

이 예에서는 폴더 이름 바꾸기를 사용합니다. 이 작업은 대용량 폴더의 경우 시간이 오래 걸릴 수 있지만 소용량 폴더의 경우 비교적 빠릅니다.

장기 실행 작업을 시작하려면 클라이언트를 초기화하고 RPC를 실행해야 합니다.

먼저 긴 패키지 이름을 피하기 위해 use 선언을 추가합니다.

use anyhow::anyhow;
use google_cloud_longrunning as longrunning;
use google_cloud_storage::client::StorageControl;

다음으로 클라이언트를 만듭니다.

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

Rust 클라이언트 라이브러리에서 각 요청은 요청 빌더를 반환하는 메서드로 표시됩니다. 클라이언트에서 메서드를 호출하여 요청 빌더를 만듭니다.

let operation = client
    .rename_folder()
    .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
    .set_destination_folder_id(dest)

샘플 함수는 버킷 및 폴더 이름을 인수로 허용합니다.

pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {

요청을 실행하고 작업이 반환될 때까지 기다립니다. 이 Operation은 장기 실행 요청 결과의 프로미스 역할을 합니다.

    let operation =
        // ...
        .send()
        .await?;

이 요청은 백그라운드에서 작업을 시작합니다. 작업이 완료될 때까지 기다려 성공 여부를 확인합니다.

장기 실행 작업 자동 폴링

자동 폴링을 구성하려면 다음과 같이 장기 실행 작업을 Poller로 시작합니다. .send().wait 대신

.poller()
.until_done()
.await?;

먼저 use 선언을 사용하여 범위에 Poller 특성을 도입합니다.

use google_cloud_lro::Poller;

그런 다음 클라이언트를 초기화하고 이전과 같이 요청을 준비합니다.

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:?}");

중간 결과가 있는 장기 실행 작업 폴링

.until_done() 메서드는 편리하지만 장기 실행 작업의 부분 진행률 보고서를 생략합니다. 애플리케이션에 이 정보가 필요한 경우 폴러를 직접 사용합니다.

    let mut poller = client
        .rename_folder()
        /* more stuff */
        .poller();

그런 다음 루프에서 폴러를 사용합니다.

while let Some(p) = poller.poll().await {
    match p {
        PollingResult::Completed(r) => {
            println!("LRO completed, response={r:?}");
        }
        PollingResult::InProgress(m) => {
            println!("LRO in progress, metadata={m:?}");
        }
        PollingResult::PollingError(e) => {
            println!("Transient error polling the LRO: {e}");
        }
    }
    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
}

이 루프는 다시 폴링하기 전에 명시적으로 대기합니다. 폴링 기간은 특정 작업 및 페이로드에 따라 다릅니다. 서비스 문서를 참고하거나 데이터를 실험하여 적절한 값을 결정합니다.

장기 실행 작업 수동 폴링

자동 폴링 접근 방식을 권장하지만 장기 실행 작업을 수동으로 폴링할 수도 있습니다. 자세한 내용은 작업 메시지 참고 문서 문서를 참고하세요.

클라이언트를 사용하여 장기 실행 작업을 시작합니다.

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

폴링 루프를 시작하고 done 필드를 사용하여 작업이 완료되었는지 확인합니다.

let response: anyhow::Result<Folder> = loop {
    if operation.done {

작업이 완료되면 일반적으로 결과가 포함됩니다. 서비스에서 결과 없이 done을 true로 반환할 수 있으므로 결과 필드는 선택사항입니다. 예를 들어 삭제 작업이 성공하면 반환 값이 없습니다. 이 예에서 Cloud Storage 서비스는 항상 값을 반환합니다.

match &operation.result {
    None => {
        break Err(anyhow!("missing result for finished operation"));
    }

시작된 작업이 성공적으로 완료되지 않을 수 있습니다. 결과는 오류 또는 유효한 응답일 수 있습니다. 먼저 오류를 확인합니다.

Some(r) => {
    break match r {
        longrunning::model::operation::Result::Error(s) => {
            Err(anyhow!("operation completed with error {s:?}"))
        }

오류 유형은 상태 메시지 유형입니다. 표준 Error 특성을 구현하지 않습니다. Error::service를 사용하여 유효한 오류로 수동으로 변환합니다.

결과가 성공하면 응답 유형을 추출합니다. LRO 메서드 문서 또는 서비스 API 참고 리소스에서 이 유형을 찾습니다.

longrunning::model::operation::Result::Response(any) => {
    let response = any.to_msg::<Folder>()?;
    Ok(response)
}

유형이 서비스에서 보낸 유형과 일치하지 않으면 값 추출이 실패할 수 있습니다.

Google Cloud 유형은 향후 필드와 브랜치를 추가할 수 있습니다. Rust용 클라이언트 라이브러리는 모든 구조체와 enum을 #[non_exhaustive]로 표시합니다. Google Cloud 이 케이스를 처리합니다.

_ => Err(anyhow!("unexpected result branch {r:?}")),

작업이 완료되지 않은 경우 메타데이터가 포함될 수 있습니다. 일부 서비스에는 요청에 관한 초기 정보가 포함되어 있고 다른 서비스에는 부분 진행률 보고서가 포함되어 있습니다. 이 메타데이터를 추출하고 보고할 수 있습니다.

if let Some(any) = &operation.metadata {
    let metadata = any.to_msg::<RenameFolderMetadata>()?;
    println!("LRO in progress, metadata={metadata:?}");
}

다시 폴링하기 전에 기다립니다. 잘린 지수 백오프 를 사용하여 폴링 기간을 조정하는 것이 좋습니다. 이 예에서는 500ms마다 폴링합니다.

tokio::time::sleep(std::time::Duration::from_millis(500)).await;

작업 상태를 쿼리합니다.

if let Ok(attempt) = client
    .get_operation()
    .set_name(&operation.name)
    .send()
    .await
{
    operation = attempt;
}

편의상 이 예에서는 모든 오류를 무시합니다. 애플리케이션에서 오류의 하위 집합을 복구 불가능한 것으로 처리하고 폴링 시도 횟수를 제한할 수 있습니다.

다음 단계

  • GitHub에서 예시의 소스 코드를 GitHub.