Method: query.search
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
توفّر Cloud Search query API طريقة البحث التي تعرض النتائج الأكثر صلةً من طلب بحث المستخدم. يمكن أن تأتي النتائج من تطبيقات Google Workspace، مثل Gmail أو Google Drive، أو يمكن أن تأتي من بيانات فهّمتها من جهة خارجية.
ملاحظة: تتطلّب واجهة برمجة التطبيقات هذه حساب مستخدم نهائي عادي لتنفيذها. لا يمكن لحساب الخدمة تنفيذ طلبات واجهة برمجة التطبيقات لطلبات البحث مباشرةً. لاستخدام حساب خدمة لإجراء طلبات بحث، عليك إعداد تفويض السلطة على مستوى نطاق Google Workspace.
طلب HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
| الحقول |
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.queryhttps://www.googleapis.com/auth/cloud_search
لمزيد من المعلومات، يمكنك الاطّلاع على دليل التفويض.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة 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)."]]
