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

קטע הקוד הבא מציג שאילתה למקור נתוני הסרט של הסרט 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": {...}
  }]
}

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

התאמה של עובדים ישירים היא תכונה של חיפוש אנשים ב-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[].

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

  • מסנני אובייקטים, באמצעות הנכס 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"
  }
]

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

אפשר גם לבקש תוצאות עם פיצ'רים של חלוקה לפי פנים (facet) עם שדות שמבוססים על מספרים שלמים. לדוגמה, אפשר לסמן מאפיין שלם בשם 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.

הוספת הצעות

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

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

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

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