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

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

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

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

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

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

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

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

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

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

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

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

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

מידע נוסף על אפשרויות OAuth וספריות לקוח זמין ב[Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.

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

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

כל בקשה צריכה לכלול שני פריטי מידע: טקסט query להתאמת פריטים ומזהה searchApplicationId שמציין את אפליקציית החיפוש שבה רוצים להשתמש.

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

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

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

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

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

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

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

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

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

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

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

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

התאמה של עובדים ישירים היא תכונה של חיפוש אנשים ב-Cloud Search, שמאפשרת למשתמשים לראות את העובדים הישירים של אדם בארגון שלהם. התוצאה זמינה בשדה structuredResults.

אם השאילתה היא לגבי המנהל או העובדים הישירים של אדם מסוים, התשובה תכלול את הסמל assistCardProtoHolder בתוך structuredResults. ל-assistCardProtoHolder יש שדה בשם cardType שיהיה שווה ל-RELATED_PEOPLE_ANSWER_CARD. התשובה assistCardProtoHolder מכילה כרטיס בשם relatedPeopleAnswerCard, שמכיל את התשובה בפועל. הוא מכיל את subject (האדם שנכלל בשאילתה) ואת relatedPeople, שהם קבוצת האנשים שקשורים לנושא. השדה relationType מחזיר את הערך MANAGER או DIRECT_REPORTS.

בדוגמה הבאה מוצגת תגובה לשאילתה לגבי עובדים שמוגדרים כעובדים ישירים:

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

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

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

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

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

  • כדי להשבית את התוצאות המשלימות ברמת אפליקציית החיפוש, מגדירים את QueryInterpretationOptions.forceDisableSupplementalResults לערך true בשאילתת החיפוש.

  • כדי להשבית את התוצאות המשלימות ברמת שאילתת החיפוש, מגדירים את QueryInterpretationOptions.disableSupplementalResults לערך true בשאילתת החיפוש.

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

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

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

משתמשים ב-matchRanges כדי להדגיש את הטקסט התואם כשמעבדים את התוצאות. בדוגמה הבאה של JavaScript, קטע הקוד מומר לתגי HTML, וכל טווח תואם מוקף בתג <span>.

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 כדי להציג מידע נוסף על הפריט שהוחזר, שעשוי להיות רלוונטי למשתמשים. השדה metadata כולל את createTime וupdateTime של הפריט, וגם נתונים מובְנים שניתן להחזיר שמשויכים לפריט.

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

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

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

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

מיון התוצאות

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

  • ‫operatorName — אופרטור של מאפיין הנתונים המובְנים שלפיו יתבצע המיון. בנכסים עם כמה מפעילים, אפשר למיין רק באמצעות אופרטור השוויון הראשי.
  • ‫sortOrder – כיוון המיון, ASCENDING או DESCENDING.

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

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

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

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

כדי להוסיף מסננים בבקשה או באפליקציית חיפוש, מוסיפים את המסנן בשדה dataSourceRestrictions.filterOptions[].

יש 2 דרכים עיקריות לסנן עוד יותר את מקור הנתונים:

  • מסנני אובייקטים, דרך המאפיין filterOptions[].objectType – מגבילים את הפריטים התואמים לסוג שצוין, כפי שמוגדר בסכימה מותאמת אישית.
  • מסנני ערכים – מגבילים את הפריטים התואמים על סמך אופרטור שאילתה וערך שסופק.

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

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

{
  "query": "adventure",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>"
  },
  "dataSourceRestrictions": [
    {
      "source": {
        "name": "datasources/<data_source_id>"
      },
      "filterOptions": [
        {
          "objectType": "movie",
          "filter": {
            "compositeFilter": {
              "logicOperator": "AND"
              "subFilters": [
                {
                  "compositeFilter": {
                  "logicOperator": "OR"
                  "subFilters": [
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "G"
                        }
                      }
                    },
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "PG"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

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

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

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

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

דפוס האינטראקציה האופייני עם היבטים הוא:

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

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

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

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

אפשר גם להוסיף פילוח לתוצאות של בקשות עם שדות מבוססי-מספרים שלמים. לדוגמה, אפשר לסמן מאפיין של מספר שלם בשם book_pages כמאפיין שניתן לסינון כדי לצמצם את התוצאות של חיפוש ספרים עם 100-200 עמודים.

כשמגדירים את סכימת השדה של מאפיין מסוג מספר שלם, מגדירים את isFacetable לערך true ומוסיפים אפשרויות מתאימות של חלוקה לקטגוריות ל-integerPropertyOptions. כך אפשר לוודא שלכל מאפיין שאפשר לסנן לפי מספר שלם מוגדרות אפשרויות ברירת מחדל של חלוקה לקטגוריות.

כשמגדירים את הלוגיקה של אפשרויות החלוקה לקטגוריות, צריך לספק מערך של ערכים מצטברים שמייצגים טווחים. לדוגמה, אם משתמש הקצה מציין טווחים כמו 2, 5, 10, 100, הפילטרים ל-<2, [2-5), [5-10), [10-100), >=100 מחושבים.

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

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

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

  • כדי להשתמש בסינון לפי גודל המסמך, משתמשים ב-itemsize ומגדירים אפשרויות של חלוקה לקטגוריות.
  • כדי להשתמש בסינון לפי תאריך יצירת המסמך, משתמשים ב-createddatetimestamp.
  • כדי להשתמש בסינון לפי תאריך השינוי של המסמך, משתמשים ב-lastmodified.

פירוש של קטגוריות מאפיינים

המאפיין facetResults בתשובה לשאילתת החיפוש כולל את בקשת הסינון המדויקת של המשתמש בשדה filter לכל bucket.

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

כשמשתמש בוחר ערך אחד או יותר לסינון, צריך ליצור שאילתה חדשה עם המסננים שנבחרו ולשלוח שוב שאילתה ל-API.

הוספת הצעות

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

לדוגמה, הקריאה הבאה מחזירה הצעות לביטוי החלקי jo.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

לאחר מכן תוכלו להציג את ההצעות שמתקבלות באופן שמתאים לאפליקציה שלכם.