- طلب HTTP
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- QueryInterpretationOptions
- تفسير طلبات البحث
- QueryInterpretation.InterpretationType
- QueryInterpretation.السبب
- نتائج البحث
- مقتطف
- مطابقة النطاق
- البيانات الوصفية
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- نتيجة منسّقة
- التدقيق الإملائي
- FacetResult
- دلو الأوجه
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- عدد النتائج
- SourceResultCount
- جرِّبه الآن
توفر واجهة برمجة تطبيقات طلبات البحث في 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 |
سلسلة طلب البحث الأولية. يمكنك الاطّلاع على عوامل تشغيل البحث المتوافقة في القسم تضييق نطاق البحث باستخدام عوامل التشغيل. |
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
لمزيد من المعلومات، راجع نظرة عامة على OAuth 2.0.
خيارات تفسير طلبات البحث
خيارات تفسير طلب بحث المستخدم.
تمثيل JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
الحقول | |
---|---|
disableNlInterpretation |
ضع علامة لإيقاف تفسير اللغة الطبيعية (NL) لطلبات البحث. الإعداد التلقائي هو "خطأ"، ويتم ضبطه على "true" لإيقاف تفسير اللغة الطبيعية. لا ينطبق تفسير NL إلا على مصادر البيانات المحددة مسبقًا. |
enableVerbatimMode |
يمكنك تفعيل هذه العلامة لإيقاف جميع عمليات التحسين الداخلية مثل تفسير اللغة الطبيعية (NL) لطلبات البحث واسترجاع النتائج التكميلية واستخدام المرادفات، بما في ذلك تلك المخصّصة. سيتم إيقاف تفسير Nl إذا كانت إحدى العلامتَين صحيحة. |
disableSupplementalResults |
يمكنك استخدام هذه العلامة لإيقاف النتائج التكميلية لطلب بحث. وتكون الأولوية لإعداد النتائج التكميلية الذي تم اختياره على مستوى SearchApplication في حال ضبطه على "True". |
تفسير طلبات البحث
تمثيل JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
الحقول | |
---|---|
interpretedQuery |
تفسير طلب البحث المستخدَم في البحث. على سبيل المثال، سيتم تفسير طلبات البحث ذات اللغة الطبيعية مثل "email from john" على أنها "from:john source:mail". لن يتم ملء هذا الحقل إذا كان السبب NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
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 ( |
الحقول | |
---|---|
title |
عنوان نتيجة البحث. |
url |
عنوان URL لنتيجة البحث. يحتوي عنوان URL على إعادة توجيه من Google إلى العنصر الفعلي. تم توقيع عنوان URL هذا ويجب عدم تغييره. |
snippet |
تسلسل جميع المقتطفات (الملخصات) المتاحة لهذه النتيجة. |
metadata |
البيانات الوصفية لنتيجة البحث. |
clusteredResults[] |
في حال تجميع المصدر، قدِّم قائمة بالنتائج المجمّعة. سيكون هناك مستوى واحد فقط من النتائج المُجمَّعة. إذا لم يتم تفعيل المصدر الحالي للتجميع، سيكون هذا الحقل فارغًا. |
debugInfo |
تصحيح أخطاء المعلومات المتعلقة بنتيجة البحث هذه. |
مقتطف
مقتطف من نتيجة البحث يلخّص محتوى الصفحة الناتجة
تمثيل JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
الحقول | |
---|---|
snippet |
مقتطف المستند. مقتطف المستند. قد يحتوي على حرف HTML تم تجاوزه يجب إلغاء حروفه قبل العرض. |
matchRanges[] |
النطاقات المطابقة في المقتطف. |
مطابقة النطاق
نطاق مطابق للمقتطف [start، end].
تمثيل 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.ResultDisplayLine
مجموعة الحقول التي تشكّل خطًا معروضًا
تمثيل JSON |
---|
{
"fields": [
{
object ( |
الحقول | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
عرض الحقول لنتائج search.search
تمثيل 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[] |
مجموعات الواجهة للقيم التي تحتوي على نتيجة واحدة على الأقل بالفلتر المقابل. |
دلو الواجهات
إن الحزمة في الواجهة هي الوحدة الأساسية للتشغيل. يمكن أن تتألف الحزمة من قيمة واحدة أو مجموعة من القيم المتجاورة، بناءً على نوع حقل الحزمة المجمّع. يتم حاليًا استخدام FacetBucket لعرض كائن الاستجابة فقط.
تمثيل JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
الحقول | |
---|---|
count |
عدد النتائج التي تطابق قيمة الحزمة. لا يتم عرض الأعداد إلا لعمليات البحث عند ضمان دقة العدد. لا يضمن Cloud Search ظهور الواجهات لأي طلب بحث وقد تظهر أعداد الواجهات بشكل متقطع حتى لطلبات البحث المتطابقة. لا تبني التبعيات على وجود عدد الواجهات، بل استخدم النسب المئوية للواجهة التي يتم عرضها دائمًا بدلاً من ذلك. |
percentage |
النسبة المئوية للنتائج التي تطابق قيمة الحزمة. تتراوح القيمة المعروضة بين (0-100] ويتم تقريبها إلى عدد صحيح إذا كانت كسرية. إذا لم يتم عرض القيمة صراحةً، فإنها تمثّل قيمة مئوية تقرّب إلى الصفر. يتم عرض النسب المئوية لجميع عمليات البحث، ولكنها تقديرية. بما أنّ النسب المئوية يتم عرضها دائمًا، عليك عرض النسب المئوية بدلاً من الأعداد. |
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 |
عدد النتائج لهذا المصدر بالتحديد. |