הגדרת כללי מדיניות לגבי סקרים

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

שתי כללי מדיניות שולטים בהתנהגות של לולאות הסקרים של LRO:

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

אפשר להגדיר כל מדיניות בנפרד, לכל ה-LRO שהתחילו בלקוח או לבקשה ספציפית.

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

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

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

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

יחסי תלות

מוסיפים את ה-crates הנדרשים לקובץ Cargo.toml:

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

הגדרת תדירות הסקרים לכל הבקשות בלקוח

אם אתם משתמשים באותה מדיניות השהיה לפני ניסיון חוזר של דגימה ברוב הבקשות בלקוח, הגדירו את המדיניות בבונה הלקוח. בדוגמה הבאה מוגדרת השהיה מעריכית לפני ניסיון חוזר (exponential backoff) של דגימה לכל ה-LRO שהופעלו על ידי לקוח StorageControl:

pub async fn client_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use google_cloud_lro::Poller;
    use std::time::Duration;

    let client = StorageControl::builder()
        .with_polling_backoff_policy(
            ExponentialBackoffBuilder::new()
                .with_initial_delay(Duration::from_millis(250))
                .with_maximum_delay(Duration::from_secs(10))
                .build()?,
        )
        .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(())
}

אלא אם מבטלים את המדיניות בבקשה ספציפית, ההגדרה הזו חלה על כל LRO שהלקוח מתחיל. בדוגמה הזו, ספריית הלקוח ממתינה 250 אלפיות השנייה אחרי הסקר הראשון ו-500 אלפיות השנייה אחרי הסקר השני. לאחר מכן, ההשהיה מוכפלת לשנייה אחת, שתי שניות, 4 שניות ו-8 שניות, עד שהיא מגיעה למגבלה של 10 שניות לכל הסקרים הבאים.

הגדרת תדירות הסקרים לבקשה ספציפית

אפשר גם להגדיר את תדירות הסקרים בבונה בקשות ספציפי, מה שיעקוף את כל מדיניות ההשהיה של הסקרים ברמת הלקוח. מכניסים את RequestOptionsBuilder להיקף וקוראים ל-with_polling_backoff_policy בכלי ליצירת בקשות:

pub async fn rpc_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use std::time::Duration;
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

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

    let response = client
        .rename_folder()
        .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)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

הגדרת מדיניות שגיאות דגימה לכל הבקשות בלקוח

כדי לקבוע אילו שגיאות דגימה יגרמו ללולאה לנסות שוב ומתי הדגימה תיפסק, צריך להעביר סוג שמטמיע את המאפיין PollingErrorPolicy, כמו Aip194Strict.

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

pub async fn client_errors(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_gax::retry_policy;
    use google_cloud_gax::retry_policy::RetryPolicyExt;
    use std::time::Duration;
    use google_cloud_lro::Poller;

    let builder = StorageControl::builder().with_polling_error_policy(
        Aip194Strict
            .with_attempt_limit(100)
            .with_time_limit(Duration::from_secs(300)),
    );

    let client = builder
        .with_retry_policy(
            retry_policy::Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .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(())
}

הגדרת כללי מדיניות לשגיאות דגימה בבקשה ספציפית

כדי לשנות את מדיניות השגיאות של הסקר לבקשה אחת, צריך להביא את RequestOptionsBuilder להיקף ולהפעיל את with_polling_error_policy בבונה הבקשות:

pub async fn rpc_errors(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_gax::retry_policy;
    use google_cloud_gax::retry_policy::RetryPolicyExt;
    use std::time::Duration;
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

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

    let response = client
        .rename_folder()
        .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)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}