Method: query.search

Cloud Search Query API מספק את שיטת החיפוש, שמחזירה את התוצאות הרלוונטיות ביותר משאילתת משתמש. התוצאות יכולות להגיע מאפליקציות של Google Workspace, כמו Gmail או Google Drive, או מנתונים שהוספת לאינדקס מצד שלישי.

הערה: כדי להפעיל את ה-API הזה, נדרש חשבון רגיל של משתמש קצה. חשבון שירות לא יכול לשלוח בקשות API של שאילתה באופן ישיר. כדי להשתמש בחשבון שירות לביצוע שאילתות, צריך להגדיר הענקת סמכויות ברמת הדומיין ב-Google Workspace.

בקשת HTTP

POST https://cloudsearch.googleapis.com/v1/query/search

בכתובת ה-URL נעשה שימוש בתחביר המרת gRPC.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "requestOptions": {
    object (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
שדות
requestOptions

object (RequestOptions)

אפשרויות בקשה, כמו אפליקציית החיפוש ואזור הזמן של המשתמש.
query

string

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

integer

המספר המקסימלי של תוצאות חיפוש שיחזרו בדף אחד. הערכים החוקיים הם בין 1 ל-100, כולל. ערך ברירת המחדל הוא 10. הערך המינימלי הוא 50 כשמבקשים תוצאות מעבר ל-2,000.
start

integer

מתחיל אינדקס של התוצאות.
dataSourceRestrictions[]

object (DataSourceRestriction)

המקורות לשימוש בשאילתות. אם לא מציינים שום אפשרות, המערכת תשתמש בכל מקורות הנתונים מאפליקציית החיפוש הנוכחית.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

האפשרויות למיון תוצאות החיפוש
queryInterpretationOptions

object (QueryInterpretationOptions)

לפרש את שאילתת המשתמש.
contextAttributes[]

object (ContextAttribute)

מאפייני הקשר של הבקשה, שישמשו לשינוי הדירוג של תוצאות החיפוש. מספר הרכיבים המקסימלי הוא 10.

גוף התגובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול נתונים במבנה הבא:

תגובת Search API.

ייצוג JSON 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
שדות
queryInterpretation

object (QueryInterpretation)

תוצאה של פרשנות השאילתה לשאילתת משתמש. שדה זה ריק אם פירוש השאילתה מושבת.
results[]

object (SearchResult)

תוצאות משאילתת חיפוש.
structuredResults[]

object (StructuredResult)

תוצאות מובנות לשאילתת המשתמש. התוצאות האלה לא נספרות כחלק מ-pageSize.
spellResults[]

object (SpellResult)

הצעת איות לשאילתה.
facetResults[]

object (FacetResult)

תוצאות חוזרות של מאפיינים.
hasMoreResults

boolean

אם יש עוד תוצאות חיפוש שתואמות לשאילתה.
debugInfo

object (ResponseDebugInfo)

מידע על תוצאות ניפוי הבאגים לגבי התגובה.
errorInfo

object (ErrorInfo)

פרטי השגיאה לגבי התשובה.
resultCounts

object (ResultCounts)

מידע מורחב על ספירת תוצאות.

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

  • כשהשאילתה מכילה יותר מ-2 מונחים בביטוי, למשל 'ספירת תוצאות מדויקת' במירכאות.

  • כאשר מספר הרשימות של בקרת גישה (ACL) של תוצאות חיפוש ייחודיות להערכה גדול מדי לחישוב בתוך זמן אחזור סביר.

במקרים הנדירים שבהם המערכת לא יכולה לחפש בכל המסמכים, הריצו מחדש את השאילתה. הערך של result_count יכול להיות רק אחת מהאפשרויות הבאות:
resultCountEstimate

string (int64 format)

מספר התוצאות המשוער של השאילתה הזו.
resultCountExact

string (int64 format)

מספר התוצאות המדויק לשאילתה הזו.

היקפי הרשאות

כדי להשתמש בתכונה הזו יש צורך באחד מההיקפים הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

למידע נוסף, ניתן לעיין במדריך ההרשאות.

QueryInterpretationOptions

לפרש שאילתות של משתמשים.

ייצוג JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
שדות
disableNlInterpretation

boolean

סימון להשבתת הפרשנות הטבעית (NL) של שאילתות. ברירת המחדל היא False. יש להגדיר את הערך True כדי להשבית את פרשנות השפה הטבעית. הפרשנות של NL חלה רק על מקורות נתונים מוגדרים מראש.
enableVerbatimMode

boolean

הפעל את הסימון הזה כדי להשבית את כל האופטימיזציות הפנימיות כמו פרשנות שפה טבעית (NL) של שאילתות, אחזור תוצאות משלימות ושימוש במילים נרדפות, כולל אלה בהתאמה אישית. תרגום Nl יושבת אם אחד משני הדגלים נכון.
disableSupplementalResults

boolean

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

QueryInterpretation

ייצוג JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
שדות
interpretedQuery

string

הפרשנות של השאילתה המשמשת בחיפוש. לדוגמה, שאילתות עם כוונה בשפה טבעית, כגון "אימייל מאת ישראל", יפורשו כ-"from:john source:mail". השדה הזה לא ימולא כשהסיבה היא NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

הסיבה לפירוש השאילתה. השדה הזה לא יהיה 'לא צוין' אם סוג הפרשנות אינו 'ללא'.

QueryInterpretation.InterpretationType

טיפוסים בני מנייה (enums)
NONE לא נעשה שימוש בפירוש של השפה הטבעית או בגרסה רחבה יותר של השאילתה כדי לאחזר את תוצאות החיפוש.
BLEND התוצאות מהשאילתה המקורית משולבות עם תוצאות אחרות. הסיבה לשילוב התוצאות האחרות עם התוצאות מהשאילתה המקורית מאוכלסת בשדה 'סיבה' שלמטה.
REPLACE התוצאות מהשאילתה המקורית יוחלפו. הסיבה להחלפת התוצאות מהשאילתה המקורית מאוכלסת בשדה 'סיבה' שבהמשך.

QueryInterpretation.Reason

טיפוסים בני מנייה (enums)
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT אחזור תוצאות החיפוש מתבצע לפי הפרשנות הטבעית של השאילתה.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY הדמיון בין מונחי שאילתות למסמכים משמש להרחבה סלקטיבית של השאילתה במטרה לאחזר תוצאות חיפוש נוספות, מכיוון שלא נמצאו מספיק תוצאות עבור שאילתת המשתמש. במקרה הזה, השאילתה שפורשה תהיה ריקה.

SearchResult

תוצאות שמכילות מידע שנוסף לאינדקס של מסמך.

ייצוג JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
שדות
title

string

הכותרת של תוצאת החיפוש.
url

string

כתובת ה-URL של תוצאת החיפוש. כתובת ה-URL מכילה הפניה אוטומטית של Google לפריט עצמו. כתובת ה-URL הזו חתומה ואין לשנות אותה.
snippet

object (Snippet)

השרשור של כל קטעי הקוד (סיכומים) הזמינים לתוצאה הזו.
metadata

object (Metadata)

מטא-נתונים של תוצאת החיפוש.
clusteredResults[]

object (SearchResult)

אם המקור מקובץ באשכולות, צריך לספק רשימה של תוצאות מקובצות. תהיה רק רמה אחת של תוצאות מקובצות. אם המקור הנוכחי לא מופעל לקיבוץ, השדה הזה יהיה ריק.
debugInfo

object (ResultDebugInfo)

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

קטע קוד

קטע של תוצאת החיפוש, שמסכם את התוכן של הדף שהתקבל.

ייצוג JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
שדות
snippet

string

קטע הטקסט של המסמך. קטע הטקסט של המסמך. עשוי להכיל תו HTML בתו בריחה (escape) שיש לסמן בתו בריחה (escape) לפני העיבוד.
matchRanges[]

object (MatchRange)

הטווחים התואמים בקטע הקוד.

MatchRange

טווח תואם של קטע טקסט [התחלה, סיום).

ייצוג JSON 
{
  "start": integer,
  "end": integer
}
שדות
start

integer

המיקום ההתחלתי של ההתאמה בקטע הקוד.
end

integer

סוף ההתאמה בקטע הקוד.

Metadata

מטא-נתונים של תוצאת חיפוש תואמת.

ייצוג JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
שדות
source

object (Source)

המקור בעל השם של התוצאה, למשל Gmail.
mimeType

string

סוג Mime של תוצאת החיפוש.
thumbnailUrl

string

כתובת ה-URL של התמונה הממוזערת של התוצאה.
owner

object (Person)

הבעלים (בדרך כלל היוצר) של המסמך או האובייקט של תוצאת החיפוש.
createTime

string (Timestamp format)

שעת היצירה של המסמך או האובייקט בתוצאת החיפוש.

חותמת זמן בפורמט "זולו" RFC3339 UTC, ברזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

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

חותמת זמן בפורמט "זולו" RFC3339 UTC, ברזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

שדות שנוספו לאינדקס בנתונים מובְנים, שהוחזרו כנכס בעל שם גנרי.
displayOptions

object (ResultDisplayMetadata)

אפשרויות המציינות כיצד להציג תוצאת חיפוש של נתונים מובנים.
objectType

string

סוג האובייקט של תוצאת החיפוש.

ResultDisplayMetadata

ייצוג JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
שדות
objectTypeLabel

string

תווית התצוגה של האובייקט.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

תוכן המטא-לינות שיוצג עם התוצאה.

ResultDisplayMetadata.ResultDisplayLine

אוסף השדות שמרכיבים קו מוצג

ייצוג JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
שדות
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

שדות תצוגה עבור תוצאות query.search

ייצוג JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
שדות
label

string

תווית התצוגה של הנכס.
operatorName

string

שם האופרטור של הנכס.
property

object (NamedProperty)

צמד ערכי השם של הנכס.

ResultDebugInfo

מידע על תוצאות ניפוי הבאגים.

ייצוג JSON 
{
  "formattedDebugInfo": string
}
שדות
formattedDebugInfo

string

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

StructuredResult

תוצאות מובנות שמוחזרות כחלק מבקשת החיפוש.

ייצוג JSON 
{
  "person": {
    object (Person)
  }
}
שדות
person

object (Person)

ייצוג של אדם

SpellResult

ייצוג JSON 
{
  "suggestedQuery": string
}
שדות
suggestedQuery

string

האיות המוצע של השאילתה.

FacetResult

תגובה למאפיין ספציפי למקור

ייצוג JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
שדות
sourceName

string

שם המקור שעבורו מוחזרות תוצאות המאפיינים. לא יהיה ריק.
objectType

string

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

string

שם האופרטור שנבחר לזיהוי. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

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

FacetBucket

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

ייצוג JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
שדות
count

integer

מספר התוצאות שתואמות לערך הקטגוריה. הספירות מוחזרות לחיפושים רק אם מתקיימת רמת הדיוק של הספירה. שירות Cloud Search לא מבטיח שמספרי המאפיינים יופיעו בכל שאילתה, וייתכן שספירת מאפיינים תופיע רק לסירוגין, גם עבור שאילתות זהות. אל תבנה יחסי תלות בקיום של ספירת המאפיינים. במקום זאת, השתמש באחוזי ount של מאפיין שמוחזרים תמיד.
percentage

integer

אחוז התוצאות שתואמות לערך הקטגוריה. הערך המוחזר הוא בין (0-100], ואם הוא שבר, הוא יעוגל כלפי מטה למספר שלם. אם הערך לא מוחזר באופן מפורש, הוא מייצג ערך באחוזים שמעוגל ל-0. האחוזים מוחזרים לכל החיפושים, אבל הם בגדר הערכה בלבד. מכיוון שהאחוזים תמיד מוחזרים, עליכם להציג אחוזים במקום ספירות.
filter

object (Filter)

מסננים שיועברו בבקשת החיפוש אם נבחרה הקטגוריה המתאימה.
value

object (Value)

ResponseDebugInfo

מידע על תוצאות ניפוי הבאגים לגבי התגובה.

ייצוג JSON 
{
  "formattedDebugInfo": string
}
שדות
formattedDebugInfo

string

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

ErrorInfo

פרטי השגיאה לגבי התשובה.

ייצוג JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
שדות
errorMessages[]

object (ErrorMessage)

ErrorMessage

הודעת שגיאה לכל תגובה של המקור.

ייצוג JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
שדות
source

object (Source)
errorMessage

string

ResultCounts

מידע על ספירת התוצאות

ייצוג JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
שדות
sourceResultCounts[]

object (SourceResultCount)

התוצאות סופרות מידע לכל מקור עם תוצאות.

SourceResultCount

מידע על ספירת תוצאות לפי מקור.

ייצוג JSON 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
שדות
source

object (Source)

המקור שאליו משויך המידע של ספירת התוצאות.
hasMoreResults

boolean

אם יש תוצאות חיפוש נוספות למקור הזה.

שדה איחוד result_count.

הערך של result_count יכול להיות רק אחת מהאפשרויות הבאות:
resultCountEstimate

string (int64 format)

מספר התוצאות המשוער של המקור הזה.
resultCountExact

string (int64 format)

מספר התוצאות המדויק עבור המקור הזה.