Method: query.search
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
Cloud Search query API روش جستجو را ارائه می دهد که مرتبط ترین نتایج را از یک درخواست کاربر برمی گرداند. نتایج می‌توانند از برنامه‌های Google Workspace، مانند Gmail یا Google Drive، یا از داده‌هایی که شما از شخص ثالث ایندکس کرده‌اید به دست آیند.
توجه: این API برای اجرا به یک حساب کاربری نهایی استاندارد نیاز دارد. یک حساب سرویس نمی تواند درخواست های API پرس و جو را به طور مستقیم انجام دهد. برای استفاده از حساب سرویس برای انجام پرس و جوها، تفویض اختیار در سراسر دامنه Google Workspace را تنظیم کنید.
درخواست HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
URL از دستور GRPC Transcoding استفاده می کند.
درخواست بدن
بدنه درخواست حاوی داده هایی با ساختار زیر است:
| فیلدها |
|---|
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 است. |
بدن پاسخگو
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی نمونه‌ای از SearchResponse است.
محدوده مجوز
به یکی از حوزه های OAuth زیر نیاز دارد:
-
https://www.googleapis.com/auth/cloud_search.query -
https://www.googleapis.com/auth/cloud_search
برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.
،
Cloud Search query API روش جستجو را ارائه می دهد که مرتبط ترین نتایج را از یک درخواست کاربر برمی گرداند. نتایج می‌توانند از برنامه‌های Google Workspace، مانند Gmail یا Google Drive، یا از داده‌هایی که شما از شخص ثالث ایندکس کرده‌اید به دست آیند.
توجه: این API برای اجرا به یک حساب کاربری نهایی استاندارد نیاز دارد. یک حساب سرویس نمی تواند درخواست های API پرس و جو را به طور مستقیم انجام دهد. برای استفاده از حساب سرویس برای انجام پرس و جوها، تفویض اختیار در سراسر دامنه Google Workspace را تنظیم کنید.
درخواست HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
URL از دستور GRPC Transcoding استفاده می کند.
درخواست بدن
بدنه درخواست حاوی داده هایی با ساختار زیر است:
| فیلدها |
|---|
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 است. |
بدن پاسخگو
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی نمونه‌ای از SearchResponse است.
محدوده مجوز
به یکی از حوزه های OAuth زیر نیاز دارد:
-
https://www.googleapis.com/auth/cloud_search.query -
https://www.googleapis.com/auth/cloud_search
برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Method: query.search\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n- [Authorization scopes](#body.aspect)\n- [Try it!](#try-it)\n\nThe Cloud Search query API provides the search method, which returns the most relevant results from a user query. The results can come from Google Workspace apps, such as Gmail or Google Drive, or they can come from data that you have indexed from a third party.\n\n**Note:** This API requires a standard end user account to execute. A service account can't perform query API requests directly; to use a service account to perform queries, set up [Google Workspace domain-wide delegation of authority](https://developers.google.com/workspace/cloud-search/docs/guides/delegation/).\n\n### HTTP request\n\n`POST https://cloudsearch.googleapis.com/v1/query/search`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"requestOptions\": { object (/workspace/cloud-search/docs/reference/rest/v1/RequestOptions) }, \"query\": string, \"pageSize\": integer, \"start\": integer, \"dataSourceRestrictions\": [ { object (/workspace/cloud-search/docs/reference/rest/v1/settings.searchapplications#DataSourceRestriction) } ], \"facetOptions\": [ { object (/workspace/cloud-search/docs/reference/rest/v1/settings.searchapplications#FacetOptions) } ], \"sortOptions\": { object (/workspace/cloud-search/docs/reference/rest/v1/settings.searchapplications#SortOptions) }, \"queryInterpretationOptions\": { object (/workspace/cloud-search/docs/reference/rest/v1/QueryInterpretationOptions) }, \"contextAttributes\": [ { object (/workspace/cloud-search/docs/reference/rest/v1/indexing.datasources.items#ContextAttribute) } ] } ``` |\n\n| Fields ||\n|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `requestOptions` | `object (`[RequestOptions](/workspace/cloud-search/docs/reference/rest/v1/RequestOptions)`)` Request options, such as the search application and user timezone. |\n| `query` | `string` The raw query string. See supported search operators in the [Narrow your search with operators](https://support.google.com/cloudsearch/answer/6172299) |\n| `pageSize` | `integer` Maximum number of search results to return in one page. Valid values are between 1 and 100, inclusive. Default value is 10. Minimum value is 50 when results beyond 2000 are requested. |\n| `start` | `integer` Starting index of the results. |\n| `dataSourceRestrictions[]` | `object (`[DataSourceRestriction](/workspace/cloud-search/docs/reference/rest/v1/settings.searchapplications#DataSourceRestriction)`)` The sources to use for querying. If not specified, all data sources from the current search application are used. |\n| `facetOptions[]` | `object (`[FacetOptions](/workspace/cloud-search/docs/reference/rest/v1/settings.searchapplications#FacetOptions)`)` |\n| `sortOptions` | `object (`[SortOptions](/workspace/cloud-search/docs/reference/rest/v1/settings.searchapplications#SortOptions)`)` The options for sorting the search results |\n| `queryInterpretationOptions` | `object (`[QueryInterpretationOptions](/workspace/cloud-search/docs/reference/rest/v1/QueryInterpretationOptions)`)` options to interpret the user query. |\n| `contextAttributes[]` | `object (`[ContextAttribute](/workspace/cloud-search/docs/reference/rest/v1/indexing.datasources.items#ContextAttribute)`)` Context attributes for the request which will be used to adjust ranking of search results. The maximum number of elements is 10. |\n\n### Response body\n\nIf successful, the response body contains an instance of [SearchResponse](/workspace/cloud-search/docs/reference/rest/v1/SearchResponse).\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://www.googleapis.com/auth/cloud_search.query`\n- `https://www.googleapis.com/auth/cloud_search`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent)."]]
