עבודה עם פעולות ממושכות

יש שיטות (methods) של Google Cloud API שפעולתן נמשכת זמן רב. במקום לחסום עד לסיום העבודה, השיטות האלה מחזירות משאב Operation שמייצג פעולה שמתבצעת, כדי שהאפליקציה תוכל לדגום את הסטטוס ואת התוצאה הסופית שלה.

ספריות הלקוח ב-Cloud ל-Rust מספקות כלי עזר לעבודה עם הפעולות הממושכות האלה (LRO). במאמר הזה מוסבר איך להתחיל LRO, לדגום באופן אוטומטי עד לסיום, לבדוק עדכוני התקדמות ביניים ולדגום באופן ידני.

לפני שמתחילים

במאמר הזה נשתמש ב-Cloud Storage כדי להציג דוגמאות קונקרטיות לקוד, אבל אותם מושגים רלוונטיים לכל שירות של Google Cloud שמשתמש ב-LRO.

לפני שמריצים את הקוד במסמך הזה, צריך להשלים את הדרישות המוקדמות הבאות:

  • יוצרים או בוחרים פרויקט ב-Google Cloud שהחיוב מופעל בו.
  • כדי להגדיר את סביבת הפיתוח ואת פרטי הכניסה, פועלים לפי ההוראות במאמר תחילת העבודה עם Rust.
  • יוצרים קטגוריה של Cloud Storage עם מרחב שמות היררכי, ויוצרים תיקיית מקור כדי לשנות את השם שלה.
  • מקצים לחשבון המשתמש תפקיד בממשק לניהול הזהויות והרשאות הגישה (IAM) עם הרשאה לניהול תיקיות, כמו אדמין של Storage‏ (roles/storage.admin).

יחסי תלות

מוסיפים את ספריית הלקוח ואת ה-crate של LRO לקובץ Cargo.toml:

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

מוסיפים את tokio להפעלה אסינכרונית ולטיימרים:

cargo add tokio --features full

התחלת פעולה ממושכת

בדוגמאות שבמסמך הזה מתבצעת קריאה לפעולה rename folder ב-Cloud Storage, שמחזירה LRO. כדי להפעיל LRO ישירות ולקבל את המשאב הראשוני של Operation, מבצעים את הפעולות הבאות:

  1. מוסיפים הצהרות use כדי לקצר את נתיבי הסוגים:

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

  2. מגדירים פונקציית 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?;

אחרי שמתחילים את הפעולה, ממתינים שהיא תסתיים כדי לאחזר את התוצאה הסופית שלה.

דגימה אוטומטית של פעולה ממושכת

ברוב התרחישים לדוגמה, משתמשים ב-method‏ until_done של המאפיין Poller במקום לקרוא ישירות ל-send. ה-poller מפעיל את ה-LRO, מבצע דגימה לפי מדיניות ההשהיה לפני ניסיון חוזר (backoff) והטיפול בשגיאות של הלקוח, ומחזיר את התשובה הסופית:

  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 מטפל כמעט בכל התרחישים לדוגמה, אפשר גם לדגום Operation באופן ידני באמצעות get_operation:

  1. אחרי הפעלת ה-LRO באמצעות send, נכנסים ללולאה ובודקים את השדה done:

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

  2. בודקים את operation.result. השדה result הוא Option כי פעולות מסוימות, כמו מחיקות, מסתיימות בלי להחזיר מטען ייעודי (payload). ב-rename_folder, השירות מחזיר משאב Folder:

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

  3. בודקים אם הפעולה הסתיימה עם שגיאה. הווריאנט של השגיאה מכיל הודעת Status, שבדוגמה הבאה מעוצבת כשגיאה, או שאפשר להמיר אותה לשגיאת לקוח באמצעות Error::service:

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

  4. אם הפעולה הצליחה, פורקים את המטען הייעודי (payload) של Any לסוג התגובה הצפוי של Folder:

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

  5. מוסיפים זרוע של תו כללי לחיפוש כי טיפוסי ה-enum בספריות הלקוח של Cloud ל-Rust מסומנים בתור #[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. צריך להמתין לפני ששולחים שוב בקשה. בדוגמה הזו, כדי לקצר, ההשהיה היא למשך 500 אלפיות השנייה. בקוד ייצור, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff):

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

  8. שולחים קריאה אל get_operation עם operation.name כדי לרענן את סטטוס הפעולה:

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