Method: query.search

توفّر واجهة برمجة التطبيقات لطلبات البحث في Cloud Search طريقة البحث التي تعرض النتائج الأكثر صلة بطلب بحث المستخدم. يمكن أن تأتي النتائج من تطبيقات Google Workspace، مثل Gmail أو Google Drive، أو من بيانات تمت فهرستها من جهة خارجية.

ملاحظة: تتطلّب واجهة برمجة التطبيقات هذه حساب مستخدم نهائي عاديًا لتنفيذها. لا يمكن لحساب الخدمة تنفيذ طلبات واجهة برمجة التطبيقات للاستعلام مباشرةً. لاستخدام حساب خدمة لتنفيذ طلبات البحث، عليك إعداد تفويض على مستوى نطاق Google Workspace.

طلب HTTP

POST https://cloudsearch.googleapis.com/v1/query/search

يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل 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.

نص الاستجابة

الردّ من واجهة برمجة التطبيقات الخاصة بالبحث معرّف NEXT: 19

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل 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)

نتائج منظَّمة لطلب بحث المستخدم لا يتم احتساب هذه النتائج ضمن حجم الصفحة.
spellResults[]

object (SpellResult)

تصحيح إملائي مقترح لطلب البحث
facetResults[]

object (FacetResult)

نتائج الأوجه المتكرّرة
hasMoreResults

boolean

تُستخدَم لتحديد ما إذا كانت هناك المزيد من نتائج البحث التي تطابق طلب البحث.
debugInfo

object (ResponseDebugInfo)

معلومات تصحيح الأخطاء المتعلّقة بالردّ
errorInfo

object (ErrorInfo)

معلومات الخطأ المتعلّقة بالردّ
resultCounts

object (ResultCounts)

معلومات موسّعة حول عدد النتائج

حقل الدمج result_count إجمالي عدد النتائج في جميع مصادر البيانات المطلوبة يتم حذف هذا الحقل إذا تم تضمين مصادر محدّدة مسبقًا في مجموعة مصادر البيانات التي يتم البحث فيها. قد يتم عرض أعداد النتائج كتقدير بدلاً من عدد دقيق في الحالات التالية:

  • عندما يتضمّن طلب البحث أكثر من عبارتَين في عبارة، مثل "عدد النتائج مطابق" بين علامتَي اقتباس

  • عندما يكون عدد قوائم التحكّم بالوصول الفريدة لنتائج البحث المطلوب تقييمها كبيرًا جدًا بحيث لا يمكن حسابه في وقت استجابة معقول.

في الحالات النادرة التي يتعذّر فيها على النظام البحث في جميع المستندات، أعِد تنفيذ طلب البحث. يمكن أن تكون 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

علم لإيقاف تفسير طلبات البحث باللغة الطبيعية القيمة التلقائية هي "خطأ". اضبطها على "صحيح" لإيقاف تفسير اللغة الطبيعية. لا ينطبق تفسير اللغة الطبيعية إلا على مصادر البيانات المحدّدة مسبقًا.
enableVerbatimMode

boolean

فعِّل هذا الخيار لإيقاف جميع التحسينات الداخلية، مثل تفسير اللغة الطبيعية (NL) للاستعلامات واسترجاع النتائج التكميلية واستخدام المرادفات، بما في ذلك المرادفات المخصّصة. سيتم إيقاف تفسير اللغة الطبيعية إذا كانت إحدى العلامتَين صحيحة.
disableSupplementalResults

boolean

استخدِم هذه العلامة لإيقاف النتائج التكميلية لطلب بحث معيّن. سيكون لإعداد النتائج التكميلية الذي تم اختياره على مستوى SearchApplication الأولوية إذا تم ضبطه على "صحيح".

QueryInterpretation

تمثيل JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
الحقول
interpretedQuery

string

تفسير طلب البحث المستخدَم في البحث على سبيل المثال، سيتم تفسير طلبات البحث التي تتضمّن عبارات بلغة طبيعية مثل "رسالة إلكترونية من فلان" على أنّها "from:john source:mail". لن يتم ملء هذا الحقل عندما يكون السبب هو NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

تمثّل هذه السمة سبب تفسير طلب البحث. لن يكون هذا الحقل UNSPECIFIED إذا لم يكن نوع التفسير NONE.
interpretedQueryActualResultCount

integer

العدد الفعلي للنتائج التي يعرضها طلب البحث الذي تم تفسيره.
interpretedQueryEstimatedResultCount

string (int64 format)

العدد المقدَّر للنتائج التي يعرضها طلب البحث الذي تم تفسيره

QueryInterpretation.InterpretationType

عمليات التعداد
NONE لا يتم استخدام تفسير اللغة الطبيعية ولا نسخة أوسع من طلب البحث لجلب نتائج البحث.
BLEND يتم دمج النتائج من الاستعلام الأصلي مع نتائج أخرى. يتم عرض سبب دمج هذه النتائج الأخرى مع نتائج طلب البحث الأصلي في حقل "السبب" أدناه.
REPLACE يتم استبدال النتائج من طلب البحث الأصلي. يتم ملء حقل "السبب" أدناه بسبب استبدال النتائج من طلب البحث الأصلي.

QueryInterpretation.Reason

عمليات التعداد
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT يتم استخدام التفسير باللغة الطبيعية لطلب البحث من أجل استرجاع نتائج البحث.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY يتم استخدام التشابه بين عبارات طلب البحث والمستندات لتوسيع نطاق طلب البحث بشكل انتقائي من أجل استرداد نتائج بحث إضافية، وذلك لأنّه لم يتم العثور على نتائج كافية لطلب بحث المستخدم. سيكون طلب البحث الذي تم تفسيره فارغًا في هذه الحالة.

SearchResult

نتائج تحتوي على معلومات مفهرسة لمستند المعرّف التالي: 16

تمثيل JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
الحقول
title

string

عنوان نتيجة البحث
url

string

عنوان URL لنتيجة البحث يحتوي عنوان URL على عملية إعادة توجيه من Google إلى المنتج الفعلي. هذا العنوان موقّع ويجب عدم تغييره.
snippet

object (Snippet)

سلسلة من جميع المقتطفات (الملخّصات) المتاحة لهذه النتيجة
metadata

object (Metadata)

البيانات الوصفية لنتيجة البحث
clusteredResults[]

object (SearchResult)

إذا كان المصدر مجمّعًا، قدِّم قائمة بالنتائج المجمّعة. سيكون هناك مستوى واحد فقط من النتائج المجمّعة. إذا لم يتم تفعيل المصدر الحالي للتجميع، سيكون هذا الحقل فارغًا.
debugInfo

object (ResultDebugInfo)

معلومات تصحيح الأخطاء المتعلّقة بنتيجة البحث هذه

المقتطف

مقتطف من نتيجة البحث يلخّص محتوى الصفحة الناتجة

تمثيل JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
الحقول
snippet

string

مقتطف من المستند قد يحتوي على حرف HTML تم إلغاء تسلسله ويجب إعادة تسلسله قبل العرض.
matchRanges[]

object (MatchRange)

النطاقات المطابقة في المقتطف

MatchRange

النطاق المطابق لمقتطف [البداية، النهاية).

تمثيل 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

تمثّل عنوان URL للصورة المصغّرة الخاصة بالنتيجة.
owner

object (Person)

مالك المستند أو العنصر (عادةً المنشئ) الذي يظهر في نتيجة البحث
createTime

string (Timestamp format)

تمثّل هذه السمة وقت إنشاء هذا المستند أو العنصر في نتيجة البحث.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

تاريخ آخر تعديل للعنصر في نتيجة البحث إذا لم يتم ضبطها في السلعة، تكون القيمة المعروضة هنا فارغة. عند استخدام updateTime لاحتساب مدى الحداثة وعدم ضبطها، تكون القيمة التلقائية هي عامان من الوقت الحالي.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
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

معلومات تصحيح الأخطاء العامة المنسَّقة للعرض

StructuredResult

نتائج منظَّمة يتم عرضها كجزء من طلب البحث

تمثيل JSON 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
الحقول

حقل الدمج structured_result

يمكن أن تكون structured_result إحدى القيم التالية فقط:
person

object (Person)

تمثيل شخص

SpellResult

تمثيل JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
الحقول
suggestedQuery

string

تمثّل هذه السمة التصحيح الإملائي المقترَح للطلب.
suggestionType

enum (SpellResult.SuggestionType)

اقتراح تم عرضه لطلب البحث الحالي.
suggestedQueryHtml

object (SafeHtmlProto)

تمثّل هذه السمة رمز HTML الذي تم تنظيفه والذي يمثّل طلب البحث الذي تم تصحيح أخطائه الإملائية ويمكن استخدامه في واجهة المستخدم. يتضمّن ذلك عادةً علامات خاصة باللغة لترميز أجزاء من طلب البحث يتم التدقيق الإملائي فيها.

SpellResult.SuggestionType

تمثّل هذه السمة نوع الاقتراح الذي تم عرضه لطلب البحث.

عمليات التعداد
SUGGESTION_TYPE_UNSPECIFIED نوع التدقيق الإملائي التلقائي
NON_EMPTY_RESULTS_SPELL_SUGGESTION تم تغيير اقتراح التدقيق الإملائي بدون أي نتائج. تستمر النتائج في الظهور لطلب البحث الأصلي (الذي يتضمّن نتائج غير صفرية)، مع اقتراح تدقيق إملائي يؤدي إلى ظهور نتائج.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT اقتراح التدقيق الإملائي الذي يتم تفعيله عندما لا يعرض طلب البحث الأصلي أي نتائج عندما لا يؤدي طلب البحث الأصلي إلى ظهور أي نتائج، ولكن يؤدي اقتراح التدقيق الإملائي إلى ظهور نتائج، نعرض نتائج لطلب البحث الذي تم تصحيح أخطائه الإملائية.

SafeHtmlProto

ملاحظة مهمة: من غير الآمن قبول هذه الرسالة من مصدر غير موثوق به، لأنّه من السهل على المهاجم إنشاء رسائل متسلسلة لا تستوفي عقد أمان النوع، على سبيل المثال، قد تحتوي على نص برمجي يتحكّم فيه المهاجم. النظام الذي يتلقّى SafeHtmlProto يثق ضمنيًا في منتج SafeHtmlProto. لذا، من الآمن بشكل عام عرض هذه الرسالة في ردود RPC، ولكن من غير الآمن بشكل عام قبولها في طلبات RPC.

تمثيل JSON 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
الحقول
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

ملاحظة مهمة: لا تضبط هذا الحقل أو تقرأه أبدًا، حتى من الاختبارات، فهو خاص. راجِع المستندات في أعلى ملف ‎ .proto لمعرفة حِزم لغات البرمجة التي يمكن استخدامها لإنشاء هذه الرسالة أو قراءتها.

FacetResult

ردّ متعدد الأوجه خاص بالمصدر

تمثيل JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
الحقول
sourceName

string

اسم المصدر الذي يتم عرض نتائج الفلاتر له. لن يكون فارغًا.
objectType

string

نوع العنصر الذي يتم عرض نتائج الفلاتر له. يمكن أن يكون الحقل فارغًا.
operatorName

string

اسم عامل التشغيل الذي تم اختياره لتقسيم النتائج إلى أوجه. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets للقيم في الرد الذي يحتوي على نتيجة واحدة على الأقل مع الفلتر المقابل.

FacetBucket

المجموعة في وجه البحث هي وحدة التشغيل الأساسية. يمكن أن يتضمّن التصنيف إما قيمة واحدة أو نطاقًا متجاورًا من القيم، وذلك حسب نوع الحقل الذي تم تصنيفه. يتم حاليًا استخدام FacetBucket لعرض عنصر الرد فقط.

تمثيل JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
الحقول
count

integer

عدد النتائج التي تطابق قيمة المجموعة. لا يتم عرض الأعداد إلا في عمليات البحث التي يتم التأكّد من دقتها. لا يضمن Cloud Search توفّر أعداد الأوجه لأي طلب بحث، وقد تظهر أعداد الأوجه بشكل متقطع فقط، حتى لطلبات البحث المتطابقة. لا تنشئ تبعيات على توفّر عدد النتائج حسب الفئة، بل استخدِم نسب عدد النتائج حسب الفئة التي يتم عرضها دائمًا.
percentage

integer

النسبة المئوية للنتائج التي تتطابق مع قيمة المجموعة. تتراوح القيمة المعروضة بين (0 و100]، ويتم تقريبها إلى عدد صحيح إذا كانت كسرية. إذا لم يتم عرض القيمة بشكلٍ صريح، فإنّها تمثّل قيمة نسبة مئوية يتم تقريبها إلى 0. يتم عرض النسب المئوية لجميع عمليات البحث، ولكنّها تكون تقديرية. بما أنّه يتم عرض النسب المئوية دائمًا، عليك عرض النسب المئوية بدلاً من الأعداد.
filter

object (Filter)

الفلتر الذي سيتم تمريره في طلب البحث في حال تحديد الحزمة المقابلة
حقل الدمج bucket_value يمكن أن يكون نطاق أو قيمة المجموعة التي يتم تقسيمها إلى أوجه bucket_value واحدًا مما يلي فقط:
value

object (Value)

ResponseDebugInfo

معلومات تصحيح الأخطاء المتعلّقة بالردّ

تمثيل JSON 
{
  "formattedDebugInfo": string
}
الحقول
formattedDebugInfo

string

معلومات تصحيح الأخطاء العامة المنسَّقة للعرض

ErrorInfo

معلومات الخطأ المتعلّقة بالردّ

تمثيل JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
الحقول
errorMessages[]

object (ErrorMessage)

ErrorMessage

رسالة الخطأ لكل ردّ من المصدر

تمثيل JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
الحقول
source

object (Source)
errorMessage

string

ResultCounts

معلومات حول عدد النتائج

تمثيل 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)

عدد النتائج الدقيق لهذا المصدر.