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

لمزيد من المعلومات، راجِع دليل التفويض.

QueryInterpretationOptions

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

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

boolean

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

boolean

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

boolean

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

QueryInterpretation

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

string

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

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

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

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

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)

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