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.

نص الاستجابة

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

ردّ واجهة برمجة تطبيقات البحث.

تمثيل 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. إجمالي عدد النتائج على مستوى جميع مصادر البيانات المطلوبة. يتم حذفها إذا تم تضمين المصادر المحددة مسبقًا في مجموعة مصادر البيانات التي تم البحث عنها. قد يتم عرض أعداد النتائج كتقدير، وليس كقيمة دقيقة، في ظل الظروف التالية:

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

  • عندما يكون عدد قوائم التحكم في الوصول (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). الإعداد التلقائي "خطأ"، والضبط على "صحيح" لإيقاف تفسير اللغة الطبيعية. لا ينطبق تفسير لغة البرمجة NL إلا على مصادر البيانات المحدَّدة مسبقًا.
enableVerbatimMode

boolean

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

boolean

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

QueryInterpretation

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

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

QueryInterpretation.InterpretationType

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

QueryInterpretation.Reason

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

SearchResult

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

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

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

MatchRange

النطاق المطابق لمقتطف [start وend).

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

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

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

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

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "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)

محتوى metalines الذي سيتم عرضه مع النتيجة.

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 
{
  "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)

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

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

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

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)

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