Method: query.search

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

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

בקשת HTTP

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

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

גוף הבקשה

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

ייצוג ב-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 של החיפוש. המזהה הבא: 19

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

ייצוג ב-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 מונחים בביטוי, כמו "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 כדי להשבית את הפרשנות של שפה טבעית. הפרשנות של שפה טבעית חלה רק על מקורות נתונים מוגדרים מראש.
enableVerbatimMode

boolean

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

boolean

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

QueryInterpretation

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

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

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

integer

המספר בפועל של התוצאות שהוחזרו על ידי השאילתה המפורשת.
interpretedQueryEstimatedResultCount

string (int64 format)

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

QueryInterpretation.InterpretationType

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

QueryInterpretation.Reason

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

SearchResult

תוצאות שמכילות מידע שעבר אינדוקס למסמך. המזהה הבא: 16

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

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

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z-normalized ויכלול 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

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

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z-normalized ויכלול 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

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

object (ResultDisplayMetadata)

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

string

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

ResultDisplayMetadata

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

string

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

object (ResultDisplayMetadata.ResultDisplayLine)

התוכן של תגי ה-meta שיוצג עם התוצאה.

ResultDisplayMetadata.ResultDisplayLine

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

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

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

הצגת שדות לתוצאות של שאילתת חיפוש

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

string

תווית התצוגה של המאפיין.
operatorName

string

שם המפעיל של הנכס.
property

object (NamedProperty)

זוג הערכים של שם המאפיין.

ResultDebugInfo

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

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

string

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

StructuredResult

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

ייצוג ב-JSON 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
שדות

שדה איחוד structured_result.

הערך structured_result יכול להיות רק אחד מהבאים:
person

object (Person)

ייצוג של אדם

SpellResult

ייצוג ב-JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
שדות
suggestedQuery

string

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

enum (SpellResult.SuggestionType)

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

object (SafeHtmlProto)

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

SpellResult.SuggestionType

סוג ההצעה שהופעלה בשאילתה.

טיפוסים בני מנייה (enum)
SUGGESTION_TYPE_UNSPECIFIED סוג ברירת המחדל של בדיקת האיות
NON_EMPTY_RESULTS_SPELL_SUGGESTION ההצעה לאיות שונתה בלי שום תוצאות. התוצאות עדיין מוצגות עבור השאילתה המקורית (שיש לה תוצאות שונות מאפס), עם הצעה לאיות שיניב תוצאות.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT הצעה לאיות מופעלת כשאין תוצאות לשאילתה המקורית. אם אין תוצאות לשאילתה המקורית, אבל יש תוצאות להצעה לתיקון האיות, אנחנו מציגים תוצאות לשאילתה עם תיקון האיות.

SafeHtmlProto

חשוב: לא בטוח לאשר את ההודעה הזו ממקור לא מהימן, כי קל לתוקף לזייף הודעות שעברו סריאליזציה ולא עומדות בחוזה הבטיחות של הסוג – למשל, היא יכולה להכיל סקריפט בשליטת התוקף. מערכת שמקבלת SafeHtmlProto סומכת באופן מרומז על היוצר של SafeHtmlProto. לכן, בדרך כלל בטוח להחזיר את ההודעה הזו בתגובות RPC, אבל בדרך כלל לא בטוח לקבל אותה בבקשות RPC.

ייצוג ב-JSON 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
שדות
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

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

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

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

ייצוג ב-JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
שדות
count

integer

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

integer

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

object (Filter)

מסנן שיועבר בבקשת החיפוש אם נבחרה הקטגוריה המתאימה.
שדה איחוד bucket_value. הטווח או הערך של הדלי שמוגדרים כפנים bucket_value יכולים להיות רק אחד מהערכים הבאים:
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)

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