- درخواست HTTP
- درخواست بدنه
- بدنه پاسخ
- دامنههای مجوز
- گزینههای تفسیر پرسوجو
- تفسیر پرسوجو
- نوع تفسیر پرسوجو
- تفسیر پرس و جو. دلیل
- نتیجه جستجو
- قطعه کد
- محدوده تطابق
- فراداده
- نمایش نتایجفراداده
- فرادادهی نمایش نتیجه.خط نمایش نتیجه
- ResultDisplayMetadata.ResultDisplayField
- اطلاعات اشکالزدایی نتیجه
- نتیجه ساختاریافته
- نتیجه طلسم
- نوع پیشنهاد.نتیجه طلسم
- SafeHmlProto
- نتیجه چهره
- فیست باکت
- اطلاعات اشکالزدایی پاسخ
- اطلاعات خطا
- پیام خطا
- شمارش نتایج
- تعداد نتایج منبع
- امتحانش کن!
رابط برنامهنویسی کاربردی جستجوی ابری (Cloud Search query API) روشی برای جستجو ارائه میدهد که مرتبطترین نتایج را از یک جستجوی کاربر برمیگرداند. این نتایج میتوانند از برنامههای Google Workspace مانند Gmail یا Google Drive یا از دادههایی که شما از یک شخص ثالث فهرستبندی کردهاید، حاصل شوند.
توجه: این API برای اجرا به یک حساب کاربری نهایی استاندارد نیاز دارد. یک حساب کاربری سرویس نمیتواند درخواستهای API پرسوجو را مستقیماً انجام دهد؛ برای استفاده از یک حساب کاربری سرویس برای انجام پرسوجوها، تفویض اختیار در سطح دامنه Google Workspace را تنظیم کنید.
درخواست HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
این URL از سینتکس Transcoding در gRPC استفاده میکند.
درخواست بدنه
بدنه درخواست شامل دادههایی با ساختار زیر است:
| نمایش JSON |
|---|
{ "requestOptions": { object ( |
| فیلدها | |
|---|---|
requestOptions | گزینههایی مانند برنامه جستجو و منطقه زمانی کاربر را درخواست کنید. |
query | رشته جستجوی خام. اپراتورهای جستجوی پشتیبانی شده را در بخش جستجوی خود را با اپراتورها محدود کنید، مشاهده کنید. |
pageSize | حداکثر تعداد نتایج جستجو برای نمایش در یک صفحه. مقادیر معتبر بین ۱ تا ۱۰۰ هستند، شامل. مقدار پیشفرض ۱۰ است. حداقل مقدار ۵۰ است وقتی نتایجی فراتر از ۲۰۰۰ درخواست میشود. |
start | شاخص شروع نتایج. |
dataSourceRestrictions[] | منابعی که برای پرسوجو استفاده میشوند. در صورت عدم مشخص شدن، از تمام منابع داده از برنامه جستجوی فعلی استفاده میشود. |
facetOptions[] | |
sortOptions | گزینههای مرتبسازی نتایج جستجو |
queryInterpretationOptions | گزینههایی برای تفسیر پرسوجوی کاربر. |
contextAttributes[] | ویژگیهای زمینهای برای درخواستی که برای تنظیم رتبهبندی نتایج جستجو استفاده خواهد شد. حداکثر تعداد عناصر ۱۰ است. |
بدنه پاسخ
پاسخ API جستجو. شناسه بعدی: ۱۹
در صورت موفقیت، بدنه پاسخ شامل دادههایی با ساختار زیر است:
| نمایش JSON |
|---|
{ "queryInterpretation": { object ( |
| فیلدها | |
|---|---|
queryInterpretation | نتیجه تفسیر پرسوجو برای پرسوجوی کاربر. اگر تفسیر پرسوجو غیرفعال باشد، خالی است. |
results[] | نتایج حاصل از یک عبارت جستجو. |
structuredResults[] | نتایج ساختاریافته برای جستجوی کاربر. این نتایج در محاسبهی اندازهی صفحه لحاظ نمیشوند. |
spellResults[] | املای پیشنهادی برای عبارت جستجو شده. |
facetResults[] | نتایج مکرر وجهی. |
hasMoreResults | اینکه آیا نتایج جستجوی بیشتری مطابق با عبارت جستجو شده وجود دارد یا خیر. |
debugInfo | اطلاعات اشکالزدایی در مورد پاسخ. |
errorInfo | اطلاعات خطا در مورد پاسخ. |
resultCounts | اطلاعات شمارش نتایج گسترشیافته. |
فیلد یونیون
در موارد نادری که سیستم قادر به جستجو در تمام اسناد نیست، پرس و جو را دوباره اجرا کنید. | |
resultCountEstimate | تعداد نتایج تخمینی برای این پرس و جو. |
resultCountExact | تعداد دقیق نتایج برای این پرس و جو. |
دامنههای مجوز
به یکی از حوزههای OAuth زیر نیاز دارد:
-
https://www.googleapis.com/auth/cloud_search.query -
https://www.googleapis.com/auth/cloud_search
برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.
گزینههای تفسیر پرسوجو
گزینههایی برای تفسیر پرسوجوی کاربر.
| نمایش JSON |
|---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
| فیلدها | |
|---|---|
disableNlInterpretation | برای غیرفعال کردن تفسیر زبان طبیعی (NL) از پرسوجوها، علامتگذاری کنید. پیشفرض نادرست است، برای غیرفعال کردن تفسیر زبان طبیعی، روی درست تنظیم کنید. تفسیر NL فقط برای منابع داده از پیش تعریفشده اعمال میشود. |
enableVerbatimMode | این پرچم را فعال کنید تا تمام بهینهسازیهای داخلی مانند تفسیر پرسوجوها به زبان طبیعی (NL)، بازیابی نتایج تکمیلی و استفاده از مترادفها از جمله مترادفهای سفارشی غیرفعال شوند. اگر هر یک از دو پرچم درست باشد، تفسیر Nl غیرفعال خواهد شد. |
disableSupplementalResults | از این پرچم برای غیرفعال کردن نتایج تکمیلی برای یک پرسوجو استفاده کنید. تنظیمات نتایج تکمیلی انتخاب شده در سطح SearchApplication در صورت تنظیم روی True، اولویت خواهند داشت. |
تفسیر پرسوجو
| نمایش JSON |
|---|
{ "interpretedQuery": string, "interpretationType": enum ( |
| فیلدها | |
|---|---|
interpretedQuery | تفسیر عبارت جستجو شده در جستجو. برای مثال، عبارتهای جستجو با هدف زبان طبیعی مانند "email from john" به صورت "from:john source:mail" تفسیر میشوند. این فیلد زمانی که دلیل NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY باشد، پر نخواهد شد. |
interpretationType | |
reason | دلیل تفسیر پرسوجو. اگر نوع تفسیر NONE نباشد، این فیلد نامشخص (UNSPECIFIED) نخواهد بود. |
interpretedQueryActualResultCount | تعداد واقعی نتایج برگردانده شده توسط کوئری تفسیر شده. |
interpretedQueryEstimatedResultCount | تعداد تخمینی نتایج برگردانده شده توسط پرس و جوی تفسیر شده. |
نوع تفسیر پرسوجو
| انومها | |
|---|---|
NONE | نه از تفسیر زبان طبیعی و نه از نسخه گستردهتر عبارت جستجو برای دریافت نتایج جستجو استفاده نمیشود. |
BLEND | نتایج حاصل از جستجوی اصلی با نتایج دیگر ترکیب میشوند. دلیل ترکیب این نتایج دیگر با نتایج جستجوی اصلی در فیلد «دلیل» زیر وارد شده است. |
REPLACE | نتایج حاصل از جستجوی اصلی جایگزین میشوند. دلیل جایگزینی نتایج جستجوی اصلی در فیلد «دلیل» زیر وارد میشود. |
تفسیر پرس و جو. دلیل
| انومها | |
|---|---|
UNSPECIFIED | |
QUERY_HAS_NATURAL_LANGUAGE_INTENT | تفسیر زبان طبیعی از پرس و جو برای دریافت نتایج جستجو استفاده میشود. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY | از تشابه اصطلاحات پرسوجو و سند برای گسترش انتخابی پرسوجو به منظور بازیابی نتایج جستجوی بیشتر استفاده میشود، زیرا نتایج کافی برای پرسوجوی کاربر یافت نشده است. پرسوجوی تفسیر شده در این مورد خالی خواهد بود. |
نتیجه جستجو
نتایجی که حاوی اطلاعات فهرستبندی شده برای یک سند هستند. شناسه بعدی: ۱۶
| نمایش JSON |
|---|
{ "title": string, "url": string, "snippet": { object ( |
| فیلدها | |
|---|---|
title | عنوان نتیجه جستجو. |
url | آدرس اینترنتی نتیجه جستجو. این آدرس اینترنتی حاوی یک ریدایرکت گوگل به مورد اصلی است. این آدرس اینترنتی امضا شده است و نباید تغییر کند. |
snippet | پیوستگی تمام خلاصهها (snippets) موجود برای این نتیجه. |
metadata | فراداده نتیجه جستجو. |
clusteredResults[] | اگر منبع خوشهای است، فهرستی از نتایج خوشهای ارائه دهید. فقط یک سطح از نتایج خوشهای وجود خواهد داشت. اگر منبع فعلی برای خوشهبندی فعال نشده باشد، این فیلد خالی خواهد بود. |
debugInfo | اطلاعات اشکالزدایی در مورد این نتیجه جستجو. |
قطعه کد
قطعهای از نتیجه جستجو که خلاصهای از محتوای صفحه نتیجه را نشان میدهد.
| نمایش JSON |
|---|
{
"snippet": string,
"matchRanges": [
{
object ( |
| فیلدها | |
|---|---|
snippet | قطعهای از سند. ممکن است حاوی کاراکترهای HTML از رده خارج شده باشد که باید قبل از رندر شدن، از حالت اسکیپ خارج شوند. |
matchRanges[] | محدودههای منطبق در قطعه کد. |
محدوده تطابق
محدوده منطبق با یک قطعه کد [شروع، پایان].
| نمایش JSON |
|---|
{ "start": integer, "end": integer } |
| فیلدها | |
|---|---|
start | موقعیت شروع تطابق در قطعه کد. |
end | پایان مسابقه در قطعه کد. |
فراداده
فرادادهی یک نتیجهی جستجوی منطبق.
| نمایش JSON |
|---|
{ "source": { object ( |
| فیلدها | |
|---|---|
source | منبع نامگذاری شده برای نتیجه، مانند Gmail. |
mimeType | نوع MIME نتیجه جستجو. |
thumbnailUrl | URL تصویر کوچک نتیجه. |
owner | مالک (معمولاً سازنده) سند یا شیء نتیجه جستجو. |
createTime | زمان ایجاد این سند یا شیء در نتیجه جستجو. از RFC 3339 استفاده میکند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده میکند. آفستهای غیر از "Z" نیز پذیرفته میشوند. مثالها: |
updateTime | آخرین تاریخ تغییر برای شیء در نتیجه جستجو. اگر در مورد تنظیم نشده باشد، مقدار برگردانده شده در اینجا خالی است. وقتی از از RFC 3339 استفاده میکند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده میکند. آفستهای غیر از "Z" نیز پذیرفته میشوند. مثالها: |
fields[] | فیلدهای فهرستبندیشده در دادههای ساختاریافته، که به عنوان یک ویژگی با نام عمومی بازگردانده میشوند. |
displayOptions | گزینههایی که نحوه نمایش نتیجه جستجوی دادههای ساختاریافته را مشخص میکنند. |
objectType | نوع شیء نتیجه جستجو. |
نمایش نتایجفراداده
| نمایش JSON |
|---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
| فیلدها | |
|---|---|
objectTypeLabel | برچسب نمایشی برای شیء. |
metalines[] | محتوای متالین که باید همراه با نتیجه نمایش داده شود. |
فرادادهی نمایش نتیجه.خط نمایش نتیجه
مجموعهای از فیلدها که یک خط نمایش داده شده را تشکیل میدهند
| نمایش JSON |
|---|
{
"fields": [
{
object ( |
| فیلدها | |
|---|---|
fields[] | |
ResultDisplayMetadata.ResultDisplayField
نمایش فیلدها برای نتایج query.search
| نمایش JSON |
|---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
| فیلدها | |
|---|---|
label | برچسب نمایشی برای ملک. |
operatorName | نام اپراتور ملک. |
property | جفت نام و مقدار برای ویژگی. |
اطلاعات اشکالزدایی نتیجه
اطلاعات اشکالزدایی در مورد نتیجه.
| نمایش JSON |
|---|
{ "formattedDebugInfo": string } |
| فیلدها | |
|---|---|
formattedDebugInfo | اطلاعات اشکالزدایی عمومی برای نمایش قالببندی شده است. |
نتیجه ساختاریافته
نتایج ساختاریافتهای که به عنوان بخشی از درخواست جستجو بازگردانده میشوند.
| نمایش JSON |
|---|
{ // Union field |
| فیلدها | |
|---|---|
فیلد یونیونی | |
person | نمایندگی یک شخص |
نتیجه طلسم
| نمایش JSON |
|---|
{ "suggestedQuery": string, "suggestionType": enum ( |
| فیلدها | |
|---|---|
suggestedQuery | املای پیشنهادی عبارت جستجو. |
suggestionType | پیشنهادی برای پرس و جوی فعلی فعال شده است. |
suggestedQueryHtml | HTML اصلاحشده که نشاندهندهی عبارت تصحیحشدهی املایی است و میتواند در رابط کاربری استفاده شود. این معمولاً دارای برچسبهای خاص زبان برای علامتگذاری بخشهایی از عبارت است که از نظر املایی بررسی شدهاند. |
نوع پیشنهاد.نتیجه طلسم
نوع پیشنهادی که برای پرسوجو فعال شده است.
| انومها | |
|---|---|
SUGGESTION_TYPE_UNSPECIFIED | نوع بررسی املای پیشفرض |
NON_EMPTY_RESULTS_SPELL_SUGGESTION | پیشنهاد املا بدون هیچ نتیجهای تغییر کرد. نتایج هنوز برای پرسوجوی اصلی (که دارای مقادیر غیر صفر / results است) به همراه پیشنهادی برای املا که نتایجی خواهد داشت، نشان داده میشوند. |
ZERO_RESULTS_FULL_PAGE_REPLACEMENT | پیشنهاد املا زمانی فعال میشود که عبارت جستجوی اصلی هیچ نتیجهای نداشته باشد. وقتی عبارت جستجوی اصلی هیچ نتیجهای نداشته باشد و پیشنهاد املا نتایجی داشته باشد، نتایج مربوط به عبارت جستجوی تصحیحشده از نظر املا را فعال میکنیم. |
SafeHmlProto
مهم: پذیرش این پیام از یک منبع غیرقابل اعتماد ناامن است، زیرا برای یک مهاجم جعل پیامهای سریالی که قرارداد ایمنی نوع را برآورده نمیکنند، امری بدیهی است -- برای مثال، میتواند حاوی اسکریپت کنترلشده توسط مهاجم باشد. سیستمی که SafeHtmlProto را دریافت میکند، به طور ضمنی به تولیدکننده SafeHtmlProto اعتماد دارد. بنابراین، بهطورکلی بازگرداندن این پیام در پاسخهای RPC امن است، اما پذیرش آن در درخواستهای RPC بهطورکلی ناامن است.
| نمایش JSON |
|---|
{ "privateDoNotAccessOrElseSafeHtmlWrappedValue": string } |
| فیلدها | |
|---|---|
privateDoNotAccessOrElseSafeHtmlWrappedValue | مهم: هرگز این فیلد را تنظیم یا نخوانید، حتی از تستها، خصوصی است. برای مشاهدهی بستههای زبان برنامهنویسی که میتوانید با آنها این پیام را ایجاد یا بخوانید، به مستندات بالای فایل .proto مراجعه کنید. |
نتیجه چهره
پاسخ وجه خاص منبع
| نمایش JSON |
|---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
| فیلدها | |
|---|---|
sourceName | نام منبعی که نتایج وجهی برای آن برگردانده میشود. خالی نخواهد بود. |
objectType | نوع شیء که نتایج وجه برای آن برگردانده میشود. میتواند خالی باشد. |
operatorName | نام عملگری که برای صفحهبندی انتخاب شده است. @see cloudsearch.SchemaPropertyOptions |
buckets[] | FacetBuckets برای مقادیری در پاسخ که حداقل شامل یک نتیجه واحد با فیلتر مربوطه هستند. |
فیست باکت
یک سطل در یک وجه، واحد اساسی عملیات است. یک سطل میتواند شامل یک مقدار واحد یا طیف پیوستهای از مقادیر باشد، بسته به نوع فیلد سطلبندی شده. FacetBucket در حال حاضر فقط برای بازگرداندن شیء پاسخ استفاده میشود.
| نمایش JSON |
|---|
{ "count": integer, "percentage": integer, "filter": { object ( |
| فیلدها | |
|---|---|
count | تعداد نتایجی که با مقدار سطل مطابقت دارند. تعدادها فقط برای جستجوهایی که دقت شمارش تضمین شده باشد، برگردانده میشوند. جستجوی ابری تعداد وجهها را برای هیچ پرسوجویی تضمین نمیکند و تعداد وجهها ممکن است فقط به صورت متناوب، حتی برای پرسوجوهای یکسان، وجود داشته باشد. وابستگیهایی را بر اساس وجود تعداد وجهها ایجاد نکنید؛ در عوض از درصد تعداد وجهها استفاده کنید که همیشه برگردانده میشوند. |
percentage | درصد نتایجی که با مقدار سطل مطابقت دارند. مقدار برگشتی بین (0-100) است و در صورت کسری بودن به یک عدد صحیح گرد میشود. اگر مقدار به صراحت برگردانده نشود، نشاندهنده یک مقدار درصدی است که به 0 گرد میشود. درصدها برای همه جستجوها برگردانده میشوند، اما یک تخمین هستند. از آنجا که درصدها همیشه برگردانده میشوند، باید به جای شمارش، درصدها را نمایش دهید. |
filter | فیلتری که در صورت انتخاب سطل مربوطه، در درخواست جستجو ارسال میشود. |
فیلد اتحادیه bucket_value . محدوده یا مقدار سطلی که وجهی است bucket_value فقط میتواند یکی از موارد زیر باشد: | |
value | |
اطلاعات اشکالزدایی پاسخ
اطلاعات اشکالزدایی در مورد پاسخ.
| نمایش JSON |
|---|
{ "formattedDebugInfo": string } |
| فیلدها | |
|---|---|
formattedDebugInfo | اطلاعات اشکالزدایی عمومی برای نمایش قالببندی شده است. |
اطلاعات خطا
اطلاعات خطا در مورد پاسخ.
| نمایش JSON |
|---|
{
"errorMessages": [
{
object ( |
| فیلدها | |
|---|---|
errorMessages[] | |
پیام خطا
پیام خطا به ازای هر پاسخ منبع.
| نمایش JSON |
|---|
{
"source": {
object ( |
| فیلدها | |
|---|---|
source | |
errorMessage | |
شمارش نتایج
اطلاعات شمارش نتایج
| نمایش JSON |
|---|
{
"sourceResultCounts": [
{
object ( |
| فیلدها | |
|---|---|
sourceResultCounts[] | اطلاعات شمارش نتایج برای هر منبع به همراه نتایج. |
تعداد نتایج منبع
اطلاعات شمارش نتایج بر اساس منبع.
| نمایش JSON |
|---|
{ "source": { object ( |
| فیلدها | |
|---|---|
source | منبعی که اطلاعات شمارش نتایج به آن مرتبط است. |
hasMoreResults | اینکه آیا نتایج جستجوی بیشتری برای این منبع وجود دارد یا خیر. |
فیلد اتحادیه | |
resultCountEstimate | تعداد نتایج تخمینی برای این منبع. |
resultCountExact | تعداد دقیق نتایج برای این منبع. |