עבודה עם פעולות ברשימה

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

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

דרישות מוקדמות

במדריך הזה נעשה שימוש בשירות Secret Manager כדי להדגים פעולות של רשימה. המושגים שמופיעים במדריך הזה רלוונטיים גם לשירותים אחרים.

כדי לפעול לפי המדריך הזה, צריך להפעיל את השירות Secret Manager, להיכנס לחשבון ולוודא שיש לחשבון את ההרשאות הנדרשות. כדי לקבל הנחיות לגבי השלמת הדרישות המוקדמות האלה, אפשר לעיין במדריך למתחילים של השירות.

הוראות מלאות להגדרת ספריות Rust זמינות במאמר הגדרת סביבת הפיתוח.

תלויות

מוסיפים את ספריית Secret Manager לקובץ Cargo.toml:

cargo add google-cloud-secretmanager-v1

איטרציה של שיטות ברשימה

כדי לעזור לכם לחזור על הפריטים בשיטת רשימה, ממשקי ה-API מחזירים הטמעה של המאפיין ItemPaginator. מגדירים את התכונה בהיקף באמצעות הצהרה של use:

use google_cloud_gax::paginator::ItemPaginator as _;

כדי לבצע איטרציה על הפריטים, משתמשים בשיטה by_item.

let mut list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_item();
while let Some(secret) = list.next().await {
    let secret = secret?;
    println!("  secret={}", secret.name)
}

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

1. מגדירים את Paginator בהיקף באמצעות הצהרת use:

   use google_cloud_gax::paginator::Paginator as _;

2. מבצעים איטרציה על הדפים באמצעות by_page:

   let mut list = client
       .list_secrets()
       .set_parent(format!("projects/{project_id}"))
       .by_page();
   while let Some(page) = list.next().await {
       let page = page?;
       println!("  next_page_token={}", page.next_page_token);
       page.secrets
           .into_iter()
           .for_each(|secret| println!("    secret={}", secret.name));
   }

עבודה עם futures::Stream

יכול להיות שתרצו להשתמש בממשקי ה-API האלה במערכת האקולוגית הגדולה יותר של Rust של זרמים אסינכרוניים, כמו tokio::Stream. כדי לעשות את זה:

1. מפעילים את התכונה unstable-streams בתיבת google_cloud_gax. השם של התכונה הזו הוא הודעה שממשקי ה-API האלה לא יציבים. כדאי להשתמש בהם רק אם אתם מוכנים להתמודד עם שיבושים שנובעים משינויים לא תואמים במאפיין futures::Stream.

   cargo add google-cloud-gax --features unstable-stream
   

2. בדוגמאות הבאות נעשה שימוש גם במאפיין futures::stream::StreamExt, שאפשר להפעיל אותו על ידי הוספת תיבת הכלים futures.

   cargo add futures
   

3. מוסיפים את ההצהרות הנדרשות use:

   use futures::stream::StreamExt;
   use google_cloud_gax::paginator::ItemPaginator as _;

4. משתמשים בפונקציה into_stream כדי להמיר את ItemPaginator ל-futures::Stream.

   let list = client
       .list_secrets()
       .set_parent(format!("projects/{project_id}"))
       .by_item()
       .into_stream();
   list.map(>|secret| - g<ax>::Result() {
       println!("  secret={}", secret?.name);
       Ok(())
   })
   .fold(Ok(()), a>sync |acc, r<es>ult| - gax::Result() {
       acc.and(result)
   })
   .await?;

באופן דומה, אפשר להשתמש בפונקציה into_stream כדי להמיר את Paginator ל-futures::Stream.

let list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_page()
    .into_stream();
list.enumerate()
    .map(|(index>, page)| - g<ax>::Result() {
        println!("page={}, next_page_token={}", index, page?.next_page_token);
        Ok(())
    })
    .fold(Ok(()), a>sync |acc, r<es>ult| - gax::Result() {
        acc.and(result)
    })
    .await?;

המשכת שימוש בשיטות של רשימות על ידי הגדרת אסימון של הדף הבא

במקרים מסוימים, כמו פעולת רשימה שהופסקה, אפשר להגדיר את הטוקן של הדף הבא כדי להמשיך את חלוקת התוצאות לדפים מדף ספציפי.

let page = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .send()
    .await;
let page = page?;
let mut next_page_token = page.next_page_token.clone();
page.secrets
    .into_iter()
    .for_each(|secret| println!("    secret={}", secret.name));

while !next_page_token.is_empty() {
    println!("  next_page_token={next_page_token}");

    let page = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .set_page_token(next_page_token)
        .send()
        .await;
    let page = page?;
    next_page_token = page.next_page_token.clone();

    page.secrets
        .into_iter()
        .for_each(|secret| println!("    secret={}", secret.name));
}

מתי כדאי להשתמש בעזרים של רכיב ה-paginator

Google Cloud ספריות הלקוח ל-Rust מספקות מתאם להמרה של רשימת RPCs כפי שמוגדר ב-AIP-4233 לסוגים שמטמיעים את ItemPaginator ו-Paginator אם השיטה Google API List פועלת לפי ההנחיות בנושא חלוקה לדפים שמוגדרות ב-AIP-158. בקיצור, ההנחיה הזו מחייבת שכל קריאה ל-method‏ List תחזיר דף של פריטי משאבים (לדוגמה, סודות) יחד עם טוקן שאפשר להעביר ל-method‏ List כדי לאחזר את הדף הבא.

רוב השירותים של Google Cloud פועלים לפי ההנחיות האלה. במקרים שבהם הם לא עושים זאת, צריך להטמיע מתאם משלכם כדי לחזור על התוצאות.