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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   • כשמבצעים פעולת push, המחבר כולל באופן מפורש push 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 כדי לבצע סקר בתור A ולקבוע אילו פריטים יתווספו לאינדקס. ‫Cloud Search אומר למחבר אילו פריטים הכי זקוקים לאינדוקס, והם ממוינים קודם לפי קוד סטטוס ואז לפי זמן ההמתנה בתור.

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

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

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

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

   • כשמבצעים פעולת push, המחבר כולל באופן מפורש 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.