יצירת ממשק חיפוש באמצעות 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"}.

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

משתמשים ב-method 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 כ-Facetable כדי לצמצם את התוצאות של חיפוש לגבי ספרים עם דפים עם הערך '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.

הוספת הצעות

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

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

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

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