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)

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

object (SpellResult)

الهجاء المقترح لطلب البحث.
facetResults[]

object (FacetResult)

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

boolean

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

object (ResponseDebugInfo)

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

object (ErrorInfo)

معلومات الخطأ حول الرد.
resultCounts

object (ResultCounts)

تم توسيع معلومات عدد النتائج.

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

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

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

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

لمزيد من المعلومات، راجع نظرة عامة على OAuth 2.0.

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

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

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

boolean

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

boolean

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

boolean

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

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

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

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

QueryInterpretation.InterpretationType

عمليات التعداد
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، 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

نوع الكائن في نتيجة البحث.

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

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

عرض الحقول لنتائج search.search

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

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

دلو الواجهات

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

تمثيل JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
الحقول
count

integer

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

integer

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

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