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 Transcode.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

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

هي نتائج منظَّمة لطلب بحث المستخدم. ولا يتم احتساب هذه النتائج ضمن pageSize.
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

لمزيد من المعلومات، اطّلِع على دليل التفويض.

خيارات تفسير طلبات البحث

خيارات تفسير طلب بحث المستخدم.

تمثيل JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
الحقول
disableNlInterpretation

boolean

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

boolean

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

boolean

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

تفسير طلبات البحث

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

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

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

تفسير تفسير طلبات البحث

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

تفسير طلب البحث

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

نتيجة البحث

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

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

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

معدل المطابقة

النطاق المطابق للمقتطف [start، النهاية].

تمثيل 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 "Zulu"، بدقة تصل إلى نانو ثانية وما يصل إلى تسعة أرقام كسور أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

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

طابع زمني بتنسيق RFC3339 UTC "Zulu"، بدقة تصل إلى نانو ثانية وما يصل إلى تسعة أرقام كسور أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

الحقول المفهرسة في البيانات المنظَّمة التي يتم عرضها كسمة مُسمّاة عامة.
displayOptions

object (ResultDisplayMetadata)

الخيارات التي تحدّد كيفية عرض نتيجة بحث للبيانات المنظَّمة
objectType

string

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

البيانات الوصفية لعرض النتائج

تمثيل JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
الحقول
objectTypeLabel

string

تصنيف العرض للعنصر.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

يشير هذا المصطلح إلى محتوى يتضمن قيمًا وصفية يتم عرضها مع النتيجة.

ResultDisplayMetadata.نتيجةDisplayDisplayLine

مجموعة الحقول التي تشكّل سطرًا معروضًا

تمثيل JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
الحقول
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.نتيجةDisplayDisplayField

حقول العرض لنتائج طلب البحث

تمثيل JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
الحقول
label

string

تمثّل هذه السمة تصنيف العرض للموقع.
operatorName

string

اسم عامل التشغيل للموقع
property

object (NamedProperty)

زوج قيمة الاسم للموقع.

معلومات تصحيح النتائج

تصحيح أخطاء المعلومات حول النتيجة

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

string

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

النتيجة المنظَّمة

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

تمثيل JSON 
{
  "person": {
    object (Person)
  }
}
الحقول
person

object (Person)

تمثيل شخص

نتيجة إملائية

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

string

التهجئة المقترحة لطلب البحث

نتيجة الوجه

استجابة واجهة مصدر معيّنة

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

string

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

string

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

string

تمثّل هذه السمة اسم عامل التشغيل الذي تم تحديده للوجه. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

مجموعة FacetBuckies للقيم التي تحتوي على نتيجة واحدة على الأقل باستخدام الفلتر المقابل

دلو الوجه

إنّ الدُلّة في الواجهة هي الوحدة الأساسية للتشغيل. ويمكن أن تتضمّن مجموعة البيانات قيمة واحدة أو نطاقًا متتاليًا من القيم، اعتمادًا على نوع مجموعة البيانات المجمّعة. لا يتم استخدام 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)

معلومات تصحيح الأخطاء في الرد

تصحيح أخطاء المعلومات المتعلقة بالاستجابة

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

string

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

معلومات الخطأ

معلومات حول الخطأ.

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

object (ErrorMessage)

رسالة الخطأ

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

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

object (Source)
errorMessage

string

أعداد النتائج

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

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

object (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)

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