Query API מספק שיטות חיפוש והצעה לבניית חיפוש או הטמעת תוצאות חיפוש באפליקציה.
באפליקציות אינטרנט עם דרישות מינימליות, כדאי להשתמש בווידג'ט החיפוש. מידע נוסף זמין במאמר הבא: יצירת ממשק חיפוש עם ווידג'ט החיפוש
פיתוח ממשק חיפוש
כדי ליצור ממשק חיפוש מינימלי, נדרשים כמה שלבים:
- הגדרת אפליקציית חיפוש
- יצירת פרטי כניסה של OAuth עבור האפליקציה
- שליחת שאילתה לאינדקס
- הצגת תוצאות השאילתה
כדי לשפר את ממשק החיפוש עוד יותר, אפשר להשתמש בתכונות כמו חלוקה לדפים, מיון, סינון, מאפיינים והצעה אוטומטית.
הגדרת אפליקציית חיפוש
צריך ליצור לפחות אפליקציית חיפוש אחת שתשויך לכל אחד מהם ממשק החיפוש שיצרת, אפליקציית חיפוש מספקת את ברירת המחדל של שאילתה, כמו מקורות הנתונים שבהם צריך להשתמש, סדר המיון, מסננים ומאפיינים לבקש. במקרה הצורך, אפשר לשנות את הפרמטרים האלה באמצעות ה-API של השאילתות.
למידע נוסף על אפליקציות חיפוש, עיינו בכתובת התאמה אישית של חוויית החיפוש ב-Cloud Search
יצירת פרטי כניסה של OAuth עבור האפליקציה
בנוסף לשלבים שמפורטים הגדרת הגישה ל-Google Cloud Search API, צריך גם ליצור פרטי כניסה של OAuth עבור אפליקציית האינטרנט. הסוג של פרטי הכניסה שתיצרו תלויים בהקשר שבו משתמשים ב-API.
משתמשים בפרטי הכניסה כדי לבקש הרשאה בשם המשתמש. משתמשים ב
היקף https://www.googleapis.com/auth/cloud_search.query
כאשר מבקשים
אישור.
מידע נוסף על אפשרויות OAuth ועל ספריות לקוח זמין במאמר [פלטפורמת הזהויות של Google](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 מחזיר שני סוגים של 'תוצאות של אנשים': מסמכים שקשורים
אדם ששמו מופיע בשאילתה ופרטי העובד של אדם
שהשם שלו משמש בשאילתה. התוצאה השנייה היא פונקציה של ענן
ניתן למצוא את התכונה 'חיפוש אנשים' של חיפוש אנשים והתוצאות של שאילתה כזו נמצאות ב
ה
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
כטבלת פנים כדי לצמצם
תוצאות לחיפוש על ספרים עם "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"
}
}
אפשר להציג את ההצעות שהתקבלו בהתאם תרגום מכונה.