דף זה תורגם על ידי 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](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"
  }
}

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