תורי ההוספה לאינדקס של Google Cloud Search

‫Connector SDK ו-Google Cloud Search API מאפשרים ליצור תורים לאינדוקס ב-Cloud Search, שמשמשים לביצוע המשימות הבאות:

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

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

• לתעדף פריטים בתורים לפי הסטטוס שלהם.

• לתחזק מידע נוסף על מצב השילוב כדי שהוא יהיה יעיל, כמו נקודות ביקורת, אסימון שינוי וכו'.

תור הוא תווית שמוקצית לפריט שעבר אינדוקס, כמו 'default' לתור ברירת המחדל או 'B' לתור B.

סטטוס ועדיפות

העדיפות של מסמך בתור מבוססת על קוד ItemStatus. אלה קודי ItemStatus האפשריים לפי סדר העדיפות (מהטיפול הראשון ועד האחרון):

• ‫ERROR – הפריט נתקל בשגיאה אסינכרונית במהלך תהליך היצירה של האינדקס, וצריך ליצור לו אינדקס מחדש.

• ‫MODIFIED – פריט שעבר אינדוקס בעבר, ומאז עבר שינוי במאגר מאז האינדוקס האחרון.

• ‫NEW_ITEM – פריט שלא נכלל באינדקס.

• ‫ACCEPTED – מסמך שעבר אינדוקס בעבר ולא השתנה במאגר מאז האינדוקס האחרון.

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

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

איור 1 מציג את השלבים באינדוקס של פריט חדש או פריט שהשתנה באמצעות תור אינדוקס. בשלבים הבאים מוצגות קריאות ל-API בארכיטקטורת REST. למידע על קריאות שוות-ערך ל-SDK, אפשר לעיין במאמר בנושא פעולות בתור (Connector SDK).

איור 1. שלבי יצירת אינדקס להוספה או לעדכון של פריט

1. מחבר התוכן משתמש ב-items.push כדי להעביר פריטים (מטא-נתונים וגיבוב) לתור של יצירת אינדקס, כדי לקבוע את הסטטוס של הפריט (MODIFIED, NEW_ITEM, DELETED). באופן ספציפי:

   • כשמבצעים פעולת דחיפה, המחבר כולל באופן מפורש דחיפה type או contentHash.
   • אם המחבר לא כולל את type, Cloud Search משתמש אוטומטית ב-contentHash כדי לקבוע את הסטטוס של הפריט.
   • אם הפריט לא מוכר, סטטוס הפריט מוגדר כNEW_ITEM.
   • אם הפריט קיים וערכי הגיבוב (hash) זהים, הסטטוס נשאר ACCEPTED.
   • אם הפריט קיים והגיבובים שונים, הסטטוס יהיה MODIFIED.

   מידע נוסף על קביעת הסטטוס של פריט אפשר למצוא בדוגמת הקוד Traversing the GitHub repositories במדריך תחילת העבודה עם Cloud Search.

   בדרך כלל, הפעולה הזו משויכת לתהליכים של מעבר על תוכן ו/או זיהוי שינויים במחבר.

2. מחבר התוכן משתמש ב-items.poll כדי לבצע סקר של התור ולקבוע אילו פריטים יתווספו לאינדקס. ‫Cloud Search אומר למחבר אילו פריטים הכי זקוקים לאינדוקס, והם ממוינים קודם לפי קוד סטטוס ואז לפי זמן ההמתנה בתור.

3. המחבר מאחזר את הפריטים האלה מהמאגר ויוצר בקשות API של אינדקס.

4. המחבר משתמש ב-items.index כדי ליצור אינדקס לפריטים. הפריט עובר למצב ACCEPTED רק אחרי ש-Cloud Search מסיים לעבד אותו בהצלחה.

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

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

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

אסטרטגיית הסריקה המלאה משתמשת בתהליך עם שני תורים כדי ליצור אינדקס של פריטים ולזהות מחיקות. איור 2 מציג את השלבים במחיקת פריט באמצעות שני תורים של יצירת אינדקס. באיור 2 מוצג המעבר השני שבוצע באמצעות אסטרטגיית מעבר מלא. השלבים האלה משתמשים בקריאות ל-API ל-REST. למידע על קריאות SDK מקבילות, אפשר לעיין במאמר פעולות בתור (Connector SDK).

איור 2. מחיקת פריטים

הערה: ברשימת השלבים הבאה, שלבים 1 עד 4 לא מוצגים באיור 2 כי הם זהים לשלבים 1 עד 4 בתרשים הקודם, והם לא רלוונטיים לסעיף הזה. שלב 5 לא מוצג כי הקריאה ל-deleteQueueItems בתור ריק לא נכללת בהיקף של הקטע הזה. הדיאגרמה הזו מתמקדת במעבר השני.

1. במעבר הראשוני, מחבר התוכן משתמש ב-items.push כדי להעביר פריטים (מטא-נתונים וגיבוב) לתור האינדוקס, 'תור א', בתור NEW_ITEM כי הוא לא קיים בתור. לכל פריט מוקצית התווית A לציון תור A. התוכן מתווסף לאינדקס ב-Cloud Search.

   הערה: המחבר יכול להקצות תווית לתור באמצעות השדה queue של הפריט, במהלך פעולת item.push או item.index. אפשר לשנות את התווית הזו בכל פעם שהפריט נדחף מחדש או עובר אינדוקס מחדש.

2. מחבר התוכן משתמש ב-items.poll כדי לבצע שאילתות ב-queue A ולקבוע אילו פריטים יתווספו לאינדקס. ‫Cloud Search אומר למחבר אילו פריטים הכי זקוקים לאינדוקס, והם ממוינים קודם לפי קוד סטטוס ואז לפי זמן ההמתנה בתור.

3. המחבר מאחזר את הפריטים האלה מהמאגר ויוצר בקשות API של אינדקס.

4. המחבר משתמש ב-items.index כדי ליצור אינדקס לפריטים. הפריט עובר למצב ACCEPTED רק אחרי ש-Cloud Search מסיים לעבד אותו בהצלחה.

5. השיטה deleteQueueItems מופעלת בתור B. אבל לא הועברו פריטים לתור B, ולכן לא ניתן למחוק כלום.

6. במעבר המלא השני, מחבר התוכן משתמש ב-items.push כדי להעביר פריטים (מטא-נתונים וגיבוב) לתור ב':

   • כשמבצעים פעולת דחיפה, המחבר כולל באופן מפורש דחיפה type או contentHash.
   • אם המחבר לא כולל את type, Cloud Search משתמש אוטומטית ב-contentHash כדי לקבוע את הסטטוס של הפריט.
   • אם הפריט לא מוכר, סטטוס הפריט מוגדר כ-NEW_ITEM ותווית התור משתנה ל-B.
   • אם הפריט קיים וערכי הגיבוב (hash) זהים, הסטטוס נשאר ACCEPTED והתווית של התור משתנה ל-B.
   • אם הפריט קיים והגיבובים שונים, הסטטוס הופך ל-MODIFIED והתווית של התור משתנה ל-B.

7. מחבר התוכן משתמש ב-items.poll כדי לבצע סקר של התור ולקבוע אילו פריטים יתווספו לאינדקס. ‫Cloud Search אומר למחבר אילו פריטים הכי זקוקים לאינדוקס, והם ממוינים קודם לפי קוד סטטוס ואז לפי זמן ההמתנה בתור.

8. המחבר מאחזר את הפריטים האלה מהמאגר ויוצר בקשות API של אינדקס.

9. המחבר משתמש ב-items.index כדי ליצור אינדקס לפריטים. הפריט עובר למצב ACCEPTED רק אחרי ש-Cloud Search מסיים לעבד אותו בהצלחה.

10. לבסוף, הפונקציה deleteQueueItems נקראת בתור A כדי למחוק את כל הפריטים שסומנו בתווית 'A' ב-Cloud Search ועברו אינדוקס בעבר.

11. במעברים מלאים עוקבים, התור שמשמש לאינדוקס והתור שמשמש למחיקה מתחלפים.

פעולות בתור (Connector SDK)

ה-SDK של Content Connector מספק פעולות לדחיפת פריטים לתור ולשליפת פריטים מהתור.

כדי לארוז פריט ולהעביר אותו לתור, משתמשים במחלקה pushItemsbuilder.

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

פעולות בתור (REST API)

ה-API ל-REST מספק את שתי השיטות הבאות להעברת פריטים לתור ולשליפת פריטים מהתור:

• כדי להעביר פריט לתור, משתמשים ב-Items.push.
• כדי לבדוק את הפריטים בתור, משתמשים ב-Items.poll.

אפשר גם להשתמש ב-Items.index כדי להוסיף פריטים לתור במהלך יצירת האינדקס. פריטים שמועברים לתור במהלך יצירת האינדקס לא דורשים type ומקבלים אוטומטית את הסטטוס ACCEPTED.

Items.push

השיטה Items.push מוסיפה מזהים לתור. אפשר לקרוא לשיטה הזו עם ערך ספציפי של type שקובע את התוצאה של פעולת הדחיפה. רשימה של ערכי type מופיעה בשדה item.type בשיטה Items.push.

הוספת מזהה חדש גורמת להוספת רשומה חדשה עם קוד NEW_ITEM ItemStatus.

המטען הייעודי (payload) האופציונלי תמיד נשמר, נחשב לערך אטום ומוחזר מ-Items.poll.

כשמתבצעת שאילתה לגבי פריט, הוא מוזמן, כלומר אי אפשר להחזיר אותו על ידי קריאה אחרת אל Items.poll. שימוש ב-Items.push עם type בתור NOT_MODIFIED,‏ REPOSITORY_ERROR או REQUEUE, מבטל את השמירה של רשומות שנבדקו. מידע נוסף על רשומות שמורות ולא שמורות זמין בקטע Items.poll.

‫Items.push עם גיבוב

‫Google Cloud Search API תומך בציון מטא-נתונים וערכי hash של תוכן בבקשות Items.index. במקום לציין את type, אפשר לציין את המטא-נתונים ו/או את ערכי הגיבוב של התוכן באמצעות בקשת push. תור האינדוקס של Cloud Search משווה את ערכי הגיבוב שסופקו לערכים המאוחסנים שזמינים לפריט במקור הנתונים. אם יש אי התאמה, הרשומה מסומנת בסטטוס MODIFIED. אם אין פריט תואם באינדקס, הסטטוס הוא NEW_ITEM.

הערה: ערכי הגיבוב שמועברים עם בקשות Items.push לא נשמרים עם הפריט. הפריטים האלה משמשים רק כדי לקבוע אם הפריט שונה.

Items.poll

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

כברירת מחדל, יכול להיות שיוחזרו רשומות מכל קטע בתור, על סמך העדיפות. כל רשומה שמוחזרת שמורה, ולא מוחזרת על ידי קריאות אחרות אל Items.poll עד שאחד מהמקרים הבאים מתקיים:

• הזמן שהוקצב להזמנה פג.
• הערך מתווסף שוב לתור על ידי Items.index.
• הפונקציה Items.push מופעלת עם ערך type של NOT_MODIFIED,‏ REPOSITORY_ERROR או REQUEUE.