장기 실행 작업 다루기

일부 Google Cloud API 메서드는 완료하는 데 상당한 시간이 걸립니다. 이러한 메서드는 작업이 완료될 때까지 차단하는 대신 진행 중인 작업을 나타내는 Operation 리소스를 반환하므로 애플리케이션에서 상태와 최종 결과를 폴링할 수 있습니다.

Rust용 Cloud 클라이언트 라이브러리는 이러한 장기 실행 작업(LRO)을 처리하는 도우미를 제공합니다. 이 문서에서는 LRO를 시작하고, 완료될 때까지 자동으로 폴링하고, 중간 진행 상황 업데이트를 검사하고, 수동으로 폴링하는 방법을 보여줍니다.

시작하기 전에

이 문서에서는 Cloud Storage를 사용하여 코드 예시를 구체적으로 유지하지만, LRO를 사용하는 모든 Google Cloud 서비스에 동일한 개념이 적용됩니다.

이 문서의 코드를 실행하기 전에 다음 기본 요건을 완료하세요.

  • 결제가 사용 설정된 Google Cloud 프로젝트를 만들거나 선택합니다.
  • Rust 시작하기에 따라 개발 환경과 사용자 인증 정보를 설정합니다.
  • 계층적 네임스페이스가 사용 설정된 Cloud Storage 버킷을 만들고 이름을 바꿀 소스 폴더를 만듭니다.
  • 주 구성원에게 스토리지 관리자(roles/storage.admin)와 같은 폴더 관리 권한이 있는 Identity and Access Management(IAM) 역할을 부여합니다.

종속 항목

클라이언트 라이브러리와 LRO 크레이트를 Cargo.toml 파일에 추가합니다.

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

비동기 실행 및 타이머를 위해 tokio를 추가합니다.

cargo add tokio --features full

장기 실행 작업 시작

이 문서의 예시에서는 LRO를 반환하는 Cloud Storage 폴더 이름 바꾸기 작업을 호출합니다. LRO를 직접 시작하고 초기 Operation 리소스를 가져오려면 다음 단계를 완료합니다.

  1. use 선언을 추가하여 유형 경로를 단축합니다.

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

  2. 버킷 ID, 소스 폴더 ID, 대상 폴더 ID를 허용하는 async 함수를 정의합니다.

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

  3. StorageControl 클라이언트를 초기화합니다.

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

  4. rename_folder 요청 빌더를 만듭니다.

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

  5. 요청을 전송하고 백그라운드 작업을 나타내는 초기 Operation 리소스를 기다립니다.

    .send()
    .await?;

작업을 시작한 후 완료될 때까지 기다려 최종 결과를 가져옵니다.

장기 실행 작업 자동 폴링

대부분의 사용 사례에서는 send를 직접 호출하는 대신 Poller 트레잇의 until_done 메서드를 사용합니다. 폴러는 LRO를 시작하고 클라이언트의 백오프 및 오류 정책에 따라 폴링하고 최종 응답으로 확인합니다.

  1. Poller 트레잇을 범위로 가져옵니다.

    use google_cloud_lro::Poller;

  2. StorageControl 클라이언트를 초기화하고 rename_folder 요청 빌더를 구성합니다.

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

  3. 요청 빌더에서 poller 및 until_done를 호출하여 완료를 기다리고 결과를 출력합니다.

        .poller()
        .until_done()
        .await?;
    
    println!("LRO completed, response={response:?}");

자동 폴링 코드 완료

다음 함수는 전체 자동 폴링 예시를 보여줍니다.

pub async fn automatic(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::Poller;

    let client = StorageControl::builder().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(())
}

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

until_done 메서드는 최종 결과만 반환하고 중간 메타데이터 업데이트는 생략합니다. LRO가 실행되는 동안 애플리케이션에 진행 상황 업데이트가 필요한 경우 poller를 사용하여 폴러를 가져오고 루프에서 poll를 호출합니다.

  1. Poller 및 PollingResult를 가져옵니다.

    use google_cloud_lro::{Poller, PollingResult};

  2. poller를 사용하여 요청 빌더를 폴러로 변환합니다.

    .poller();

  3. 루프에서 poller.poll().await를 호출하여 InProgress, PollingError, Completed 상태를 처리합니다.

    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;
    }

poll를 직접 호출할 때 루프는 폴링 시도 간의 지연을 제어합니다. 작업의 예상 기간에 적합한 지연 시간을 선택합니다.

중간 결과를 사용한 폴링의 전체 코드

다음 함수는 전체 poll 루프를 보여줍니다.

pub async fn polling(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::{Poller, PollingResult};

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

    let mut poller = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .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;
    }

    Ok(())
}

장기 실행 작업 수동 폴링

Poller 특성은 거의 모든 사용 사례를 처리하지만 get_operation를 사용하여 Operation를 수동으로 폴링할 수도 있습니다.

  1. send로 LRO를 시작한 후 루프를 입력하고 done 필드를 확인합니다.

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

  2. operation.result을 검사합니다. 삭제와 같은 일부 작업은 페이로드를 반환하지 않고 완료되므로 result 필드는 Option입니다. rename_folder의 경우 서비스는 Folder 리소스를 반환합니다.

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

  3. 작업이 오류로 완료되었는지 확인합니다. 오류 변형에는 다음 예시에서 오류로 형식을 지정하거나 Error::service를 사용하여 클라이언트 오류로 변환할 수 있는 Status 메시지가 포함됩니다.

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

  4. 작업이 성공하면 Any 페이로드를 예상되는 Folder 응답 유형으로 압축 해제합니다.

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

  5. Rust용 Cloud 클라이언트 라이브러리의 enum은 #[non_exhaustive]로 표시되므로 와일드 카드 암을 추가합니다.

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

  6. 선택사항: operation.done가 false인 동안 operation.metadata의 압축을 풀어 진행 상황 업데이트를 검사합니다.

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

  7. 다시 폴링하기 전에 기다립니다. 이 예시에서는 간결성을 위해 500ms 동안 대기합니다. 프로덕션 코드에서는 잘린 지수 백오프를 사용합니다.

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

  8. operation.name를 사용하여 get_operation를 호출하여 작업 상태를 새로고침합니다.

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

수동 폴링 코드 완료

다음 함수는 모든 수동 폴링 단계를 결합합니다.

pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_storage::model::Folder;
    use google_cloud_storage::model::RenameFolderMetadata;

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

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .send()
        .await?;
    println!("LRO started, response={operation:?}");

    let mut operation = operation;
    let response: anyhow::Result<Folder> = loop {
        if operation.done {
            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:?}"))
                        }
                        longrunning::model::operation::Result::Response(any) => {
                            let response = any.to_msg::<Folder>()?;
                            Ok(response)
                        }
                        _ => Err(anyhow!("unexpected result branch {r:?}")),
                    };
                }
            }
        }
        if let Some(any) = &operation.metadata {
            let metadata = any.to_msg::<RenameFolderMetadata>()?;
            println!("LRO in progress, metadata={metadata:?}");
        }
        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;
        }
    };
    println!("LRO completed, response={response:?}");

    Ok(())
}