Method: query.search

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

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

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של 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 מונחים בביטוי בשאילתה, כמו "result count exact" במירכאות כפולות.

  • כשמספר רשימות 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 תושבת אם אחד משני הדגלים יהיה True.
disableSupplementalResults

boolean

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

QueryInterpretation

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

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

הסיבה לפרשנות של השאילתה. השדה הזה לא יהיה UNSPECIFIED אם סוג הפרשנות לא יהיה NONE.

QueryInterpretation.InterpretationType

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

QueryInterpretation.Reason

טיפוסים בני מנייה (enum)
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) שצריך לבטל את התו בריחה לפני העיבוד.
matchRanges[]

object (MatchRange)

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

MatchRange

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

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

integer

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

integer

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

מטא-נתונים

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

ייצוג ב-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)

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

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

string (Timestamp format)

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

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

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