- طلب HTTP
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- خيارات تفسير طلب البحث
- تفسير طلبات البحث
- تفسير الشرح لطلب البحث
- سبب تفسير طلب البحث
- نتيجة البحث
- المقتطف
- تطابق النطاق
- البيانات الوصفية
- نتائج عرض البيانات الوصفية
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- نتيجة تصحيح الأخطاء في النتائج
- النتيجة المنظَّمة
- التدقيق الإملائي
- واجهة الوجه
- دالة الوجه
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- عدد النتائج
- SourceResultCount
- جرِّبه الآن
توفّر 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 |
سلسلة طلب البحث الأولية. الاطّلاع على عوامل تشغيل البحث المتوافقة في تضييق نطاق البحث باستخدام عوامل التشغيل |
pageSize |
الحد الأقصى لعدد نتائج البحث المراد عرضها في صفحة واحدة. تتراوح القيم الصالحة بين 1 و100، بما يشمل هذين الرقمين. والقيمة التلقائية هي 10. وتكون القيمة الأدنى هي 50 عندما يتم طلب النتائج بعد 2000. |
start |
فهرس بدء النتائج. |
dataSourceRestrictions[] |
المصادر المطلوب استخدامها لطلب البحث. في حال عدم تحديد هذه السياسة، يتم استخدام جميع مصادر البيانات من تطبيق البحث الحالي. |
facetOptions[] |
|
sortOptions |
خيارات ترتيب نتائج البحث |
queryInterpretationOptions |
خيارات تفسير طلب بحث المستخدم. |
contextAttributes[] |
سمات السياق للطلب الذي سيتم استخدامه لتعديل ترتيب نتائج البحث الحد الأقصى لعدد العناصر هو 10. |
نص الاستجابة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
استجابة واجهة برمجة التطبيقات للبحث
تمثيل JSON |
---|
{ "queryInterpretation": { object ( |
الحقول | |
---|---|
queryInterpretation |
نتيجة تفسير طلب البحث لطلب بحث المستخدم. ويكون فارغًا إذا تم إيقاف تفسير طلبات البحث. |
results[] |
نتائج من طلب بحث |
structuredResults[] |
هي نتائج منظَّمة لطلب بحث المستخدم. ولا يتم احتساب هذه النتائج ضمن pageSize. |
spellResults[] |
تصحيح إملائي مقترح لطلب البحث |
facetResults[] |
نتائج الواجهة المتكررة |
hasMoreResults |
ما إذا كان هناك المزيد من نتائج البحث المطابقة لطلب البحث |
debugInfo |
تصحيح أخطاء المعلومات المتعلقة بالاستجابة |
errorInfo |
معلومات حول الخطأ. |
resultCounts |
معلومات موسّعة حول عدد النتائج. |
حقل الاتحاد
في الحالات النادرة التي يتعذّر فيها على النظام البحث في جميع المستندات، يمكنك إعادة تنفيذ طلب البحث. لا يمكن أن يكون |
|
resultCountEstimate |
العدد المقدَّر للنتائج لطلب البحث هذا. |
resultCountExact |
عدد النتائج الدقيق لطلب البحث هذا. |
نطاقات الأذونات
يتطلب ذلك أحد نطاقات OAuth التالية:
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
لمزيد من المعلومات، اطّلِع على دليل التفويض.
خيارات تفسير طلبات البحث
خيارات تفسير طلب بحث المستخدم.
تمثيل JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
الحقول | |
---|---|
disableNlInterpretation |
علامة لإيقاف تفسير الطلبات الطبيعية باللغة (NL) ويتم ضبط القيمة التلقائية على "خطأ" على "صحيح" لإيقاف تفسير اللغة الطبيعية. لا ينطبق تفسير NL إلا على مصادر البيانات المحدَّدة مسبقًا. |
enableVerbatimMode |
يمكنك تفعيل هذه العلامة لإيقاف جميع عمليات التحسين الداخلية مثل تفسير اللغة الطبيعية (NL) طلبات البحث واسترجاع النتائج التكميلية واستخدام المرادفات، بما في ذلك العبارات المخصّصة. سيتم إيقاف تفسير Nl إذا كانت إحدى العلامتَين صحيحة. |
disableSupplementalResults |
يمكنك استخدام هذه العلامة لإيقاف النتائج التكميلية لطلب البحث. سيتم منح الأولوية لإعدادات النتائج التكميلية التي تم اختيارها على مستوى SearchApplication في حال ضبطها على "صحيح". |
تفسير طلبات البحث
تمثيل JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
الحقول | |
---|---|
interpretedQuery |
تفسير طلب البحث المستخدَم في البحث. على سبيل المثال، سيتم تفسير طلبات البحث ذات اللغة الطبيعية مثل "email from john" على أنها "from:john Source:mail". لن يتم ملء هذا الحقل عندما يكون السبب NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
reason |
سبب تفسير طلب البحث. لن يتم تحديد هذا الحقل إذا لم يكن نوع التفسير "بلا". |
تفسير تفسير طلبات البحث
عمليات التعداد | |
---|---|
NONE |
ولا يتم استخدام تفسير اللغة الطبيعية أو نسخة أوسع من طلب البحث للحصول على نتائج البحث. |
BLEND |
يتم دمج نتائج البحث الأصلي مع نتائج أخرى. تتم تعبئة سبب دمج هذه النتائج الأخرى مع نتائج طلب البحث الأصلي في حقل "السبب" أدناه. |
REPLACE |
ويتم استبدال النتائج من طلب البحث الأصلي. تتم تعبئة سبب استبدال النتائج من طلب البحث الأصلي في حقل "السبب" أدناه. |
تفسير طلب البحث
عمليات التعداد | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
يُستخدم تفسير اللغة الطبيعية لطلب البحث لجلب نتائج البحث. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
يتم استخدام تشابه عبارات طلب البحث والمستندات لتوسيع نطاق طلب البحث بشكل انتقائي لاسترداد نتائج البحث الإضافية نظرًا لعدم العثور على نتائج كافية لطلب بحث المستخدم. سيكون الطلب تفسيري فارغًا لهذا الطلب. |
نتيجة البحث
النتائج التي تحتوي على معلومات مفهرسة للمستند
تمثيل JSON |
---|
{ "title": string, "url": string, "snippet": { object ( |
الحقول | |
---|---|
title |
عنوان نتيجة البحث |
url |
عنوان URL لنتيجة البحث. يتضمن عنوان URL إعادة توجيه Google إلى العنصر الفعلي. تم توقيع عنوان URL هذا ويجب عدم تغييره. |
snippet |
سلسلة كل المقتطفات (الملخّصات) المتاحة لهذه النتيجة |
metadata |
البيانات الوصفية لنتيجة البحث |
clusteredResults[] |
في حال تجميع المصدر، قدِّم قائمة بالنتائج المجمّعة. سيكون هناك مستوى واحد فقط من النتائج المجمَّعة. في حال لم يتم تفعيل المصدر الحالي للتجميع، سيكون هذا الحقل فارغًا. |
debugInfo |
تصحيح الأخطاء في معلومات نتيجة البحث هذه |
المقتطف
مقتطف من نتيجة البحث، الذي يلخّص محتوى الصفحة الناتجة
تمثيل JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
الحقول | |
---|---|
snippet |
مقتطف المستند. مقتطف المستند. قد يحتوي على حرف HTML تم تجاوزه ويجب إلغاء حروفه قبل العرض. |
matchRanges[] |
النطاقات المطابقة في المقتطف. |
معدل المطابقة
النطاق المطابق للمقتطف [start، النهاية].
تمثيل JSON |
---|
{ "start": integer, "end": integer } |
الحقول | |
---|---|
start |
موضع بدء المطابقة في المقتطف. |
end |
نهاية المطابقة في المقتطف. |
البيانات الوصفية
البيانات الوصفية لنتيجة بحث مطابقة.
تمثيل JSON |
---|
{ "source": { object ( |
الحقول | |
---|---|
source |
المصدر المحدّد للنتيجة، مثل Gmail. |
mimeType |
نوع MIME لنتيجة البحث |
thumbnailUrl |
عنوان URL للصورة المصغّرة للنتيجة. |
owner |
المالك (عادةً ما يكون منشئ) للمستند أو كائن نتيجة البحث |
createTime |
وقت إنشاء هذا المستند أو العنصر في نتيجة البحث طابع زمني بتنسيق RFC3339 UTC "Zulu"، بدقة تصل إلى نانو ثانية وما يصل إلى تسعة أرقام كسور أمثلة: |
updateTime |
تاريخ آخر تعديل للعنصر في نتيجة البحث. إذا لم يتم ضبط العنصر في العنصر، ستكون القيمة المعروضة هنا فارغة. عند استخدام طابع زمني بتنسيق RFC3339 UTC "Zulu"، بدقة تصل إلى نانو ثانية وما يصل إلى تسعة أرقام كسور أمثلة: |
fields[] |
الحقول المفهرسة في البيانات المنظَّمة التي يتم عرضها كسمة مُسمّاة عامة. |
displayOptions |
الخيارات التي تحدّد كيفية عرض نتيجة بحث للبيانات المنظَّمة |
objectType |
نوع عنصر نتيجة البحث |
البيانات الوصفية لعرض النتائج
تمثيل JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
الحقول | |
---|---|
objectTypeLabel |
تصنيف العرض للعنصر. |
metalines[] |
يشير هذا المصطلح إلى محتوى يتضمن قيمًا وصفية يتم عرضها مع النتيجة. |
ResultDisplayMetadata.نتيجةDisplayDisplayLine
مجموعة الحقول التي تشكّل سطرًا معروضًا
تمثيل JSON |
---|
{
"fields": [
{
object ( |
الحقول | |
---|---|
fields[] |
ResultDisplayMetadata.نتيجةDisplayDisplayField
حقول العرض لنتائج طلب البحث
تمثيل JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
الحقول | |
---|---|
label |
تمثّل هذه السمة تصنيف العرض للموقع. |
operatorName |
اسم عامل التشغيل للموقع |
property |
زوج قيمة الاسم للموقع. |
معلومات تصحيح النتائج
تصحيح أخطاء المعلومات حول النتيجة
تمثيل JSON |
---|
{ "formattedDebugInfo": string } |
الحقول | |
---|---|
formattedDebugInfo |
معلومات تصحيح الأخطاء العامة المنسّقة للعرض. |
النتيجة المنظَّمة
يتم عرض النتائج المنظَّمة كجزء من طلب البحث.
تمثيل JSON |
---|
{
"person": {
object ( |
الحقول | |
---|---|
person |
تمثيل شخص |
نتيجة إملائية
تمثيل JSON |
---|
{ "suggestedQuery": string } |
الحقول | |
---|---|
suggestedQuery |
التهجئة المقترحة لطلب البحث |
نتيجة الوجه
استجابة واجهة مصدر معيّنة
تمثيل JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
الحقول | |
---|---|
sourceName |
اسم المصدر الذي يتم عرض نتائج الواجهة له لن يكون فارغًا. |
objectType |
نوع العنصر الذي يتم عرض نتائج الواجهة له يمكن ترك الحقل فارغًا. |
operatorName |
تمثّل هذه السمة اسم عامل التشغيل الذي تم تحديده للوجه. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
مجموعة FacetBuckies للقيم التي تحتوي على نتيجة واحدة على الأقل باستخدام الفلتر المقابل |
دلو الوجه
إنّ الدُلّة في الواجهة هي الوحدة الأساسية للتشغيل. ويمكن أن تتضمّن مجموعة البيانات قيمة واحدة أو نطاقًا متتاليًا من القيم، اعتمادًا على نوع مجموعة البيانات المجمّعة. لا يتم استخدام FacetBucket حاليًا إلا لعرض كائن الاستجابة.
تمثيل JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
الحقول | |
---|---|
count |
عدد النتائج التي تطابق قيمة مجموعة البيانات. لا يتم عرض الأعداد إلا لعمليات البحث عند ضمان دقة العدد. لا يضمن Cloud Search عدد الواجهات لأي طلب بحث وقد يتم عرض أعداد الواجهات على فترات متقطّعة فقط، حتى بالنسبة إلى طلبات البحث المطابِقة. لا تُنشئ الاعتماديات على وجود عدد الواجهات، بل استخدم نِسب مئوية للواجهة التي يتم عرضها دائمًا. |
percentage |
النسبة المئوية من النتائج التي تطابق قيمة الحزمة. تتراوح القيمة المعروضة بين (0 و100) ويتم تقريبها إلى عدد صحيح إذا كانت كسورًا. إذا لم يتم عرض القيمة صراحةً، فإنها تمثّل قيمة النسبة المئوية التي تقرب إلى 0. يتم عرض النسب المئوية لجميع عمليات البحث، ولكنها تقديرية. ولأنّ النسب المئوية يتم عرضها دائمًا، يجب عرض النسب المئوية بدلاً من الأعداد. |
filter |
الفلترة ليتم تمريرها في طلب البحث إذا تم اختيار مجموعة البيانات المقابلة |
value |
|
معلومات تصحيح الأخطاء في الرد
تصحيح أخطاء المعلومات المتعلقة بالاستجابة
تمثيل JSON |
---|
{ "formattedDebugInfo": string } |
الحقول | |
---|---|
formattedDebugInfo |
معلومات تصحيح الأخطاء العامة المنسّقة للعرض. |
معلومات الخطأ
معلومات حول الخطأ.
تمثيل JSON |
---|
{
"errorMessages": [
{
object ( |
الحقول | |
---|---|
errorMessages[] |
|
رسالة الخطأ
رسالة خطأ لكل رد مصدر.
تمثيل JSON |
---|
{
"source": {
object ( |
الحقول | |
---|---|
source |
|
errorMessage |
|
أعداد النتائج
معلومات حول عدد النتائج
تمثيل JSON |
---|
{
"sourceResultCounts": [
{
object ( |
الحقول | |
---|---|
sourceResultCounts[] |
معلومات حول عدد النتائج لكل مصدر مع النتائج |
عدد النتائج المصدر
معلومات حول عدد النتائج حسب المصدر
تمثيل JSON |
---|
{ "source": { object ( |
الحقول | |
---|---|
source |
المصدر الذي ترتبط به معلومات عدد النتائج |
hasMoreResults |
ما إذا كانت هناك المزيد من نتائج البحث لهذا المصدر |
حقل الاتحاد لا يمكن أن يكون |
|
resultCountEstimate |
العدد المقدَّر للنتائج لهذا المصدر |
resultCountExact |
عدد النتائج الدقيقة لهذا المصدر |