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 נעשה שימוש בתחביר המרת קידוד של 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 רכיבים.

גוף התשובה

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

תגובת ה-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)

תוצאות מובנות לשאילתת המשתמש. התוצאות האלו לא נספרות ביחס לגודל הדף.
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

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

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

QueryInterpretation.InterpretationType

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

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) שצריך לסמן בתו בריחה (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)

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

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

string (Timestamp format)

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

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

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

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)

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