יצירת ממשק חיפוש באמצעות Query API

ממשק ה-API של השאילתות מספק שיטות חיפוש והצעות לבניית ממשק חיפוש או להטמעת תוצאות באפליקציה.

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

בניית ממשק חיפוש

כדי ליצור ממשק חיפוש מינימלי, צריך לבצע כמה שלבים:

  1. מגדירים אפליקציית חיפוש.
  2. יוצרים פרטי כניסה של OAuth לאפליקציה.
  3. מריצים שאילתה באינדקס.
  4. הצגת תוצאות השאילתה.

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

הגדרת אפליקציית חיפוש

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

אי אפשר להגדיל את מספר מקורות הנתונים שמשמשים בשאילתה מעבר למספר המקורות שהוגדר באפליקציית החיפוש. אפשר להגביל שאילתה לקבוצת משנה של המקורות האלה באמצעות dataSourceRestrictions.

מידע נוסף זמין במאמר בנושא התאמה אישית של חוויית החיפוש.

יצירת פרטי כניסה של OAuth לאפליקציה

בנוסף לשלבים שמפורטים במאמר בנושא הגדרת גישה ל-Cloud Search API, צריך ליצור פרטי כניסה ל-OAuth עבור אפליקציית האינטרנט.

משתמשים בפרטי הכניסה כדי לבקש הרשאה בשם המשתמש. משתמשים בהיקף https://www.googleapis.com/auth/cloud_search.query.

מידע נוסף על אפשרויות OAuth זמין במאמר בנושא Google Identity Platform.

שליחת שאילתה לאינדקס

משתמשים ב-search method כדי לחפש באינדקס.

כל בקשה חייבת לכלול טקסט query ו-searchApplicationId.

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

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

הצגת תוצאות של שאילתות

בממשקי חיפוש צריך להציג את הפריט title וקישור לפריט המקורי. אפשר גם להשתמש בתקצירים ובמטא-נתונים כדי לשפר את התצוגה.

איך מטפלים בתוצאות משלימות

‫Cloud Search מחזיר תוצאות משלימות כשאין מספיק התאמות לשאילתה. השדה queryInterpretation מציין את זה. אם מוחזרות רק תוצאות משניות, הערך של InterpretationType הוא REPLACE. אם הם משולבים, זה BLEND.

כשמחזירים תוצאות משלימות, כדאי להודיע על כך למשתמש. לדוגמה, אם המשתמש מחפש REPLACE, אפשר להגיד: "לא נמצאו תוצאות שתואמות לחיפוש שלך. מוצגות תוצאות עבור שאילתות דומות".

איך מטפלים בתוצאות של אנשים

Cloud Search מחזיר מסמכים שקשורים לאנשים ולמידע על עובדים באמצעות התכונה 'חיפוש אנשים'. התוצאות מוצגות בשדה structuredResults:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

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

התאמה של עובדים ישירים מאפשרת למשתמשים לראות את העובדים הישירים של אדם מסוים. התשובה כוללת את השדה assistCardProtoHolder עם הערך cardType של RELATED_PEOPLE_ANSWER_CARD.

השבתת האופטימיזציות

אופטימיזציות כמו תוצאות משלימות מופעלות כברירת מחדל. אפשר להשבית אותם:

הדגשת קטעי טקסט

‫Cloud Search מחזיר תקציר של טקסט או HTML שעברו אינדוקס. אם יש מונחי שאילתה, matchRanges מזהה את המיקום שלהם. משתמשים בטווחים האלה כדי להדגיש טקסט.

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

בהינתן קטע הקוד הבא:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

מחרוזת ה-HTML שתתקבל היא:

This is an <span class="highlight">example</span> snippet...

מטא-נתונים מוצגים

בשדה metadata אפשר להזין מידע כמו createTime, updateTime ונתונים מובְנים. משתמשים ב-displayOptions כדי להציג נתונים מובְנים.

אחזור תוצאות נוספות

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

מיון התוצאות

משתמשים בפקודה sortOptions כדי לציין את הסדר:

  • ‫operatorName: המאפיין שלפיו יתבצע המיון.
  • ‫sortOrder: ASCENDING או DESCENDING.

רלוונטיות היא מפתח המיון המשני שמוגדר כברירת מחדל.

הוספת פילטרים

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

הפעלת מסננים ב-dataSourceRestrictions.filterOptions[]. סוגי המסננים העיקריים:

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

מסננים מורכבים משלבים כמה מסנני ערכים.

צמצום התוצאות באמצעות היבטים

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

דפוס אופייני: ‫1. שאילתה שמציינת מאפיינים של היבטים. 1. הצגת תוצאות חיפוש ומאפיינים. 1. המשתמש בוחר ערכים של היבטים. 1. חזרה על השאילתה עם מסנן על סמך הבחירות.

תוצאות של היבטים עם שדות מבוססי-מספרים שלמים

כדי לצמצם את התוצאות לפי טווחים (לדוגמה, ‫"100-200" דפים). מגדירים את isFacetable ל-true ומגדירים אפשרויות ברירת מחדל לחלוקה לקטגוריות בסכימה.

סינון התוצאות לפי גודל או תאריך המסמך

שימוש באופרטורים שמורים:

  • ‫itemsize: גודל הקובץ בבייטים.
  • ‫createddatetimestamp: תאריך היצירה.
  • ‫lastmodified: לתאריך השינוי.

הוספת הצעות

אפשר להשתמש ב-suggest API להשלמה אוטומטית על סמך היסטוריית השאילתות, אנשי הקשר ותוכן המסמך.