דף זה תורגם על ידי Cloud Translation API.

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

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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

צמצום התוצאות בעזרת מאפיינים

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

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

כשמבקשים מאפיינים, 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"
  }
}

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