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 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 است که نتایجی بیش از 2000 درخواست شود.

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 )

نتایج ساختار یافته برای پرس و جو کاربر. این نتایج در برابر 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) پرچم گذاری کنید. پیش‌فرض نادرست است، برای غیرفعال کردن تفسیر زبان طبیعی روی true تنظیم کنید. تفسیر NL فقط برای منابع داده از پیش تعریف شده اعمال می شود.

enableVerbatimMode

boolean

این پرچم را فعال کنید تا همه بهینه‌سازی‌های داخلی مانند تفسیر جستارهای زبان طبیعی (NL)، بازیابی نتایج تکمیلی و استفاده از مترادف‌ها از جمله موارد سفارشی را خاموش کند. اگر یکی از دو پرچم درست باشد، تفسیر Nl غیرفعال خواهد شد.

disableSupplementalResults

boolean

از این پرچم برای غیرفعال کردن نتایج تکمیلی برای یک پرس و جو استفاده کنید. اگر روی True تنظیم شود، تنظیمات نتایج تکمیلی انتخاب شده در سطح SearchApplication اولویت خواهد داشت.

Query Interpretation

نمایندگی 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 )

دلیل تفسیر پرس و جو. اگر نوع تفسیر NONE نباشد، این فیلد نامشخص نخواهد بود.

QueryInterpretation.InterpretationType

Enums
NONE نه از تفسیر زبان طبیعی و نه نسخه گسترده تر از پرس و جو برای واکشی نتایج جستجو استفاده نمی شود.
BLEND نتایج حاصل از پرس و جو اصلی با نتایج دیگر ترکیب می شود. دلیل ترکیب این نتایج دیگر با نتایج جستجوی اصلی در قسمت "دلیل" زیر پر شده است.
REPLACE نتایج حاصل از پرس و جو اصلی جایگزین می شوند. دلیل جایگزینی نتایج جستجوی اصلی در قسمت "دلیل" زیر پر شده است.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT تفسیر زبان طبیعی پرس و جو برای واکشی نتایج جستجو استفاده می شود.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY شباهت اصطلاحات پرس و جو و سند برای گسترش انتخابی پرس و جو برای بازیابی نتایج جستجوی اضافی استفاده می شود زیرا نتایج کافی برای درخواست کاربر پیدا نشد. پرس و جوی تفسیر شده برای این مورد خالی خواهد بود.

نتیجه جستجو

نتایج حاوی اطلاعات نمایه شده برای یک سند.

نمایندگی 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 فراری باشد که باید قبل از رندر کردن، از آن حذف شود.

matchRanges[]

object ( MatchRange )

محدوده های منطبق در قطعه.

Match Range

محدوده همسان یک قطعه [شروع، پایان).

نمایندگی 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

نشانی اینترنتی تصویر کوچک نتیجه.

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 برای محاسبه تازگی استفاده می شود و تنظیم نشده است، این مقدار به طور پیش فرض 2 سال از زمان فعلی است.

مهر زمانی در قالب 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

اطلاعات اشکال زدایی عمومی برای نمایش فرمت شده است.

Structured Result

نتایج ساختاریافته ای که به عنوان بخشی از درخواست جستجو برگردانده می شوند.

نمایندگی 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

اطلاعات اشکال زدایی عمومی برای نمایش فرمت شده است.

اطلاعات خطا

اطلاعات خطا در مورد پاسخ.

نمایندگی JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
فیلدها
errorMessages[]

object ( ErrorMessage )

پیام خطا

پیام خطا در هر پاسخ منبع.

نمایندگی JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
فیلدها
source

object ( Source )

errorMessage

string

تعداد نتایج

اطلاعات شمارش نتایج

نمایندگی 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)

شمارش دقیق نتیجه برای این منبع.