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

ה-Query 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 לזיהוי המזהה של אפליקציית החיפוש.

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

{
  "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": {...}
  }]
}

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

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

  • כדי להשבית את כל האופטימיזציות ברמת אפליקציית החיפוש, כולל תוצאות משלימות, מילים נרדפות ותיקוני איות, יש להגדיר את האפליקציה 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[].

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

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

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

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

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