ב-query API יש שיטות חיפוש והצעות לבניית ממשק חיפוש או להטמעת תוצאות חיפוש באפליקציה.
אם מדובר באפליקציות אינטרנט עם דרישות מינימליות, כדאי להשתמש בווידג'ט החיפוש. למידע נוסף, ראו יצירת ממשק חיפוש באמצעות ווידג'ט החיפוש.
בניית ממשק חיפוש
בניית ממשק חיפוש מינימלי מצריכה מספר שלבים:
- הגדרה של אפליקציית חיפוש
- יצירת פרטי כניסה של OAuth לאפליקציה
- שליחת שאילתה על האינדקס
- הצגת תוצאות השאילתה
תוכלו לשפר עוד יותר את ממשק החיפוש באמצעות תכונות כמו דפדוף, מיון, סינון, מאפיינים והצעה אוטומטית.
הגדרה של אפליקציית חיפוש
עליכם ליצור לפחות אפליקציית חיפוש אחת שתשויך לכל ממשק חיפוש שתיצרו. אפליקציית חיפוש מספקת את הפרמטרים שמוגדרים כברירת מחדל לשאילתה, כמו מקורות הנתונים שבהם צריך להשתמש, סדר המיון, המסננים והמאפיינים שיש לבקש. במקרה הצורך, אפשר לשנות את הפרמטרים האלה באמצעות ה-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 מחשבת את הערכים הנפוצים ביותר של הנכסים שהתבקשו מבין הפריטים התואמים. הערכים האלה מוחזרים בתגובה. השתמשו בערכים האלה כדי ליצור מסננים שמצמצמים את התוצאות בשאילתות הבאות.
דפוס האינטראקציה האופייני עם היבטים הוא:
- יוצרים שאילתה ראשונית שמציינת אילו מאפיינים לכלול בתוצאות המאפיינים.
- עיבוד של תוצאות החיפוש והמאפיינים.
- המשתמש בוחר ערך מאפיין אחד או יותר כדי לצמצם את התוצאות.
- חוזרים על השאילתה עם מסנן המבוסס על הערכים שנבחרו.
לדוגמה, כדי להפעיל חידוד של שאילתות לסרטים לפי שנה ודירוג 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"
}
}
לאחר מכן תוכלו להציג את ההצעות הרלוונטיות בהתאם לאפליקציה שלכם.