Method: query.search

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

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

نص الاستجابة

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

استجابة Search API

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

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

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

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

الإبلاغ عن إيقاف تفسير طلبات البحث باللغة الطبيعية القيمة التلقائية هي false، ويمكنك ضبطها على true لإيقاف تفسير اللغة الطبيعية. لا ينطبق تفسير اللغة الطبيعية إلا على مصادر البيانات المحدّدة مسبقًا.
enableVerbatimMode

boolean

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

boolean

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

QueryInterpretation

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

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

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

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

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

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

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