- בקשת HTTP
- גוף הבקשה
- גוף התשובה
- היקפי ההרשאות
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- קטע טקסט
- MatchRange
- מטא-נתונים
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- רוצים לנסות?
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 |
מחרוזת השאילתה הגולמית. בקישור הבא אפשר לראות אופרטורים נתמכים של חיפוש בקטע צמצום החיפוש באמצעות אופרטורים |
pageSize |
המספר המקסימלי של תוצאות חיפוש שיחזרו בדף אחד. הערכים החוקיים הם בין 1 ל-100, כולל. ערך ברירת המחדל הוא 10. הערך המינימלי הוא 50 כשמבקשים תוצאות מעבר ל-2,000. |
start |
מתחיל אינדקס של התוצאות. |
dataSourceRestrictions[] |
המקורות לשימוש בשאילתות. אם לא מציינים שום אפשרות, המערכת תשתמש בכל מקורות הנתונים מאפליקציית החיפוש הנוכחית. |
facetOptions[] |
|
sortOptions |
האפשרויות למיון תוצאות החיפוש |
queryInterpretationOptions |
לפרש את שאילתת המשתמש. |
contextAttributes[] |
מאפייני הקשר של הבקשה, שישמשו לשינוי הדירוג של תוצאות החיפוש. מספר הרכיבים המקסימלי הוא 10. |
גוף התגובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול נתונים במבנה הבא:
תגובת Search API.
ייצוג JSON |
---|
{ "queryInterpretation": { object ( |
שדות | |
---|---|
queryInterpretation |
תוצאה של פרשנות השאילתה לשאילתת משתמש. שדה זה ריק אם פירוש השאילתה מושבת. |
results[] |
תוצאות משאילתת חיפוש. |
structuredResults[] |
תוצאות מובנות לשאילתת המשתמש. התוצאות האלה לא נספרות כחלק מ-pageSize. |
spellResults[] |
הצעת איות לשאילתה. |
facetResults[] |
תוצאות חוזרות של מאפיינים. |
hasMoreResults |
אם יש עוד תוצאות חיפוש שתואמות לשאילתה. |
debugInfo |
מידע על תוצאות ניפוי הבאגים לגבי התגובה. |
errorInfo |
פרטי השגיאה לגבי התשובה. |
resultCounts |
מידע מורחב על ספירת תוצאות. |
שדה איחוד
במקרים הנדירים שבהם המערכת לא יכולה לחפש בכל המסמכים, הריצו מחדש את השאילתה. הערך של |
|
resultCountEstimate |
מספר התוצאות המשוער של השאילתה הזו. |
resultCountExact |
מספר התוצאות המדויק לשאילתה הזו. |
היקפי הרשאות
כדי להשתמש בתכונה הזו יש צורך באחד מההיקפים הבאים של 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 |
סימון להשבתת הפרשנות הטבעית (NL) של שאילתות. ברירת המחדל היא False. יש להגדיר את הערך True כדי להשבית את פרשנות השפה הטבעית. הפרשנות של NL חלה רק על מקורות נתונים מוגדרים מראש. |
enableVerbatimMode |
הפעל את הסימון הזה כדי להשבית את כל האופטימיזציות הפנימיות כמו פרשנות שפה טבעית (NL) של שאילתות, אחזור תוצאות משלימות ושימוש במילים נרדפות, כולל אלה בהתאמה אישית. תרגום Nl יושבת אם אחד משני הדגלים נכון. |
disableSupplementalResults |
יש להשתמש בסימון הזה כדי להשבית תוצאות משלימות לשאילתה. ההגדרה של תוצאות משלימות שנבחרה ברמת SearchApplication תקבל עדיפות אם היא מוגדרת כ-True. |
QueryInterpretation
ייצוג JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
שדות | |
---|---|
interpretedQuery |
הפרשנות של השאילתה המשמשת בחיפוש. לדוגמה, שאילתות עם כוונה בשפה טבעית, כגון "אימייל מאת ישראל", יפורשו כ-"from:john source:mail". השדה הזה לא ימולא כשהסיבה היא NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
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 ( |
שדות | |
---|---|
title |
הכותרת של תוצאת החיפוש. |
url |
כתובת ה-URL של תוצאת החיפוש. כתובת ה-URL מכילה הפניה אוטומטית של Google לפריט עצמו. כתובת ה-URL הזו חתומה ואין לשנות אותה. |
snippet |
השרשור של כל קטעי הקוד (סיכומים) הזמינים לתוצאה הזו. |
metadata |
מטא-נתונים של תוצאת החיפוש. |
clusteredResults[] |
אם המקור מקובץ באשכולות, צריך לספק רשימה של תוצאות מקובצות. תהיה רק רמה אחת של תוצאות מקובצות. אם המקור הנוכחי לא מופעל לקיבוץ, השדה הזה יהיה ריק. |
debugInfo |
מידע על תוצאות החיפוש שקשורות לניפוי באגים. |
קטע קוד
קטע של תוצאת החיפוש, שמסכם את התוכן של הדף שהתקבל.
ייצוג JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
שדות | |
---|---|
snippet |
קטע הטקסט של המסמך. קטע הטקסט של המסמך. עשוי להכיל תו HTML בתו בריחה (escape) שיש לסמן בתו בריחה (escape) לפני העיבוד. |
matchRanges[] |
הטווחים התואמים בקטע הקוד. |
MatchRange
טווח תואם של קטע טקסט [התחלה, סיום).
ייצוג JSON |
---|
{ "start": integer, "end": integer } |
שדות | |
---|---|
start |
המיקום ההתחלתי של ההתאמה בקטע הקוד. |
end |
סוף ההתאמה בקטע הקוד. |
Metadata
מטא-נתונים של תוצאת חיפוש תואמת.
ייצוג JSON |
---|
{ "source": { object ( |
שדות | |
---|---|
source |
המקור בעל השם של התוצאה, למשל Gmail. |
mimeType |
סוג Mime של תוצאת החיפוש. |
thumbnailUrl |
כתובת ה-URL של התמונה הממוזערת של התוצאה. |
owner |
הבעלים (בדרך כלל היוצר) של המסמך או האובייקט של תוצאת החיפוש. |
createTime |
שעת היצירה של המסמך או האובייקט בתוצאת החיפוש. חותמת זמן בפורמט "זולו" RFC3339 UTC, ברזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: |
updateTime |
תאריך השינוי האחרון של האובייקט בתוצאת החיפוש. אם המאפיין לא מוגדר בפריט, הערך שיוחזר כאן יהיה ריק. אם המשתנה חותמת זמן בפורמט "זולו" RFC3339 UTC, ברזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: |
fields[] |
שדות שנוספו לאינדקס בנתונים מובְנים, שהוחזרו כנכס בעל שם גנרי. |
displayOptions |
אפשרויות המציינות כיצד להציג תוצאת חיפוש של נתונים מובנים. |
objectType |
סוג האובייקט של תוצאת החיפוש. |
ResultDisplayMetadata
ייצוג JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
שדות | |
---|---|
objectTypeLabel |
תווית התצוגה של האובייקט. |
metalines[] |
תוכן המטא-לינות שיוצג עם התוצאה. |
ResultDisplayMetadata.ResultDisplayLine
אוסף השדות שמרכיבים קו מוצג
ייצוג JSON |
---|
{
"fields": [
{
object ( |
שדות | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
שדות תצוגה עבור תוצאות query.search
ייצוג JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
שדות | |
---|---|
label |
תווית התצוגה של הנכס. |
operatorName |
שם האופרטור של הנכס. |
property |
צמד ערכי השם של הנכס. |
ResultDebugInfo
מידע על תוצאות ניפוי הבאגים.
ייצוג JSON |
---|
{ "formattedDebugInfo": string } |
שדות | |
---|---|
formattedDebugInfo |
מידע כללי על תוצאות ניפוי הבאגים בפורמט המיועד לרשת. |
StructuredResult
תוצאות מובנות שמוחזרות כחלק מבקשת החיפוש.
ייצוג JSON |
---|
{
"person": {
object ( |
שדות | |
---|---|
person |
ייצוג של אדם |
SpellResult
ייצוג JSON |
---|
{ "suggestedQuery": string } |
שדות | |
---|---|
suggestedQuery |
האיות המוצע של השאילתה. |
FacetResult
תגובה למאפיין ספציפי למקור
ייצוג JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
שדות | |
---|---|
sourceName |
שם המקור שעבורו מוחזרות תוצאות המאפיינים. לא יהיה ריק. |
objectType |
סוג האובייקט שעבורו מוחזרות תוצאות המאפיינים. יכול להיות ריק. |
operatorName |
שם האופרטור שנבחר לזיהוי. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBuckets של ערכים בתגובה שמכילים לפחות תוצאה אחת עם המסנן המתאים. |
FacetBucket
קטגוריה בתכונה היא יחידת הפעולה הבסיסית. קטגוריה יכולה לכלול ערך יחיד או טווח ערכים רציף, בהתאם לסוג השדה המסווג לקטגוריה. FacetBucket משמש כרגע רק להחזרת אובייקט התגובה.
ייצוג JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
שדות | |
---|---|
count |
מספר התוצאות שתואמות לערך הקטגוריה. הספירות מוחזרות לחיפושים רק אם מתקיימת רמת הדיוק של הספירה. שירות Cloud Search לא מבטיח שמספרי המאפיינים יופיעו בכל שאילתה, וייתכן שספירת מאפיינים תופיע רק לסירוגין, גם עבור שאילתות זהות. אל תבנה יחסי תלות בקיום של ספירת המאפיינים. במקום זאת, השתמש באחוזי ount של מאפיין שמוחזרים תמיד. |
percentage |
אחוז התוצאות שתואמות לערך הקטגוריה. הערך המוחזר הוא בין (0-100], ואם הוא שבר, הוא יעוגל כלפי מטה למספר שלם. אם הערך לא מוחזר באופן מפורש, הוא מייצג ערך באחוזים שמעוגל ל-0. האחוזים מוחזרים לכל החיפושים, אבל הם בגדר הערכה בלבד. מכיוון שהאחוזים תמיד מוחזרים, עליכם להציג אחוזים במקום ספירות. |
filter |
מסננים שיועברו בבקשת החיפוש אם נבחרה הקטגוריה המתאימה. |
value |
|
ResponseDebugInfo
מידע על תוצאות ניפוי הבאגים לגבי התגובה.
ייצוג JSON |
---|
{ "formattedDebugInfo": string } |
שדות | |
---|---|
formattedDebugInfo |
מידע כללי על תוצאות ניפוי הבאגים בפורמט המיועד לרשת. |
ErrorInfo
פרטי השגיאה לגבי התשובה.
ייצוג JSON |
---|
{
"errorMessages": [
{
object ( |
שדות | |
---|---|
errorMessages[] |
|
ErrorMessage
הודעת שגיאה לכל תגובה של המקור.
ייצוג JSON |
---|
{
"source": {
object ( |
שדות | |
---|---|
source |
|
errorMessage |
|
ResultCounts
מידע על ספירת התוצאות
ייצוג JSON |
---|
{
"sourceResultCounts": [
{
object ( |
שדות | |
---|---|
sourceResultCounts[] |
התוצאות סופרות מידע לכל מקור עם תוצאות. |
SourceResultCount
מידע על ספירת תוצאות לפי מקור.
ייצוג JSON |
---|
{ "source": { object ( |
שדות | |
---|---|
source |
המקור שאליו משויך המידע של ספירת התוצאות. |
hasMoreResults |
אם יש תוצאות חיפוש נוספות למקור הזה. |
שדה איחוד הערך של |
|
resultCountEstimate |
מספר התוצאות המשוער של המקור הזה. |
resultCountExact |
מספר התוצאות המדויק עבור המקור הזה. |