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

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

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

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

• ניתן לתת עדיפות לפריטים בתור לפי סטטוס הפריט.

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

'הבאים בתור' הוא תווית שהוקצתה לפריט שנוסף לאינדקס, כמו 'ברירת מחדל' לתור ברירת המחדל או '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 משתמש באופן אוטומטי בשדה contentHash כדי לקבוע את סטטוס הפריט.
   • אם הפריט לא מזוהה, סטטוס הפריט מוגדר כ-NEW_ITEM.
   • אם הפריט קיים וערכי הגיבוב תואמים, הסטטוס יישמר כ-ACCEPTED.
   • אם הפריט קיים והגיבובים שונים, הסטטוס יהפוך לMODIFIED.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ה-SDK של מחבר התוכן מספק פעולות לדחיפה של פריטים לתור ולשליפת פריטים ממנו.

כדי לארוז פריט ולדחוף אותו לתור, משתמשים במחלקת ה-builder pushItems.

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

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

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

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

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

Items.push

השיטה Items.push מוסיפה מזהים לתור. אפשר להפעיל את השיטה הזו עם ערך ספציפי של type שקובע את התוצאה של פעולת ה-push. רשימה של ערכי type מופיעה בשדה item.type ב-method‏ 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 תומך בהגדרת מטא-נתונים וערכים של גיבוב תוכן בבקשות Items.index. במקום לציין את type, אפשר לציין את ערכי הגיבוב של המטא-נתונים ו/או התוכן באמצעות בקשת push. בתור ההוספה לאינדקס של Cloud Search מתבצעת השוואה בין ערכי הגיבוב שסופקו לבין הערכים השמורים שזמינים לפריט במקור הנתונים. אם אין התאמה, הרשומה מסומנת כ-MODIFIED. אם הפריט התואם לא קיים באינדקס, הסטטוס הוא NEW_ITEM.

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

Items.poll

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

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

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